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
1curl https://api.paystack.co/customer
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "email": "zero@sum.com",
5 "first_name": "Zero",
6 "last_name": "Sum",
7 "phone": "+2348123456789"
8 }'
9-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
1curl https://api.paystack.co/customer
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-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
1curl https://api.paystack.co/customer/:email_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-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
1curl https://api.paystack.co/customer/:code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "first_name": "BoJack" }'
5-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
1curl https://api.paystack.co/customer/{customer_code}/identification
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{
5 "country": "NG",
6 "type": "bank_account",
7 "account_number": "0123456789",
8 "bvn": "20012345677",
9 "bank_code": "007",
10 "first_name": "Asta",
11 "last_name": "Lavista"
12
13}'
14-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
1curl https://api.paystack.co/customer/set_risk_action
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "customer": "CUS_xr58yrr2ujlft9k", "risk_action": "allow" }'
5-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
1curl https://api.paystack.co/customer/deactivate_authorization
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "authorization_code": "AUTH_72btv547" }'
5-X POST
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Authorization has been deactivated"
4}