API reference

Payout accounts

Bank or PayPal destinations a user can be paid out to.

List a user's payout accounts

GET/v1/users/{user_id}/payout_accounts

Returns a page of PayoutAccount objects.

Path parameters

user_idstringrequired: Starts with usr_.

Query parameters

limitinteger: Default 10.
starting_afterstring: Cursor; an object ID. Returns the page after it. Cannot be combined with ending_before.
ending_beforestring: Cursor; an object ID. Returns the page before it. Cannot be combined with starting_after.

Responses

200A page of payout accounts.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/payout_accounts" \
  -H "Api-Key: $NDEIPI_API_KEY"

Response 200

{
  "data": [
    {
      "id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY",
      "object": "payout_account",
      "user_id": "usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T",
      "type": "bank",
      "currency": "zar",
      "country": "ZA",
      "rail": "absa_eft",
      "account_owner_name": "Tendai Ncube",
      "bank": {
        "bank_name": "Absa Bank",
        "account_number_last4": "4567",
        "routing_code": "632005",
        "account_type": "checking"
      },
      "status": "active",
      "name_check": "not_supported",
      "metadata": {},
      "version": 1,
      "created_at": "2026-10-16T09:30:00Z"
    }
  ],
  "has_more": false
}

Register a payout account

POST/v1/users/{user_id}/payout_accounts

Registers a bank or mobile-money destination. Details are validated for their rail at creation; failures return 422 validation_failed with one entry per field in details. Account and phone numbers are returned masked.

Returns PayoutAccount.

Path parameters

user_idstringrequired: Starts with usr_.

Headers

Idempotency-Keyheaderrequired: A unique key for this write, up to 255 characters. Send the same key to retry safely; see idempotency.

Body

typestringrequired

Which rails serve each type is data on GET /routes. In 1.0, bank is paid by Absa (absa_eft) and paypal by PayPal. No mobile_money rail has a provider yet.

One of bank, mobile_money, paypal.

currencystringrequired

Lower-case ISO 4217 fiat currency code.

countrystringrequired

ISO 3166-1 alpha-2 country code.

railstringrequired

A payment rail code, published by GET /routes. Not an enum by design.

account_owner_namestringrequired

Screened against sanctions lists and, where the rail supports it, checked against the account.

bankobject

Required when type is bank.

bank.bank_namestringrequired

bank.account_numberstringrequired

bank.routing_codestring

Branch

bank.swift_bicstring

bank.account_typestring

One of checking, savings, other.

mobile_moneyobject

Required when type is mobile_money.

mobile_money.providerstringrequired

mobile_money.phone_numberstringrequired

paypalobject | object

Required when type is paypal.

paypal.emailstring

paypal.phonestring

metadataobject

Integrator key-value data, returned unchanged. Up to 50 keys; keys up to 40 characters, values up to 500.

Responses

201Payout account registered.
400The request is malformed.
401The API key is missing, invalid or revoked.
403The key may not perform this action, or the user is not approved.
404The object does not exist or belongs to another integrator.
422The request is well formed but fails validation or a business rule.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X POST "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/payout_accounts" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank",
    "currency": "zar",
    "country": "ZA",
    "rail": "absa_eft",
    "account_owner_name": "Tendai Ncube",
    "bank": {
      "bank_name": "Absa Bank",
      "account_number": "4091234567",
      "routing_code": "632005",
      "account_type": "checking"
    }
  }'

Response 201

{
  "id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY",
  "object": "payout_account",
  "user_id": "usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T",
  "type": "bank",
  "currency": "zar",
  "country": "ZA",
  "rail": "absa_eft",
  "account_owner_name": "Tendai Ncube",
  "bank": {
    "bank_name": "Absa Bank",
    "account_number_last4": "4567",
    "routing_code": "632005",
    "account_type": "checking"
  },
  "status": "active",
  "name_check": "not_supported",
  "metadata": {},
  "version": 1,
  "created_at": "2026-10-16T09:30:00Z"
}

Get a payout account

GET/v1/users/{user_id}/payout_accounts/{payout_account_id}

Returns PayoutAccount.

Path parameters

user_idstringrequired: Starts with usr_.
payout_account_idstringrequired: Starts with pa_.

Responses

200The payout account.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/payout_accounts/pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY" \
  -H "Api-Key: $NDEIPI_API_KEY"

Response 200

{
  "id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY",
  "object": "payout_account",
  "user_id": "usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T",
  "type": "bank",
  "currency": "zar",
  "country": "ZA",
  "rail": "absa_eft",
  "account_owner_name": "Tendai Ncube",
  "bank": {
    "bank_name": "Absa Bank",
    "account_number_last4": "4567",
    "routing_code": "632005",
    "account_type": "checking"
  },
  "status": "active",
  "name_check": "not_supported",
  "metadata": {},
  "version": 1,
  "created_at": "2026-10-16T09:30:00Z"
}

Delete a payout account

DELETE/v1/users/{user_id}/payout_accounts/{payout_account_id}

Removes the account as a destination for new transfers. Transfers already submitted to it complete or are returned as normal. Returns 409 payout_account_in_use while an off-ramp to it is in pending.

Returns PayoutAccount.

Path parameters

user_idstringrequired: Starts with usr_.
payout_account_idstringrequired: Starts with pa_.

Responses

200The deleted payout account.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
409The request conflicts with the object's current state or an earlier request.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X DELETE "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/payout_accounts/pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY" \
  -H "Api-Key: $NDEIPI_API_KEY"

Response 200

{
  "id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY",
  "object": "payout_account",
  "user_id": "usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T",
  "type": "bank",
  "currency": "zar",
  "country": "ZA",
  "rail": "absa_eft",
  "account_owner_name": "Tendai Ncube",
  "bank": {
    "bank_name": "Absa Bank",
    "account_number_last4": "4567",
    "routing_code": "632005",
    "account_type": "checking"
  },
  "status": "deleted",
  "name_check": "not_supported",
  "metadata": {},
  "version": 2,
  "created_at": "2026-10-16T09:30:00Z"
}