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

AuthenticationstringRequired

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

/v1/customers

POST /v1/customers HTTP/1.1
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

AuthenticationstringRequired

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

/v1/customers/{CustomerUUID}

PUT /v1/customers/{CustomerUUID} HTTP/1.1
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

AuthenticationstringRequired

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

/v1/customers

GET /v1/customers HTTP/1.1
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

AuthenticationstringRequired

Path parameters

CustomerUUIDstringRequired

The UUID of the customer you want to retrieve.

Example: {{$string.uuid}}

Responses

200Success

application/json

get

/v1/customers/{CustomerUUID}

GET /v1/customers/{CustomerUUID} HTTP/1.1
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

AuthenticationstringRequired

Path parameters

CustomerUUIDstringRequired

The UUID of the customer whose payment methods we are fetching

Responses

200Success

application/json

get

/v1/customers/{CustomerUUID}/payment-methods

GET /v1/customers/{CustomerUUID}/payment-methods HTTP/1.1
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

AuthenticationstringRequired

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

/v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID}/set-default

POST /v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID}/set-default HTTP/1.1
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

AuthenticationstringRequired

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

/v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID}

DELETE /v1/customers/{CustomerUUID}/payment-methods/{CustomerPaymentMethodUUID} HTTP/1.1
Authentication: YOUR_API_KEY
Accept: */*

201Success

{
  "message": "Payment Method deleted successfully",
  "status": "success"
}

PreviousErrors NextPayment Requests

Last updated 6 months ago

hashtagCreate Customer

hashtagUpdate Customer

hashtagList Customers

hashtagFetch Customer

hashtagList Payment Methods

hashtagSet Payment method as default

hashtagDelete payment method

Create Customer

Update Customer

List Customers

Fetch Customer

List Payment Methods

Set Payment method as default

Delete payment method