Customers

Create and manage customer profiles, saved payment methods, and KYC status.

Authentication Collections Payouts Customers Balances Webhooks Products Disputes FX Rates

POST/v1/customers

Create a new customer

Parameters

Name	Type	In	Required	Description
`email`	`string`	body	Required	Customer email address
`name`	`string`	body	Optional	Full name
`phone`	`string`	body	Optional	Phone number in E.164 format
`metadata`	`object`	body	Optional	Key-value pairs

Response Codes

201Customer created400Invalid parameters409Email already exists

1{
2  "id": "cus_8a3b7c9d",
3  "object": "customer",
4  "email": "customer@example.com",
5  "name": "Amina Bello",
6  "phone": "+2348012345678",
7  "metadata": { "segment": "enterprise" },
8  "created_at": "2026-05-01T10:00:00Z"
9}

GET/v1/customers/{id}

Retrieve a customer

Parameters

Name	Type	In	Required	Description
`id`	`string`	path	Required	Customer ID

Response Codes

200Customer retrieved404Customer not found

1{
2  "id": "cus_8a3b7c9d",
3  "object": "customer",
4  "email": "customer@example.com",
5  "name": "Amina Bello",
6  "created_at": "2026-05-01T10:00:00Z"
7}

PUT/v1/customers/{id}

Update a customer

Parameters

Name	Type	In	Required	Description
`id`	`string`	path	Required	Customer ID
`name`	`string`	body	Optional	Updated name
`phone`	`string`	body	Optional	Updated phone
`metadata`	`object`	body	Optional	Updated metadata (merges with existing)

Response Codes

200Customer updated404Customer not found

1{
2  "id": "cus_8a3b7c9d",
3  "object": "customer",
4  "email": "customer@example.com",
5  "name": "Amina Bello-Johnson",
6  "metadata": { "segment": "vip" },
7  "updated_at": "2026-05-02T11:00:00Z"
8}