Skip to main content

​
Endpoint

POST /customers

​
Description

This endpoint provisions a customer in the system. The customer record is required to associate wallets, transactions, and payment methods. After creation, the customer typically starts in a pending_kyc status until verification is completed.

​
Request Body

{
  "first_name": "James",
  "last_name": "Okafor",
  "email": "[email protected]",
  "phone": "+2348012345678",
  "type": "individual",
  "billing_address": {
    "line1": "123 Test Lane",
    "line2": "Suite 456",
    "city": "Lagos",
    "state": "Lagos",
    "zip_code": "100001",
    "country": "NG"
  }
}

​
Request Fields

FieldTypeRequiredDescription
first_namestringYesCustomer’s first name
last_namestringYesCustomer’s last name
emailstringYesCustomer’s email address
phonestringYesCustomer’s phone number (with country code)
typestringYesCustomer type: individual or business
billing_addressobjectYesCustomer’s billing address

​
Billing Address Fields

FieldTypeRequiredDescription
line1stringYesStreet address line 1
line2stringNoStreet address line 2
citystringYesCity
statestringYesState or region
zip_codestringYesPostal code
countrystringYesISO 2-letter country code

​
Response

​
Success Response (201 Created)

{
  "data": {
    "id": "7da75a46-a1bc-11ee-9a32-560f156a658b",
    "status": "pending_kyc",
    "created_at": "2025-09-22T09:01:09Z"
  }
}

​
Response Fields

FieldTypeDescription
idstringUnique customer identifier
statusstringCustomer status (pending_kyc, active, etc.)
created_atstringTimestamp when the customer was created

​
Example cURL Request

curl -X POST https://api.yourdomain.com/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "James",
    "last_name": "Okafor",
    "email": "[email protected]",
    "phone": "+2348012345678",
    "type": "individual",
    "billing_address": {
      "line1": "123 Test Lane",
      "line2": "Suite 456",
      "city": "Lagos",
      "state": "Lagos",
      "zip_code": "100001",
      "country": "NG"
    }
  }'

​
Common Errors

Status CodeDescription
400Invalid request or missing required fields
401Unauthorized
409Customer already exists
422Invalid field values

​
Notes & Best Practices

  • Ensure all mandatory fields are provided and formatted correctly.
  • The status starts as pending_kyc if verification is required.
  • Store the returned id as it is needed to create wallets and associate transactions.
  • Validate emails and phone numbers to prevent errors in subsequent wallet creation.

​
Typical Flow

  1. Create a customer via POST /customers.
  2. Verify customer if required (KYC).
  3. Create a wallet for the customer using POST /wallets.
  4. Add payment methods and perform transactions as needed.