Customers

The customers API allows you to create and manage customers on your business. Customers can then be charged payments via payment requests, or recurring payments via subscriptions.

Create Customer

post

This endpoint creates a new customer. A customer can then be used to initiate payments or subscriptions.

Authorizations
Body
first_namestringOptional

First name of the customer (Required without a name) field.

last_namestringOptional

Last name of the customer (Required without a name) field.

namestringOptional

Name of the customer. Could be a business name, or a full name. Overrides the first_name and last_name fields.

emailstringRequired

Email of the customer

phone_codestringOptional

The country code of the customer's phone number in the format e.g +234

phone_numberstringOptional

The customer's phone number without the country code

address_line_1stringOptional

The customer's address line

address_line_2stringOptional

The customer's secondary addresss line

citystringOptional

The customer's city

statestringOptional

The customer's state

zipstringOptional

The customer's zip code

countrystringOptional

The customer's country

meta_dataobjectOptional

An arbitrary object to store additional data for the customer

Responses
201Success
application/json
post
POST /v1/customers HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 312

{
  "first_name": "Roronoa",
  "last_name": "Zoro",
  "email": "[email protected]",
  "phone_code": "+234",
  "phone_number": "8123456789",
  "address_line_1": "The Going Merry",
  "address_line_2": "The Thousand Sunny",
  "city": "Lagos",
  "state": "Lagos",
  "zip": "101233",
  "country": "Nigeria",
  "meta_data": {
    "uid": "84734",
    "status": "Dignified"
  }
}
201Success
{
  "message": "Customer created successfully",
  "status": "success",
  "data": {
    "customer_id": "LIV-359795593",
    "uuid": "31b45fea-2db5-11f0-ac87-92433b0171f7",
    "env_mode": "live",
    "first_name": "Roronoa",
    "last_name": "Zoro",
    "name": null,
    "external_customer_ids": null,
    "email": "[email protected]",
    "phone_code": "+234",
    "phone_number": "8123456789",
    "address_line_1": "The Going Merry",
    "address_line_2": "The Thousand Sunny",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101233",
    "country": "Nigeria",
    "meta_data": {
      "uid": "84734",
      "status": "Dignified"
    },
    "deleted_at": null,
    "created_at": "2025-05-10T15:41:09.000000Z",
    "updated_at": "2025-05-10T15:41:09.000000Z",
    "full_name": "Roronoa Zoro"
  }
}

Update Customer

put

This endpoint updates a customer.

Authorizations
Path parameters
CustomerUUIDstringRequired
Body
first_namestringOptional

First name of the customer (Required without a name) field.

last_namestringOptional

Last name of the customer (Required without a name) field.

namestringOptional

Name of the customer. Could be a business name, or a full name. Overrides the first_name and last_name fields.

emailstringOptional

Email of the customer

phone_codestringOptional

The country code of the customer's phone number in the format e.g +234

phone_numberstringOptional

The customer's phone number without the country code

address_line_1stringOptional

The customer's address line

address_line_2stringOptional

The customer's secondary addresss line

citystringOptional

The customer's city

statestringOptional

The customer's state

zipstringOptional

The customer's zip code

countrystringOptional

The customer's country

meta_dataobjectOptional

An arbitrary object to store additional data for the customer

Responses
201Success
application/json
put
PUT /v1/customers/{CustomerUUID} HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 312

{
  "first_name": "Roronoa",
  "last_name": "Zoro",
  "email": "[email protected]",
  "phone_code": "+234",
  "phone_number": "8123456789",
  "address_line_1": "The Going Merry",
  "address_line_2": "The Thousand Sunny",
  "city": "Lagos",
  "state": "Lagos",
  "zip": "101233",
  "country": "Nigeria",
  "meta_data": {
    "uid": "84734",
    "status": "Dignified"
  }
}
201Success
{
  "message": "Customer updated successfully",
  "status": "success",
  "data": {
    "customer_id": "LIV-579952205",
    "uuid": "e097274b-6518-11f0-8f93-0242ac120006",
    "env_mode": "live",
    "first_name": "Roronoa",
    "last_name": "Zoro",
    "name": null,
    "external_customer_ids": null,
    "email": "[email protected]",
    "phone_code": "+234",
    "phone_number": "8123456789",
    "address_line_1": "The Going Merry",
    "address_line_2": "The Thousand Sunny",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101233",
    "country": "Nigeria",
    "meta_data": {
      "uid": "84734",
      "status": "Dignified"
    },
    "created_at": "2025-07-20T03:23:17.000000Z",
    "updated_at": "2025-07-20T03:23:17.000000Z",
    "full_name": "Roronoa Zoro"
  }
}

List Customers

get

This endpoint provides a paginated list of payment requests within your business. You can customize the number of items per page using the per_page query parameter and the page to fetch with the page query parameter.

Authorizations
Query parameters
pagestringOptional

Defines the page of customers to fetch

per_pagestringOptional

Defines the number of items to return on each page

Responses
200Success
application/json
get
GET /v1/customers HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Accept: */*
200Success
{
  "message": "Customers retrieved successfully",
  "status": "success",
  "data": [
    {
      "customer_id": "LIV-7421541e6",
      "uuid": "53145bb4-b778-11ef-8d1a-621bbad79fdf",
      "env_mode": "live",
      "first_name": "Roronoa",
      "last_name": "Zoro",
      "name": null,
      "external_customer_ids": {
        "paystack": 215556634
      },
      "email": "[email protected]",
      "phone_code": "+234",
      "phone_number": "8246578707",
      "address_line_1": "The Going Merry",
      "address_line_2": "The Thousand Sunny",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101233",
      "country": "Nigeria",
      "meta_data": {
        "uid": "84734",
        "status": "Dignified"
      },
      "deleted_at": null,
      "created_at": "2024-12-11T04:28:08.000000Z",
      "updated_at": "2024-12-11T04:30:28.000000Z",
      "full_name": "Roronoa Zoro"
    },
    {
      "customer_id": "LIV-7421541e6",
      "uuid": "53145bb4-b778-11ef-8d1a-621bbad79fdf",
      "env_mode": "live",
      "first_name": null,
      "last_name": null,
      "name": "Monkey D. Luffy",
      "external_customer_ids": null,
      "email": "[email protected]",
      "phone_code": "+234",
      "phone_number": "8242598707",
      "address_line_1": "The Going Merry",
      "address_line_2": "The Thousand Sunny",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101233",
      "country": "Nigeria",
      "meta_data": null,
      "deleted_at": null,
      "created_at": "2024-12-11T04:28:08.000000Z",
      "updated_at": "2024-12-11T04:30:28.000000Z",
      "full_name": "Monkey D. Luffy"
    }
  ]
}

Fetch Customer

get

This endpoint fetches a single customer using the customer's UUID.

Authorizations
Path parameters
CustomerUUIDstringRequired

The UUID of the customer you want to retrieve.

Example: {{$string.uuid}}
Responses
200Success
application/json
get
GET /v1/customers/{CustomerUUID} HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Accept: */*
200Success
{
  "message": "Customer retrieved successfully",
  "status": "success",
  "data": {
    "customer_id": "LIV-7421541e6",
    "uuid": "53145bb4-b778-11ef-8d1a-621bbad79fdf",
    "env_mode": "live",
    "first_name": "Roronoa",
    "last_name": "Zoro",
    "name": null,
    "external_customer_ids": {
      "paystack": 215556634
    },
    "email": "[email protected]",
    "phone_code": "+234",
    "phone_number": "8246578707",
    "address_line_1": "The Going Merry",
    "address_line_2": "The Thousand Sunny",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "101233",
    "country": "Nigeria",
    "meta_data": {
      "uid": "84734",
      "status": "Dignified"
    },
    "deleted_at": null,
    "created_at": "2024-12-11T04:28:08.000000Z",
    "updated_at": "2024-12-11T04:30:28.000000Z",
    "full_name": "Roronoa Zoro"
  }
}

List Payment Methods

get

This endpoint fetches all the saved payment methods for a customer.

You can make a one-time charge on a saved payment method with the /v1/payment-requests/charge-payment-method endpoint.

Asyncpay also makes use of saved payment methods to handle recurring charges on subscriptions.

Authorizations
Path parameters
CustomerUUIDstringRequired

The UUID of the customer whose payment methods we are fetching

Responses
200Success
application/json
get
GET /v1/customers/{CustomerUUID}/payment-methods HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Accept: */*
200Success
{
  "message": "Payment Methods retrieved successfully",
  "status": "success",
  "data": [
    {
      "uuid": "bc039205-379c-11f0-ac87-92433b0171f7",
      "payment_method": "card",
      "payment_channel_slug": "paystack",
      "created_at": "2025-05-23T06:11:15.000000Z",
      "updated_at": "2025-05-23T06:11:15.000000Z",
      "is_default": 1,
      "card_last4": "7588",
      "card_brand": "mastercard",
      "card_exp_month": "10",
      "card_exp_year": "28",
      "deleted_at": null
    }
  ]
}

Set Payment method as default

post

This endpoint allows you to specify the default payment method for a customer.

The default payment method is used when trying to charge a customer for their recurring subscriptions.

Authorizations
Path parameters
CustomerUUIDstringRequired

The UUID of the customer who we want to set the default payment method for.

Example: {{$string.uuid}}
CustomerPaymentMethodUUIDstringRequired

The UUID of the payment method to set as default for the customer.

Example: {{$string.uuid}}
Responses
201Success
application/json
post
POST /v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID}/set-default HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Accept: */*
201Success
{
  "message": "Payment Method set as default",
  "status": "success",
  "data": [
    {
      "uuid": "bc039205-379c-11f0-ac87-92433b0171f7",
      "payment_method": "card",
      "payment_channel_slug": "paystack",
      "created_at": "2025-05-23T06:11:15.000000Z",
      "updated_at": "2025-05-24T04:14:33.000000Z",
      "is_default": 1,
      "card_last4": "7588",
      "card_brand": "mastercard",
      "card_exp_month": "10",
      "card_exp_year": "28",
      "deleted_at": null
    },
    {
      "uuid": "7518662c-3853-11f0-ac87-92433b0171f7",
      "payment_method": "card",
      "payment_channel_slug": "paystack",
      "created_at": "2025-05-24T03:59:14.000000Z",
      "updated_at": "2025-05-24T04:14:33.000000Z",
      "is_default": 0,
      "card_last4": "3278",
      "card_brand": "mastercard",
      "card_exp_month": "08",
      "card_exp_year": "27",
      "deleted_at": null
    }
  ]
}

Delete payment method

delete

This endpoint deletes a customer's payment method.

Authorizations
Path parameters
CustomerUUIDstringRequired

The UUID of the customer whose payment method we want to delete.

Example: {{$string.uuid}}
CustomerPaymentMethodUUIDstringRequired

The UUID of the payment method.

Example: {{$string.uuid}}
Responses
201Success
application/json
delete
DELETE /v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID} HTTP/1.1
Host: 
Authentication: YOUR_API_KEY
Accept: */*
201Success
{
  "message": "Payment Method deleted successfully",
  "status": "success"
}
PreviousErrorsNextPayment Requests

Last updated