Mandates

Set up, manage, and charge direct debit mandates on your customers' bank accounts. If you provide a subscription-based service, use our Mandates API to automatically collect your monthly subscription fees direct from your customer bank account. You'll get a mandate.debit.successful webhook for easy reconciliation.

Stop chasing payments. With mandates, your customers authorize you to automatically debit their bank accounts for recurring payments. Whether it's monthly subscriptions, loan repayments, or regular service fees—mandates handle it all automatically. No more failed payments, no more manual follow-ups. Just set it once, and let the API handle the rest.

Misc

Resolve Account

This endpoint resolves account information for mandate creation.

Verify accounts before creating mandates

Before creating a mandate, you'll want to verify the account details. This endpoint checks if the account exists, retrieves the account name, and validates the information—helping you prevent errors and build trust with your customers.

Common use cases

Pre-mandate validation: Verify account details before creating a mandate to ensure the account is valid and active.
Account name display: Show customers the account name that will be debited, building trust and reducing errors.
Form validation: Validate account information in real-time as customers enter their details.
Error prevention: Catch invalid accounts before attempting to create mandates, reducing failed mandate creation attempts.

Query Parameters

Name
accountNumber
Type
string
Description
The account number to resolve.
Name
bankId
Type
string
Description
The bank ID for the account.

Request

GET

/mandates/misc/account/resolve

curl "https://api.aellaapp.com/mandates/misc/account/resolve?accountNumber=0480819436&bankId=058" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "destinationInstitutionCode": "000013",
    "bankVerificationNumber": "1234567890",
    "accountNumber": "0480819436",
    "accountName": "John Doe",
    "kycLevel": 1
  },
  "status": 200
}

Get Banks

This endpoint retrieves a list of supported banks for mandate creation.

Know which banks support mandates

Not all banks support direct debit mandates. This endpoint gives you the complete list of banks that do, so you can show customers the right options and prevent failed mandate creation attempts.

Common use cases

Bank selection dropdown: Display only supported banks in your mandate setup form.
Validation: Check if a customer's bank supports mandates before allowing them to proceed.
User guidance: Show customers which banks they can use for mandate setup.
Error prevention: Prevent mandate creation attempts for unsupported banks.

Request

GET

/mandates/misc/account/banks

curl https://api.aellaapp.com/mandates/misc/account/banks \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "banks": [
      {
        "id": "019059fc-a473-7778-9cc4-078dd1fb5970",
        "name": "Guaranty Trust Bank",
        "bank_code": "058",
        "institution_code": "000013"
      }
    ],
    "total": 37
  },
  "status": 200
}

POST/mandates/manual

Create Manual Mandate

This endpoint creates a new direct debit mandate for a customer. The mandate will need to be confirmed before it can be used for debits.

Set up recurring payments

Create a mandate that allows you to automatically debit a customer's bank account. Once created and confirmed, you can charge the customer's account whenever needed—perfect for subscriptions, loan repayments, or any recurring payment scenario.

Common use cases

Subscription services: Set up mandates for monthly or yearly subscription payments (SaaS, streaming services, gym memberships).
Loan repayments: Automate loan repayment collections from borrowers' accounts.
Utility bills: Enable automatic payment of recurring utility bills (electricity, water, internet).
Insurance premiums: Collect monthly or annual insurance premium payments automatically.
Savings plans: Set up automatic savings deductions from customer accounts.
Membership fees: Automate collection of club, association, or membership fees.
Investment contributions: Collect regular investment contributions automatically.

How it works

Create the mandate: Use this endpoint to create a mandate with customer and bank account details.
Customer confirmation: The customer needs to confirm the mandate (usually via a token payment).
Start debiting: Once confirmed and active, you can debit the account using the Debit Mandate endpoint.

Request Body

Name
customer
Type
object
Description
Customer information object containing:
- firstName (string): Customer's first name
- lastName (string): Customer's last name
- homeAddress (string): Customer's home address
- email (string): Customer's email address
- phoneNumber (string): Customer's phone number
- bvn (string): Customer's Bank Verification Number
- externalReference (string, optional): Unique external reference for the customer
Name
bankAccount
Type
object
Description
Bank account information object containing:
- bankId (string): The bank ID
- accountNumber (string): The account number

Request

POST

/mandates/manual

curl https://api.aellaapp.com/mandates/manual \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "firstName": "Gboluwaga",
      "lastName": "Adeyemi",
      "homeAddress": "5 Olufunmilola Okikiolu Street, Ikeja, Lagos",
      "email": "gadeyemi@aellacredit.com",
      "phoneNumber": "2349046717109",
      "bvn": "22334455666",
      "externalReference": "my-unique-id"
    },
    "bankAccount": {
      "bankId": "058",
      "accountNumber": "0480819436"
    }
  }'

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "mandate": {
      "id": "2736c574-eb5c-4d96-9c28-33848b830866",
      "confirmationStatus": "PENDING",
      "status": "INACTIVE",
      "bankAccount": {
        "id": "a50ca816-7b19-40a6-b22a-45a46dd3026e"
      },
      "created_at": "2025-02-18T12:20:27.290Z"
    },
    "instruction": "Welcome to NIBSS e-mandate authentication service, a seamless and convenient authentication experience. Kindly proceed with a token payment of N50:00 into account number \"9880218357\" with Titan-Paystack Bank. This payment will trigger the authentication of your mandate. Thank You.",
    "meta": {
      "accountNumber": "0000000000",
      "bankName": "Paystack Titan",
      "amount": "50.00"
    }
  },
  "status": 200
}

GET/mandates/:id

Get Mandate

This endpoint retrieves the details of a specific mandate.

Check mandate status and details

Need to know if a mandate is active, confirmed, or ready to use? This endpoint gives you all the details—status, confirmation status, creation date, and more. Perfect for checking mandate health before attempting debits.

Common use cases

Status checks: Verify if a mandate is active and confirmed before processing a debit.
Customer support: Look up mandate details when customers ask about their recurring payment setup.
Dashboard displays: Show mandate status in customer or admin dashboards.
Reconciliation: Retrieve mandate information for accounting and reporting.
Pre-debit validation: Check mandate status before attempting to debit to avoid failures.

Mandate statuses

PENDING: Mandate created but not yet confirmed by the customer.
CONFIRMED: Customer has confirmed the mandate, and it's ready to use.
ACTIVE: Mandate is active and can be used for debits.
INACTIVE: Mandate is inactive and cannot be used for debits.

Path Parameters

Name
id
Type
string
Description
The unique identifier of the mandate.

Request

GET

/mandates/{id}

curl https://api.aellaapp.com/mandates/2736c574-eb5c-4d96-9c28-33848b830866 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "id": "2736c574-eb5c-4d96-9c28-33848b830866",
    "confirmationStatus": "CONFIRMED",
    "status": "ACTIVE",
    "bankAccount": {
      "id": "a50ca816-7b19-40a6-b22a-45a46dd3026e"
    },
    "created_at": "2025-02-18T12:20:27.290Z"
  },
  "status": 200
}

POST/mandates/manual/:id/debit

Debit Mandate

This endpoint initiates a debit from a confirmed mandate. The mandate must be in ACTIVE status and CONFIRMED before debits can be processed.

The moment of truth—collecting payments

This is where the magic happens. Once a mandate is active and confirmed, use this endpoint to debit the customer's account. The money is automatically collected and you'll receive a webhook notification when it's successful.

Common use cases

Monthly subscriptions: Automatically charge customers on their billing date.
Loan repayments: Collect scheduled loan repayments from borrowers.
Utility bill payments: Charge customers for their monthly utility usage.
Insurance premiums: Collect recurring insurance premium payments.
Membership renewals: Automatically charge membership fees when they're due.
Installment payments: Collect installment payments for purchases or services.
Late fees: Charge late fees or penalties when applicable.

Best practices

Check status first: Always verify the mandate is ACTIVE and CONFIRMED before debiting.
Handle failures gracefully: Some debits may fail (insufficient funds, account closed, etc.). Have retry logic and notify customers.
Use clear narrations: The narration appears on the customer's bank statement, so make it clear and recognizable.
Monitor webhooks: Listen for mandate.debit.successful and mandate.debit.failed webhooks to track payment status.

Path Parameters

Name
id
Type
string
Description
The unique identifier of the mandate.

Request Body

Name
amount
Type
number
Description
The amount to debit from the mandate.
Name
narration
Type
string
Description
A description or reason for the debit.

Request

POST

/mandates/manual/{id}/debit

curl https://api.aellaapp.com/mandates/manual/2736c574-eb5c-4d96-9c28-33848b830866/debit \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "narration": "Subscription payment"
  }'

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "id": "d864a9cc-e97b-421b-b29b-3240006ec193",
    "narration": "Aella Loan Repayment",
    "amount": "2000",
    "status": "pending",
    "mandate": {
      "id": "2736c574-eb5c-4d96-9c28-33848b830866"
    },
    "provider": {
      "id": "98a8be86-77f7-41a7-ada8-d7a5d5a95d80"
    },
    "created_at": "2025-02-18T12:34:00.629Z"
  },
  "status": 200
}

GET/mandates/transaction/:id/status-query

Transaction Query

This endpoint retrieves the status of a specific transaction associated with a mandate. It allows you to query the current status and details of a transaction by providing the unique transaction identifier.

Track individual debit transactions

After initiating a debit, you'll want to know if it succeeded or failed. This endpoint gives you the real-time status of any mandate debit transaction, including response codes and final status.

Common use cases

Status polling: Check transaction status if webhooks are delayed or missed.
Customer support: Look up specific transaction status when customers inquire about payments.
Reconciliation: Verify transaction status for accounting and reporting.
Retry logic: Check if a pending transaction has completed before retrying.
Dispute resolution: Retrieve transaction details when resolving payment disputes.
Reporting: Generate reports on successful and failed debit transactions.

Transaction statuses

pending: Transaction is being processed.
successful: Payment was successfully collected from the customer's account.
failed: Transaction failed (check response codes for reasons).

Path Parameters

Name
id
Type
string
Description
The unique identifier of the transaction for which the status is being queried.

Request

GET

/mandates/transaction/{id}/status-query

curl https://api.aellaapp.com/mandates/transaction/be998b79-0aea-479c-8c30-92bc57141d23/status-query \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "id": "be998b79-0aea-479c-8c30-92bc57141d23",
    "amount": 2000,
    "status": "successful",
    "finalResponseCode": "00",
    "narration": "Subscription payment",
    "providerId": "4742c3f9-7577-4b5a-95a2-01d56efa4d6e",
    "mandateId": "a6f9ca43-7471-4bb1-bdda-5e0e79d624b0",
    "sessionId": "791948536692084308074810130927",
    "responseCode": "00",
    "createdAt": "2025-08-30T13:00:51.341Z"
  },
  "status": 200
}

Response Codes Reference

Success Codes

00 - Approved or completed successfully

Processing & Status Codes

01 - Status unknown, kindly reach out to us to resolve this transaction
09 - In progress: Your request is currently being processed. Please wait for confirmation or contact customer support for further assistance
21 - No action taken

Account & Authentication Errors

03 - Invalid Sender; beneficiary does not exist, kindly check the account details
06 - Error: Transfer unsuccessful. The recipient account is inactive. Please contact the beneficiary for further assistance
07 - Error: Account is invalid. Please check the account number and try again
08 - Account name mismatch. The name on the account does not match the provided information. Please verify the information and try again

Transaction & Request Errors

05 - Payment processing error: Please try again later or contact customer support for assistance
12 - Invalid transaction. Please check the details and try again
13 - Invalid amount. Please enter a valid amount and try again
51 - Insufficient funds