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

string

Unique identifier for the customer

name

string

Customer’s full name

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)

string

Search by name, email, or phone

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)

string

Search by name, email, or phone

{
  "code": 200,
  "status": "OK",
  "message": "Customers retrieved",
  "totals": 50,
  "last_page": 2,
  "current_page": 1,
  "selected": 30,
  "items": [
    {
      "id": "cus_123456789",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+237600000000",
      "created_at": "2023-01-01T12:00:00Z"
    },
    // More customers...
  ]
}

Create a Customer

POST /customers

Create a new customer.

Request Parameters

name

string

required

Customer’s full name

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."
  }
}

POST /customers

Create a new customer.

Request Parameters

name

string

required

Customer’s full name

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."
  }
}

{
  "status": "Created",
  "message": "Customer created",
  "code": 201,
  "customer": {
    "id": "cus_123456789",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+237600000000",
    "metadata": {
      "user_id": "12345",
      "company": "Acme Inc."
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

Retrieve a Customer

GET /customers/{id}

Retrieve details of a specific customer.

Path Parameters

string

required

ID of the customer to retrieve

GET /customers/{id}

Retrieve details of a specific customer.

Path Parameters

string

required

ID of the customer to retrieve

{
  "status": "OK",
  "message": "Customer retrieved",
  "code": 200,
  "customer": {
    "id": "cus_123456789",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+237600000000",
    "metadata": {
      "user_id": "12345",
      "company": "Acme Inc."
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

Update a Customer

PUT /customers/{id}

Update an existing customer.

Path Parameters

string

required

ID of the customer to update

Request Parameters

name

string

Customer’s full name

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"
  }
}

PUT /customers/{id}

Update an existing customer.

Path Parameters

string

required

ID of the customer to update

Request Parameters

name

string

Customer’s full name

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"
  }
}

{
  "status": "OK",
  "message": "Customer updated",
  "code": 200,
  "customer": {
    "id": "cus_123456789",
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+237600000001",
    "metadata": {
      "user_id": "12345",
      "company": "Acme Corporation"
    },
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-02T10:00:00Z"
  }
}

Delete a Customer

DELETE /customers/{id}

Delete a customer.

Path Parameters

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

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

GET /customers/{id}/payments

Retrieve a list of payments made by a specific customer.

Path Parameters

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

{
  "code": 200,
  "status": "OK",
  "message": "Payments retrieved",
  "totals": 10,
  "last_page": 1,
  "current_page": 1,
  "selected": 10,
  "items": [
    {
      "id": "pay_123456789",
      "reference": "order_123",
      "amount": 5000,
      "currency": "XAF",
      "status": "complete",
      "created_at": "2023-01-01T12:00:00Z"
    },
    // More payments...
  ]
}

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

Introduction

Core Resources

Additional Resources

API Specification

​Customers API

​The Customer Object

​Customer Object Properties

​API Endpoints

List All Customers

​Query Parameters

​Query Parameters

Create a Customer

​Request Parameters

​Example Request

​Request Parameters

​Example Request

Retrieve a Customer

​Path Parameters

​Path Parameters

Update a Customer

​Path Parameters

​Request Parameters

​Example Request

​Path Parameters

​Request Parameters

​Example Request

Delete a Customer

​Path Parameters

​Path Parameters

List Customer Payments

​Path Parameters

​Query Parameters

​Path Parameters

​Query Parameters

​Best Practices

Collect Complete Information

Use Metadata Effectively

Validate Customer Data

Implement Customer Search

​Related Resources

Payments API

Transfers API

Webhooks API

Customers API

The Customer Object

Customer Object Properties

API Endpoints

Query Parameters

Query Parameters

Request Parameters

Example Request

Request Parameters

Example Request

Path Parameters

Path Parameters

Path Parameters

Request Parameters

Example Request

Path Parameters

Request Parameters

Example Request

Path Parameters

Path Parameters

Path Parameters

Query Parameters

Path Parameters

Query Parameters

Best Practices

Related Resources