neo-pays

Collection accounts

Generated page, from the OpenAPI specification the gateway serves (GET /v1/openapi.json). Do not edit it by hand: it is rewritten on every build.

Method Path Description
POST /v1/collection-accounts Create a virtual IBAN for a partner system's customer
GET /v1/collection-accounts/{account_ref} Read a collection account
GET /v1/collection-accounts/{account_ref}/rib Download the RIB (PDF)

POST /v1/collection-accounts

Create a virtual IBAN for a partner system's customer

Restricted to omnibus SYSTEM CLIENTS (neo-card, neo-tpe). An ordinary merchant has no access to it: their own account is created automatically on KYB approval and is read in the dashboard.

The identities passed here are REQUIRED BY THE BANK in order to open an account. neo-pays passes them on and keeps nothing: no partner-system customer is recorded with us, in any form.

⚠️ Keep the ncp returned: every later operation addresses it, and neo-pays holds no record that would let you find it again.

⚠️ On a 409 ambiguous_create response, DO NOT RETRY: an account may exist at the bank. This API has no idempotency key, and a second attempt would create a second real account.

Request body

Field Type Required Description
customer_ref string yes YOUR identifier for this customer. It becomes the matricule, the only thing that will bring received transfers back to you. Opaque to neo-pays.
nom string yes Family name. Required by the bank.
prenom string no
adresse string no
country string no ISO alpha-2. Must be within the configured coverage (SN).
provider_id string no Optional. The institution that should open the account, as a stable code (for example afrikabanque). Omitted, it is the institution configured on this deployment; an unconfigured code is REFUSED and never silently swapped for another.

Responses

  • 201 — Account created (object)
  • 400 — Invalid request
  • 403 — This client is not an omnibus system client
  • 409 — Outcome UNKNOWN — do not retry
  • 503 — The bank is unreachable

GET /v1/collection-accounts/{account_ref}

Read a collection account

Returns the account's status and, once the bank has finished with it, its IBAN. A mint returns only a reference: the bank generates the RIB on its own schedule and the IBAN is derived from it, so this is how the IBAN is ever learned. usable means the account is active AND carries a RIB — an active account with no RIB is the ordinary mid-flight state, and is not something to act on. Address the account by the account_ref the mint returned.

Parameters

Name In Required Description
account_ref path yes OUR reference for the account, as creation returned it. It must start with YOUR namespace (for example neocard-) followed by the 12 digits; naming an account outside your namespace is refused. It replaces the institution's ncp, which is no longer accepted in a path.

Responses

  • 200 — The bank's known state. (object)

GET /v1/collection-accounts/{account_ref}/rib

Download the RIB (PDF)

Parameters

Name In Required Description
account_ref path yes OUR reference for the account, as creation returned it. It must start with YOUR namespace (for example neocard-) followed by the 12 digits; naming an account outside your namespace is refused. It replaces the institution's ncp, which is no longer accepted in a path.

Responses

  • 200 — The PDF, as-is (file)
  • 403 — This account belongs to a neo-pays merchant
  • 503 — The bank is unreachable