api
Cancel

No result found for:

Customers

The Customers API allows you create and manage customers on your integration.

Create Customer

Create a customer on your integration

Customer Validation

The first_name, last_name and phone are optional parameters. However, when creating a customer that would be assigned a Dedicated Virtual Account and your business catgeory falls under Betting, Financial services, and General Service, then these parameters become compulsory.

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
email
String
Customer's email address
first_name
String
Customer's first name
last_name
String
Customer's last name
phone
String
Customer's phone number
metadata
Object
A set of key/value pairs that you can attach to the customer. It can be used to store additional information in a structured format.
Show optional parameters
POST/customer
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6    "email": "zero@sum.com",
7    "first_name": "Zero",
8    "last_name": "Sum",
9    "phone": "+2348123456789"
10}'
11

12curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customer created",
4  "data": {
5    "email": "customer@email.com",
6    "integration": 100032,
7    "domain": "test",
8    "customer_code": "CUS_xnxdt6s1zg1f4nx",
9    "id": 1173,
10    "identified": false,
11    "identifications": null,
12    "createdAt": "2016-03-29T20:03:09.584Z",
13    "updatedAt": "2016-03-29T20:03:09.584Z"
14  }
15}

List Customer

List customers available on your integration.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/customer
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customers retrieved",
4  "data": [
5    {
6      "integration": 463433,
7      "first_name": null,
8      "last_name": null,
9      "email": "dom@gmail.com",
10      "phone": null,
11      "metadata": null,
12      "domain": "test",
13      "customer_code": "CUS_c6wqvwmvwopw4ms",
14      "risk_action": "default",
15      "id": 90758908,
16      "createdAt": "2022-08-15T13:46:39.000Z",
17      "updatedAt": "2022-08-15T13:46:39.000Z"
18    },
19    {
20      "integration": 463433,
21      "first_name": "Okiki",
22      "last_name": "Sample",
23      "email": "okiki@sample.com",
24      "phone": "09048829123",
25      "metadata": {},
26      "domain": "test",
27      "customer_code": "CUS_rki2ccocw7g8lsj",
28      "risk_action": "default",
29      "id": 90758301,
30      "createdAt": "2022-08-15T13:42:52.000Z",
31      "updatedAt": "2022-08-15T13:42:52.000Z"
32    },
33    {
34      "integration": 463433,
35      "first_name": "lukman",
36      "last_name": "calle",
37      "email": "lukman@calle.co",
38      "phone": "08922383034",
39      "metadata": {},
40      "domain": "test",
41      "customer_code": "CUS_hpxsz8c1if90quo",
42      "risk_action": "default",
43      "id": 90747194,
44      "createdAt": "2022-08-15T12:31:13.000Z",
45      "updatedAt": "2022-08-15T12:31:13.000Z"
46    }
47  ],
48  "meta": {
49    "next": "Y3VzdG9tZXI6OTAyMjU4MDk=",
50    "previous": null,
51    "perPage": 3
52  }
53}

Fetch Customer

Get details of a customer on your integration.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
email_or_code
String
An email or customer code for the customer you want to fetch
GET/customer/:email_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer/{email_or_code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customer retrieved",
4  "data": {
5    "transactions": [],
6    "subscriptions": [],
7    "authorizations": [
8      {
9        "authorization_code": "AUTH_ekk8t49ogj",
10        "bin": "408408",
11        "last4": "4081",
12        "exp_month": "12",
13        "exp_year": "2030",
14        "channel": "card",
15        "card_type": "visa ",
16        "bank": "TEST BANK",
17        "country_code": "NG",
18        "brand": "visa",
19        "reusable": true,
20        "signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
21        "account_name": null
22      }
23    ],
24    "first_name": null,
25    "last_name": null,
26    "email": "dom@gmail.com",
27    "phone": null,
28    "metadata": null,
29    "domain": "test",
30    "customer_code": "CUS_c6wqvwmvwopw4ms",
31    "risk_action": "default",
32    "id": 90758908,
33    "integration": 463433,
34    "createdAt": "2022-08-15T13:46:39.000Z",
35    "updatedAt": "2022-08-15T13:46:39.000Z",
36    "created_at": "2022-08-15T13:46:39.000Z",
37    "updated_at": "2022-08-15T13:46:39.000Z",
38    "total_transactions": 0,
39    "total_transaction_value": [],
40    "dedicated_account": null,
41    "identified": false,
42    "identifications": null
43  }
44}

Update Customer

Update a customer's details on your integration

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Parameters
code
String
Customer's code
Body Parameters
first_name
String
Customer's first name
last_name
String
Customer's last name
phone
String
Customer's phone number
metadata
Object
A set of key/value pairs that you can attach to the customer. It can be used to store additional information in a structured format.
Show optional parameters
PUT/customer/:code
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer/{code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "first_name": "BoJack"
7}'
8

9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customer updated",
4  "data": {
5    "integration": 100032,
6    "first_name": "BoJack",
7    "last_name": "Horseman",
8    "email": "bojack@horsinaround.com",
9    "phone": null,
10    "metadata": {
11      "photos": [
12        {
13          "type": "twitter",
14          "typeId": "twitter",
15          "typeName": "Twitter",
16          "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
17          "isPrimary": true
18        }
19      ]
20    },
21    "identified": false,
22    "identifications": null,
23    "domain": "test",
24    "customer_code": "CUS_xnxdt6s1zg1f4nx",
25    "id": 1173,
26    "transactions": [],
27    "subscriptions": [],
28    "authorizations": [],
29    "createdAt": "2016-03-29T20:03:09.000Z",
30    "updatedAt": "2016-03-29T20:03:10.000Z"
31  }
32}

Validate Customer

Validate a customer's identity

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Parameters
code
String
Email, or customer code of customer to be identified
Body Parameters
first_name
String
Customer's first name
last_name
String
Customer's last name
type
String
Predefined types of identification. Only bank_account is supported at the moment
value
String
Customer's identification number
country
String
2 letter country code of identification issuer
bvn
String
Customer's Bank Verification Number
bank_code
String
You can get the list of Bank Codes by calling the List Banks endpoint. (required if type is bank_account)
account_number
String
Customer's bank account number. (required if type is bank_account)
middle_name
String
Customer's middle name
Show optional parameters
POST/customer/:code/identification
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer/{customer_code}/identification"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "country": "NG",
7  "type": "bank_account",
8  "account_number": "0123456789",
9  "bvn": "20012345677",
10  "bank_code": "007",
11  "first_name": "Asta",
12  "last_name": "Lavista"
13}'
14

15curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customer Identification in progress"
4}

Whitelist/Blacklist Customer

Whitelist or blacklist a customer on your integration

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
customer
String
Customer's code, or email address
risk_action
String
One of the possible risk actions [ default, allow, deny ]. allow to whitelist. deny to blacklist. Customers start with a default risk action.
Show optional parameters
POST/customer/set_risk_action
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer/set_risk_action"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "customer": "CUS_xr58yrr2ujlft9k", 
7  "risk_action": "allow"
8}'
9

10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Customer updated",
4  "data": {
5    "first_name": "Peter",
6    "last_name": "Griffin",
7    "email": "peter@grif.com",
8    "phone": null,
9    "metadata": {},
10    "domain": "test",
11    "identified": false,
12    "identifications": null,
13    "customer_code": "CUS_xr58yrr2ujlft9k",
14    "risk_action": "allow",
15    "id": 2109,
16    "integration": 100032,
17    "createdAt": "2016-01-26T13:43:38.000Z",
18    "updatedAt": "2016-08-23T03:56:43.000Z"
19  }
20}

Deactivate Authorization

Deactivate an authorization when the card needs to be forgotten

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
authorization_code
String
Authorization code to be deactivated
POST/customer/deactivate_authorization
cURL
1#!/bin/sh
2url="https://api.paystack.co/customer/deactivate_authorization"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "authorization_code": "AUTH_72btv547"
7}'
8

9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Authorization has been deactivated"
4}