Create Customer

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": "james.okafor@example.com",
  "phone": "+2348012345678",
  "type": "individual",
  "billing_address": {
    "line1": "123 Test Lane",
    "line2": "Suite 456",
    "city": "Lagos",
    "state": "Lagos",
    "zip_code": "100001",
    "country": "NG"
  }
}

Request Fields

Field	Type	Required	Description
`first_name`	string	Yes	Customer’s first name
`last_name`	string	Yes	Customer’s last name
`email`	string	Yes	Customer’s email address
`phone`	string	Yes	Customer’s phone number (with country code)
`type`	string	Yes	Customer type: `individual` or `business`
`billing_address`	object	Yes	Customer’s billing address

Billing Address Fields

Field	Type	Required	Description
`line1`	string	Yes	Street address line 1
`line2`	string	No	Street address line 2
`city`	string	Yes	City
`state`	string	Yes	State or region
`zip_code`	string	Yes	Postal code
`country`	string	Yes	ISO 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

Field	Type	Description
`id`	string	Unique customer identifier
`status`	string	Customer status (`pending_kyc`, `active`, etc.)
`created_at`	string	Timestamp 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": "james.okafor@example.com",
    "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 Code	Description
`400`	Invalid request or missing required fields
`401`	Unauthorized
`409`	Customer already exists
`422`	Invalid 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

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

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Endpoint

Description

Request Body

Request Fields

Billing Address Fields

Response

Success Response (201 Created)

Response Fields

Example cURL Request

Common Errors

Notes & Best Practices

Typical Flow

​Endpoint

​Description

​Request Body

​Request Fields

​Billing Address Fields

​Response

​Success Response (201 Created)

​Response Fields

​Example cURL Request

​Common Errors

​Notes & Best Practices

​Typical Flow

Endpoint

Description

Request Body

Request Fields

Billing Address Fields

Response

Success Response (201 Created)

Response Fields

Example cURL Request

Common Errors

Notes & Best Practices

Typical Flow