​
Customers API

The Customers API allows you to create and manage customer information. Storing customer data makes it easier to process payments and track customer activity.

​
The Customer Object

{
  "id": "cus_123456789",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+237600000000",
  "metadata": {},
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}

​
Customer Object Properties

​
id
string
Unique identifier for the customer
​
name
string
Customer’s full name
​
email
string
Customer’s email address
​
phone
string
Customer’s phone number
​
metadata
object
Additional data attached to the customer
​
created_at
string
Timestamp when the customer was created
​
updated_at
string
Timestamp when the customer was last updated

​
API Endpoints

List All Customers

GET /customers
Retrieve a list of customers with pagination.

​
Query Parameters

​
limit
integer
Number of items per page (default: 30, max: 100)
​
page
integer
Page number (default: 1)
​
search
string
Search by name, email, or phone

Create a Customer

POST /customers
Create a new customer.

​
Request Parameters

​
name
string
required
Customer’s full name
​
email
string
Customer’s email address (required if phone is not provided)
​
phone
string
Customer’s phone number (required if email is not provided)
​
metadata
object
Additional data to attach to the customer

​
Example Request

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+237600000000",
  "metadata": {
    "user_id": "12345",
    "company": "Acme Inc."
  }
}

Retrieve a Customer

GET /customers/{id}
Retrieve details of a specific customer.

​
Path Parameters

​
id
string
required
ID of the customer to retrieve

Update a Customer

PUT /customers/{id}
Update an existing customer.

​
Path Parameters

​
id
string
required
ID of the customer to update

​
Request Parameters

​
name
string
Customer’s full name
​
email
string
Customer’s email address
​
phone
string
Customer’s phone number
​
metadata
object
Additional data to attach to the customer

​
Example Request

{
  "name": "John Smith",
  "phone": "+237600000001",
  "metadata": {
    "user_id": "12345",
    "company": "Acme Corporation"
  }
}

Delete a Customer

DELETE /customers/{id}
Delete a customer.

​
Path Parameters

​
id
string
required
ID of the customer to delete

List Customer Payments

GET /customers/{id}/payments
Retrieve a list of payments made by a specific customer.

​
Path Parameters

​
id
string
required
ID of the customer

​
Query Parameters

​
limit
integer
Number of items per page (default: 30, max: 100)
​
page
integer
Page number (default: 1)
​
status
string
Filter by payment status

​
Best Practices

Collect Complete Information

Collect as much customer information as possible to improve payment success rates and reduce fraud.Include both email and phone when available.

Use Metadata Effectively

Use the metadata field to store additional information about your customers that’s relevant to your business.This can include user IDs from your system, subscription information, or other custom data.

Validate Customer Data

Validate email addresses and phone numbers before sending them to the API to ensure they’re in the correct format.This helps prevent errors and improves the quality of your customer data.

Implement Customer Search

Use the search parameter when listing customers to quickly find existing customers instead of creating duplicates.Search by email, phone, or name to find matching customers.

Payments API

Create and manage payments for customers

Transfers API

Send money to customers

Webhooks API

Receive notifications about customer events