Customers

Status: Available

Customers represent the end-users you transact on behalf of. A customer can be an individual or a business. Linking transactions to a customer keeps your records clean and supports compliance.

The customer object

Field	Type	Description
`id`	string	Our identifier for the customer.
`type`	enum	`individual` or `business`.
`external_ref`	string \| null	Your own ID for this customer. Unique per merchant; use it to deduplicate.
`first_name`	string \| null	Individual's first name.
`last_name`	string \| null	Individual's last name.
`business_legal_name`	string \| null	Registered name (business).
`rc_number`	string \| null	Business registration number.
`email`	string \| null	Contact email.
`phone`	string \| null	Contact phone.
`country`	string \| null	ISO 3166-1 alpha-2 country code.
`metadata`	object \| null	Arbitrary key/values you attach.
`created_at`	string	ISO 8601 timestamp.

Create a customer

POST /v1/customers

curl -X POST {BASE_URL}/v1/customers \
  -H "x-api-key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "external_ref": "user_4821",
    "first_name": "Ada",
    "last_name": "Obi",
    "email": "ada@example.com",
    "country": "NG"
  }'

For a business, send "type": "business" with business_legal_name (and rc_number where applicable) instead of the name fields.

Returns 201 Created with the customer object.

List customers

GET /v1/customers

This endpoint gives the customers of your account.

Get a customer

GET /v1/customers/{customerId}

This endpoint gives one customer. If the customer is not yours, it gives 404.

Update a customer

PATCH /v1/customers/{customerId}

Send only the fields you want to change. Returns the updated customer.

curl -X PATCH {BASE_URL}/v1/customers/cus_123 \
  -H "x-api-key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+2348012345678" }'

Transactions

Webhooks