Customers

Customers are verified end consumers of your organization. Create a Customer with BVN, phone, and email, then link a card or direct debit payment method before lending or collection flows that require one.

The Customers API is independent and reusable beyond Debt as a Service. Use it whenever you need a verified end consumer identity under your merchant organization.

Endpoints

POST/customersCreate Customer
GET/customers/{customerId}Get Customer
POST/customers/{customerId}/cardsStart Card Link
GET/customers/{customerId}/cardsGet Card Status
POST/customers/{customerId}/direct-debitsStart Direct Debit Link
GET/customers/{customerId}/direct-debitsGet Direct Debit Status

Create Customer POST/customers

Creates a verified Organization Customer by BVN, or returns the existing Customer for the same organization and BVN.

Request Body

Name
bvn
Type
string
Description
Bank Verification Number. Must be exactly 11 digits.
Name
phone
Type
string
Description
Customer phone in international format with country code only.
Name
email
Type
string
Description
Customer email address.

Names and profile fields are filled from the BVN identity fetch — do not send first_name / last_name.

Phone must be international with country code only (for example +2348012345678). Response BVN is masked.

Creation is idempotent on organization plus BVN.

POST/customers

curl https://api.aellaapp.com/customers \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"bvn":"22122212221","phone":"+2348012345678","email":"john.doe@example.com"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": "cust-uuid",
    "bvn": "22*****221",
    "first_name": "John",
    "last_name": "Doe",
    "gender": "Male",
    "date_of_birth": "1990-01-01",
    "phone": "+2348012345678",
    "email": "john.doe@example.com",
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}

Get Customer GET/customers/{customerId}

Fetches a Customer owned by the authenticated merchant's organization. Response BVN is masked. Internal platform user linkage is not exposed.

Path Parameters

Name
customerId
Type
string
Description
Customer id returned from Create Customer.

GET/customers/{customerId}

curl https://api.aellaapp.com/customers/cust-uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "cust-uuid",
    "bvn": "22*****221",
    "first_name": "John",
    "last_name": "Doe",
    "gender": "Male",
    "date_of_birth": "1990-01-01",
    "phone": "+2348012345678",
    "email": "john.doe@example.com",
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}

Start Card Link POST/customers/{customerId}/cards

Starts a Customer-owned card link. Only one card may be active or pending at a time — if either exists, that method is returned instead of starting another.

Request Body

Name
customerId
Type
string
Description
Customer id returned from Create Customer.

Use data.metadata.authorization_url for checkout when status is pending.

Listen for customer.card.link.successful and customer.card.link.failed, or poll Get Card Status.

POST/customers/{customerId}/cards

curl https://api.aellaapp.com/customers/cust-uuid/cards \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Card link started successfully",
  "data": {
    "id": "pm-uuid",
    "customer_id": "cust-uuid",
    "type": "card",
    "status": "pending",
    "provider_reference": "access-abc",
    "metadata": {
      "authorization_url": "https://checkout.example.com/pay",
      "access_code": "access-abc",
      "email": "john.doe@example.com"
    },
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}

Get Card Status GET/customers/{customerId}/cards

Returns customer-level card link status. Prefers an active card; otherwise the latest card (for polling after Start Card Link).

Path Parameters

Name
customerId
Type
string
Description
Customer id returned from Create Customer.

GET/customers/{customerId}/cards

curl https://api.aellaapp.com/customers/cust-uuid/cards \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Card link status fetched successfully",
  "data": {
    "type": "card",
    "status": "active",
    "provider_reference": "card-xyz",
    "metadata": {
      "authorization_url": "https://checkout.example.com/pay",
      "access_code": "access-abc",
      "email": "john.doe@example.com"
    },
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}

Start Direct Debit Link POST/customers/{customerId}/direct-debits

Creates a Customer-owned direct-debit mandate. Returns a pending payment method. Use data.metadata.instruction for the customer confirmation step.

Request Body

Name
customerId
Type
string
Description
Customer id returned from Create Customer.
Name
account_number
Type
string
Description
Ten-digit Nigerian bank account number.
Name
bank_id
Type
string
Description
Bank id from the mandate banks list (GET /mandates/misc/account/banks).

Listen for customer.direct_debit.link.successful, customer.direct_debit.link.failed, and customer.direct_debit.link.deleted, or poll Get Direct Debit Status.

POST/customers/{customerId}/direct-debits

curl https://api.aellaapp.com/customers/cust-uuid/direct-debits \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"account_number":"0123456789","bank_id":"bank-uuid"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Direct debit link started successfully",
  "data": {
    "id": "pm-uuid",
    "customer_id": "cust-uuid",
    "type": "direct_debit",
    "status": "pending",
    "provider_reference": "mandate-1",
    "metadata": {
      "mandate_reference": "mandate-1",
      "instruction": "Dial *000*00# to confirm",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "amount": "50",
      "confirmation_expires_in_mins": 30,
      "email": "john.doe@example.com"
    },
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}

Get Direct Debit Status GET/customers/{customerId}/direct-debits

Returns customer-level direct-debit link status. Prefers an active mandate; otherwise the latest direct-debit method (for polling after Start Direct Debit Link).

Path Parameters

Name
customerId
Type
string
Description
Customer id returned from Create Customer.

GET/customers/{customerId}/direct-debits

curl https://api.aellaapp.com/customers/cust-uuid/direct-debits \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Direct debit link status fetched successfully",
  "data": {
    "type": "direct_debit",
    "status": "active",
    "provider_reference": "mandate-1",
    "metadata": {
      "mandate_reference": "mandate-1",
      "instruction": "Dial *000*00# to confirm",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "amount": "50",
      "confirmation_expires_in_mins": 30,
      "email": "john.doe@example.com"
    },
    "created_at": "2026-07-27T10:00:00.000Z"
  },
  "status": 200
}