Africa Fintech FoundryDeveloper Portal
Get API keys
Wallet · Partner API

Onboarding & tiers

From nothing to an open Tier 1 wallet in three calls — validate the person, poll the verification, create the account. Tier 2 is a document upload the bank reviews.

POST

Authenticate

/Merchant/authenticate
Exchange your merchant credentials for a Bearer token, and send it on every call that follows. Tokens live for an hour — refresh before expiryDate, not after your first 401.
// credentials travel as headers — there is no request body
POST

Validate a customer

/Onboarding/validate
Starts the identity check against the BVN and NIN. The result is not in this response — poll verificationStatus until it settles.
Parameters
merchantIdstringrequiredYour merchant id.
requestIdstringrequiredYour unique reference for this onboarding run.
bvnstringrequiredThe customer's BVN.
ninstringrequiredThe customer's NIN.
titlestringMr, Ms, and so on.
nationalitystringrequiredISO country code, e.g. NG.
dataConsentbooleanrequiredThe customer's consent to the identity check.
polPartyOfficial … closeAssociatePepboolean + string pairsThe PEP self-declaration block: political, government, military, royal and international-organisation flags, each with a free-text detail field.
// request — PEP flags omitted for brevity
{
  "merchantId": "MRC-YABA-01",
  "requestId": "ONB-20260715-0007",
  "bvn": "22212345678",
  "nin": "70123456789",
  "title": "Ms",
  "nationality": "NG",
  "dataConsent": true
}
GET

Verification status

/Onboarding/verificationStatus
Poll until the check settles. The spec declares verificationStatus as a bare string and names no values — expect at least VERIFIED, PENDING and FAILED, and treat anything else as pending.
// no parameters — the status is scoped to your merchant session
POST

Create the account

/Onboarding/createAccount
Opens the Tier 1 wallet once verification has passed. accountNo is the wallet NUBAN every other operation uses. Called too early, it answers with status PENDING and an empty account number.
Parameters
merchantIdstringrequiredYour merchant id.
requestIdstringrequiredThe same reference you sent to validate.
processIdstringrequiredFrom the validate response.
userSignaturestringrequiredThe customer's signature image, base64.
// request
{
  "merchantId": "MRC-YABA-01",
  "requestId": "ONB-20260715-0007",
  "processId": "PRC-000031",
  "userSignature": "iVBORw0KGgoAAA…"
}
GET

Requery account creation

/Onboarding/requeryAccountCreation
The recovery call for a creation that hangs: it nudges a pending creation through. Fire it before you retry createAccount from scratch.
// 200 — the spec declares no response body
POST

Update customer details

/Onboarding/updateCustomerDetails
Amends the customer’s contact and address records. The spec confirms nothing back — read the wallet afterwards if you need proof the change took.
// 200 — the spec declares no response body
POST

Upgrade to Tier 2

/Onboarding/upgradeAccount
Submits the Tier 2 request. It is not instant: bank operations reviews the documents, and the outcome arrives out of band — higher limits on approval, or a rejection the customer has to fix and resubmit.
Form fields (multipart)
IdTypestringrequiredThe identity document type.
IdNostringrequiredThe document number.
documentsfile[]requiredDocument images — front, back, selfie.
// multipart form — files travel as parts, not JSON
IdType=NIN_SLIP
IdNo=70123456789