> ## Documentation Index
> Fetch the complete documentation index at: https://partners.ladder.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct-debit mandates

> Let Ladder pull NGN from one of your settlement accounts under a NIBSS e-mandate, approved once by the account's signatory.

A mandate lets Ladder debit one of your NGN settlement accounts without a payment step per request. It is a NIBSS e-mandate taken through Ladder's bank partner and approved once by the signatory of the account.

<Steps>
  <Step title="Create the mandate">
    `POST /mandates` with the settlement account and the maximum amount per debit. The response is `pending` and tells the signatory exactly what to do:

    ```json Request theme={null}
    {"settlement_account_id": "e9a31846-e4b7-4058-b71f-bfa21e9b8129", "limit_amount": "50000"}
    ```

    ```json Response theme={null}
    {
      "data": {
        "id": "978b8c25-10c8-40e9-b110-454168a399bb",
        "reference": "LPM_7d24ee5a55df4f72a5f0",
        "status": "pending",
        "currency": "NGN",
        "bank_code": "044",
        "bank_name": "Access Bank",
        "account_number_masked": "******0031",
        "account_name": "Harbour Point Asset Management Limited",
        "limit_amount": "50000.0000",
        "provider": "flutterwave",
        "provider_reference": "URF_EMANDATE_1791794810710_32555",
        "activation": {
          "amount": "100.0000",
          "currency": "NGN",
          "bank_name": "…",
          "account_number": "8242474919",
          "account_name": "FLUTTERWAVE MANDATE ACTIVATION",
          "instructions": "Kindly proceed with a token payment of N100:00 into account number 8242474919 … You have 10 minutes to complete this payment."
        },
        "activated_at": null,
        "revoked_at": null,
        "last_debit_at": null,
        "failure_reason": ""
      }
    }
    ```
  </Step>

  <Step title="The signatory activates it">
    The signatory makes the token payment named in `activation` **from the mandated account**. The bank confirms, the mandate becomes `active`, `activation` becomes `null`, and you receive `mandate.activated`.

    `activated_at` is the moment the bank token becomes usable, typically about a minute after approval. A debit requested before it returns `409 mandate_not_yet_active` with `activated_at` in `details`; retry then.
  </Step>

  <Step title="Fund by direct debit">
    `POST /wallets/NGN/fund` with `"method": "flutterwave_direct_debit"`. Amounts above `limit_amount` are refused (`400 mandate_limit_exceeded`). The request settles from the bank's confirmation like any other funding request and fires `wallet.funded`; the wallet is credited with the requested amount, never with any fee the bank adds on top.
  </Step>

  <Step title="Revoke when done">
    `POST /mandates/{id}/revoke` ends it; the token is deleted at the bank partner and no further debit is possible (`409 mandate_required`). A revoked mandate stays revoked even if a late approval arrives from the bank.
  </Step>
</Steps>

## Rules

* One pending or active mandate per settlement account (`409 mandate_exists`).
* A `failed` mandate carries the bank partner's reason in `failure_reason` and does not block a new attempt.
* The settlement account needs a `bank_code`; add it when you register the account.
* Sandbox mandates are active immediately and debits settle through the sandbox endpoint.

## Status flow

```
pending ──signatory pays the activation token──▶ active ──POST /revoke──▶ revoked
pending ──bank declines──▶ failed
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.