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

string

Customer’s full name

string

Customer’s email address

string

Customer’s phone number

object

Additional data attached to the customer

string

Timestamp when the customer was created

string

Timestamp when the customer was last updated

API Endpoints

List All Customers

Request
Response

GET /customers

Retrieve a list of customers with pagination.

Query Parameters

integer

Number of items per page (default: 30, max: 100)

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

Request
Response

POST /customers

Create a new customer.

Request Parameters

string

required

Customer’s full name

string

Customer’s email address (required if phone is not provided)

string

Customer’s phone number (required if email is not provided)

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

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

fetch('https://api.notchpay.co/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(customer)
});

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

Request
Response

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

Request
Response

PUT /customers/{id}

Update an existing customer.

Path Parameters

string

required

ID of the customer to update

Request Parameters

string

Customer’s full name

string

Customer’s email address

string

Customer’s phone number

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

Request
Response

DELETE /customers/{id}

Delete a customer.

Path Parameters

string

required

ID of the customer to delete

{
  "status": "OK",
  "message": "Customer deleted",
  "code": 200
}

Deleting a customer will not delete any associated payments or other records. It only removes the customer record itself.

List Customer Payments

Request
Response

GET /customers/{id}/payments

Retrieve a list of payments made by a specific customer.

Path Parameters

string

required

ID of the customer

Query Parameters

integer

Number of items per page (default: 30, max: 100)

integer

Page number (default: 1)

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

Customers API

The Customer Object

Customer Object Properties

API Endpoints

List All Customers

Query Parameters

Create a Customer

Request Parameters

Example Request

Retrieve a Customer

Path Parameters

Update a Customer

Path Parameters

Request Parameters

Example Request

Delete a Customer

Path Parameters

List Customer Payments

Path Parameters

Query Parameters

Best Practices

Collect Complete Information

Use Metadata Effectively

Validate Customer Data

Implement Customer Search

Payments API

Transfers API

Webhooks API

​Customers API

​The Customer Object

​Customer Object Properties

​API Endpoints

List All Customers

​Query Parameters

Create a Customer

​Request Parameters

​Example Request

Retrieve a Customer

​Path Parameters

Update a Customer

​Path Parameters

​Request Parameters

​Example Request

Delete a Customer

​Path Parameters

List Customer Payments

​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

Request Parameters

Example Request

Path Parameters

Path Parameters

Request Parameters

Example Request

Path Parameters

Path Parameters

Query Parameters

Best Practices

Related Resources