Overview

A customer is either an individual or business entity that can be issued a payment card. Endpoints

Method	Url
`POST`	/customers
`GET`	/customers
`GET`	/customers/:id
`PUT`	/customers/:id
`PUT`	/customers/:id/documents/url

Validation When you create or update a customer, the fields you send are checked. Nothing below is required unless you send it, so customers for NGN cards only can still be created without them. If anything fails, nothing is saved and the response lists every problem in one message.

Field	Rule
`firstName`, `lastName`	2 to 20 characters each, for the individual or the company officer. Spaces at either end aren’t counted.
`phoneNumber`	7 to 15 digits, optionally starting with `+` and the country code. Spaces, dashes and brackets are allowed.
`emailAddress`	A valid email address.
`billingAddress.country`	A country name or ISO code, such as `Nigeria`, `NG` or `NGA`.
`dob`	`YYYY-MM-DD` (`YYYY/MM/DD` is also accepted), a real date, not in the future.
`identity.number`	A `BVN` must be 11 digits, a Nigerian `NIN` 11 digits, and a `PASSPORT` number 6 to 9 letters or digits.
`documents.idFrontUrl`, `documents.idBackUrl`	A public https link straight to a JPEG, PNG or WebP image of up to 10 MB. The file itself is checked, so its name or extension doesn’t matter.

When you update individual or company, any field you leave out, such as identity, dob or documents, keeps its stored value. USD card requirements USD virtual cards (MasterCard and Visa) are issued by our card partner, who verifies the customer (KYC). Everything below is checked before the customer is charged, when a card is created and when it’s reissued. If anything is missing, nothing is charged, the card partner isn’t contacted, and the response lists every problem at once. Every USD card needs:

a valid phone number for its country (see below) and a valid email address
a first and last name of 2 to 20 characters each: the individual’s, or for a company, the officer’s (a company must have an officer)
if a date of birth is saved, a real date that isn’t in the future
one accepted identity, with what that identity needs:

`identity.type`	Saved on	Sent to the card partner as	Also needs
`BVN`	`individual` or `company.officer`	BVN	11 digits. A Nigerian billing address and a Nigerian phone number (see below).
`NIN` (Nigerian, 11 digits)	`individual` or `company.officer`	NIN	A date of birth. A Nigerian billing address and a Nigerian phone number.
`NIN` (other countries, such as a Ghana card)	`individual` or `company.officer`	National ID	A recognised billing country. An ID image in `documents.idFrontUrl`.
`PASSPORT`	`individual` or `company.officer`	International passport	6 to 9 letters or digits. A recognised billing country. An ID image in `documents.idFrontUrl`.
`DL` (driver’s licence)	`individual` or `company.officer`	Driver’s licence	A recognised billing country. An ID image in `documents.idFrontUrl`.
`VC` (voter’s card)	`individual` or `company.officer`	Voter’s card	A recognised billing country. An ID image in `documents.idFrontUrl`.
`RC` (resident card)	`individual` or `company.officer`	Resident card	A recognised billing country. An ID image in `documents.idFrontUrl`.
`CAC`	`company.identity` only	Company registration (RC) number, with the company `name` as the business name	The company `name`. An image of the CAC certificate in `company.documents.incorporationCertificateUrl`.

TIN can’t be used for USD cards. A CAC number saved on an individual or on the officer isn’t accepted; put it on company.identity. When a company has a CAC number on company.identity, that is what’s sent, and the officer’s name and date of birth are used as the cardholder’s. Phone number: the card partner only accepts numbers in international format, so we send it as + and the country code, for example +2348031234567. Save numbers that way to be sure. If a number is saved without its country code, we read it as a number from the billing country (Nigeria for a BVN, NIN or CAC): 08031234567 and 8031234567 become +2348031234567, and 00 is read as + (0022237877557 becomes +22237877557). If the result isn’t a valid number for that country, the card is refused before the customer is charged. A number from a different country than the billing address must be saved with its country code. The saved customer isn’t changed. Nigerian phone number: a BVN or Nigerian NIN needs a phone number that is Nigerian (+234) after the steps above. Spaces, dashes and brackets are fine. ID images: a public https link straight to a JPEG, PNG or WebP image of up to 10 MB, with no redirects. The image is downloaded again when the card is created, so the link must still work then. Use Generate Customer Document URL for a link that doesn’t expire. Unless skipKYC is sent with the card request, a USD card also needs a date of birth and, for any identity other than a BVN, both documents.idFrontUrl and documents.idBackUrl. If these are missing, the response is Update customer details. Customer phone number, email address and identity details are required.

{
    "type": "individual",
    "name": "Ada Obi",
    "phoneNumber": "+2348031234567",
    "emailAddress": "ada@example.com",
    "status": "active",
    "individual": {
        "firstName": "Ada",
        "lastName": "Obi",
        "dob": "1990-05-12",
        "identity": { "type": "BVN", "number": "22212345678" }
    },
    "billingAddress": { "line1": "12 Admiralty Way", "city": "Lagos", "state": "Lagos", "country": "NG", "postalCode": "101233" }
}

{
    "type": "individual",
    "name": "Amina Yusuf",
    "phoneNumber": "+254712345678",
    "emailAddress": "amina@example.com",
    "status": "active",
    "individual": {
        "firstName": "Amina",
        "lastName": "Yusuf",
        "dob": "1992-08-30",
        "identity": { "type": "PASSPORT", "number": "B03056098" },
        "documents": {
            "idFrontUrl": "https://example.com/kyc/passport-front.jpg",
            "idBackUrl": "https://example.com/kyc/passport-back.jpg"
        }
    },
    "billingAddress": { "line1": "14 Moi Avenue", "city": "Nairobi", "state": "Nairobi", "country": "KE", "postalCode": "00100" }
}

{
    "type": "company",
    "name": "Acme Trading Ltd",
    "phoneNumber": "+2348091234567",
    "emailAddress": "ops@acme.com",
    "status": "active",
    "company": {
        "name": "Acme Trading Ltd",
        "identity": { "type": "CAC", "number": "RC1234567" },
        "documents": { "incorporationCertificateUrl": "https://example.com/kyc/cac-certificate.png" },
        "officer": {
            "firstName": "Ngozi",
            "lastName": "Okafor",
            "dob": "1985-02-01",
            "identity": { "type": "BVN", "number": "22211122233" }
        }
    },
    "billingAddress": { "line1": "12 Admiralty Way", "city": "Lagos", "state": "Lagos", "country": "NG", "postalCode": "101233" }
}

If the customer doesn’t qualify, the card request returns a message like this, listing every problem:

{
    "statusCode": 400,
    "message": "This customer can't get a USD card yet. Missing or invalid: a Nigerian billing address (required for a BVN); a Nigerian phone number starting with +234, 234 or 0 (required for a BVN)."
}

Listed after “Missing or invalid:“	How to fix it
`phone number` / `a valid phone number with its country code, such as +2348031234567`	Update `phoneNumber`, ideally in international format.
`a valid email address`	Update `emailAddress`.
`first and last name (2 to 20 characters each)` / `the officer's first and last name …`	Update `firstName` and `lastName` (on `company.officer` for a company).
`a company officer`	Add `company.officer`.
`an identity` / `the company's CAC number or the officer's identity`	Add an accepted identity.
`… (TIN can't be used for USD cards)`	Use one of the accepted identity types.
`the CAC number on company.identity, not the officer's identity` / `… (CAC can only be used for a company)`	Move the CAC number to `company.identity`.
`an identity number`, `a BVN of 11 digits`, `a Nigerian NIN of 11 digits`, `a passport number of 6 to 9 letters or digits`	Correct `identity.number`.
`a Nigerian billing address (required for a BVN)`	Use a Nigerian billing address, or a different identity.
`a Nigerian phone number starting with +234, 234 or 0 (required for a BVN)`	Use a Nigerian phone number, or a different identity.
`a recognised billing address country`	Update `billingAddress.country`.
`date of birth (required for a NIN)` / `a real date of birth, not in the future`	Update `dob`.
`an ID image (idFrontUrl)`	Add `documents.idFrontUrl`.
`a CAC certificate image (company.documents.incorporationCertificateUrl)`	Add `company.documents.incorporationCertificateUrl`.
`a company name (required with a CAC number)`	Add `company.name`.
`idFrontUrl could not be downloaded (HTTP 404) …`, `… must be a JPEG, PNG or WebP image …`, `… must be 10 MB or smaller`	Replace the link with a working public link to a JPEG, PNG or WebP image of up to 10 MB.

Customers

Funding Sources

Card Programs

Cards

Accounts

Authorizations

Transactions

Disputes

Simulator (Sandbox Only)

Overview