Customer
A collection of endpoints for creating and managing customers on an integration
- GET/customer
- POST/customer
- GET/customer/{code}
- PUT/customer/{code}
- POST/customer/set_risk_action
- POST/customer/{code}/identification
- POST/customer/authorization/initialize
- GET/customer/authorization/verify/{reference}
- POST/customer/authorization/deactivate
- POST/customer/{id}/initialize-direct-debit
- PUT/customer/{id}/directdebit-activation-charge
- GET/customer/{id}/directdebit-mandate-authorizations
Copy link List Customers
List customers on your integration
Query Parameters
Response
5 object properties
/customercurl https://api.paystack.co/customer \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.list({
use_cursor: true,
next: "NEXT"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.list({
use_cursor: true,
next: "NEXT"
})
puts response.data{
"status": true,
"message": "Customers retrieved",
"data": [
{
"integration": 463433,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"phone": null,
"metadata": null,
"domain": "test",
"customer_code": "CUS_c6wqvwmvwopw4ms",
"risk_action": "default",
"id": 90758908,
"createdAt": "2022-08-15T13:46:39.000Z",
"updatedAt": "2022-08-15T13:46:39.000Z"
},
{
"integration": 463433,
"first_name": "Okiki",
"last_name": "Sample",
"email": "[email protected]",
"phone": "+2348123456789",
"metadata": {},
"domain": "test",
"customer_code": "CUS_rki2ccocw7g8lsj",
"risk_action": "default",
"id": 90758301,
"createdAt": "2022-08-15T13:42:52.000Z",
"updatedAt": "2022-08-15T13:42:52.000Z"
},
{
"integration": 463433,
"first_name": "lukman",
"last_name": "calle",
"email": "[email protected]",
"phone": "+2348123456789",
"metadata": {},
"domain": "test",
"customer_code": "CUS_hpxsz8c1if90quo",
"risk_action": "default",
"id": 90747194,
"createdAt": "2022-08-15T12:31:13.000Z",
"updatedAt": "2022-08-15T12:31:13.000Z"
}
],
"meta": {
"next": "Y3VzdG9tZXI6OTAyMjU4MDk=",
"previous": null,
"perPage": 3
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Customer
Create a customer on your integration
Request Body
Response
17 object properties
1 object property
/customercurl https://api.paystack.co/customer \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.create({
email: "[email protected]"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.create({
email: "[email protected]"
})
puts response.data{
"status": true,
"message": "Customer created",
"data": {
"email": "[email protected]",
"integration": 100032,
"domain": "test",
"customer_code": "CUS_xnxdt6s1zg1f4nx",
"id": 1173,
"identified": false,
"identifications": null,
"createdAt": "2016-03-29T20:03:09.584Z",
"updatedAt": "2016-03-29T20:03:09.584Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Customer
Get details of a customer on your integration.
Path Parameters
Response
23 object properties
1 object property
/customer/{code}curl https://api.paystack.co/customer/CUS_c6wqvwmvwopw4ms \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.fetch("CUS_c6wqvwmvwopw4ms");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.fetch("CUS_c6wqvwmvwopw4ms")
puts response.data{
"status": true,
"message": "Customer retrieved",
"data": {
"transactions": [],
"subscriptions": [],
"authorizations": [
{
"authorization_code": "AUTH_ekk8t49ogj",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
}
],
"first_name": null,
"last_name": null,
"email": "[email protected]",
"phone": null,
"metadata": null,
"domain": "test",
"customer_code": "CUS_c6wqvwmvwopw4ms",
"risk_action": "default",
"id": 90758908,
"integration": 463433,
"createdAt": "2022-08-15T13:46:39.000Z",
"updatedAt": "2022-08-15T13:46:39.000Z",
"created_at": "2022-08-15T13:46:39.000Z",
"updated_at": "2022-08-15T13:46:39.000Z",
"total_transactions": 0,
"total_transaction_value": [],
"dedicated_account": null,
"identified": false,
"identifications": null
}
}{
"status": false,
"message": "Invalid key"
}{
"status": false,
"message": "Customer email is invalid for your live domain."
}Copy link Update Customer
Update a customer's details on your integration
Path Parameters
Request Body
Response
14 object properties
/customer/{code}curl https://api.paystack.co/customer/CUS_c6wqvwmvwopw4ms \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jane",
"last_name": "Doe"
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.update("CUS_c6wqvwmvwopw4ms", {
first_name: "Jane",
last_name: "Doe"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.update("CUS_c6wqvwmvwopw4ms", {
first_name: "Jane",
last_name: "Doe"
})
puts response.data{
"status": true,
"message": "Customer updated",
"data": {
"integration": 100032,
"first_name": "BoJack",
"last_name": "Horseman",
"email": "[email protected]",
"phone": null,
"metadata": {
"photos": [
{
"type": "twitter",
"typeId": "twitter",
"typeName": "Twitter",
"url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
"isPrimary": true
}
]
},
"identified": false,
"identifications": null,
"domain": "test",
"customer_code": "CUS_xnxdt6s1zg1f4nx",
"id": 1173,
"transactions": [],
"subscriptions": [],
"authorizations": [],
"createdAt": "2016-03-29T20:03:09.000Z",
"updatedAt": "2016-03-29T20:03:10.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Set Risk Action
Set customer's risk action by whitelisting or blacklisting the customer
Request Body
Response
17 object properties
/customer/set_risk_actioncurl https://api.paystack.co/customer/set_risk_action \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_c6wqvwmvwopw4ms"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.riskAction({
customer: "CUS_c6wqvwmvwopw4ms"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.risk_action({
customer: "CUS_c6wqvwmvwopw4ms"
})
puts response.data{
"status": true,
"message": "Customer updated",
"data": {
"first_name": "Peter",
"last_name": "Griffin",
"email": "[email protected]",
"phone": null,
"metadata": {},
"domain": "test",
"identified": false,
"identifications": null,
"customer_code": "CUS_xr58yrr2ujlft9k",
"risk_action": "allow",
"id": 2109,
"integration": 100032,
"createdAt": "2016-01-26T13:43:38.000Z",
"updatedAt": "2016-08-23T03:56:43.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Validate Customer
Validate a customer's identity
Path Parameters
Request Body
Response
/customer/{code}/identificationcurl https://api.paystack.co/customer/CUS_c6wqvwmvwopw4ms/identification \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Jane",
"last_name": "Doe",
"type": "bank_account",
"country": "NG",
"bvn": "20012345677",
"bank_code": "007",
"account_number": "0123456789"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.validate("CUS_c6wqvwmvwopw4ms", {
first_name: "Jane",
last_name: "Doe",
type: "bank_account",
country: "NG",
bvn: "20012345677",
bank_code: "007",
account_number: "0123456789"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.validate("CUS_c6wqvwmvwopw4ms", {
first_name: "Jane",
last_name: "Doe",
type: "bank_account",
country: "NG",
bvn: "20012345677",
bank_code: "007",
account_number: "0123456789"
})
puts response.data{
"status": true,
"message": "Customer Identification in progress"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Initialize Authorization
Initiate a request to create a reusable authorization code for recurring transactions
Request Body
2 object properties
3 object properties
Response
3 object properties
/customer/authorization/initializecurl https://api.paystack.co/customer/authorization/initialize \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"channel": "direct_debit"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.initializeAuthorization({
email: "[email protected]",
channel: "direct_debit"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.initialize_authorization({
email: "[email protected]",
channel: "direct_debit"
})
puts response.data{
"status": true,
"message": "Authorization initialized",
"data": {
"redirect_url": "https://checkout.paystack.com/82t4mp5b5mfn51h",
"access_code": "82t4mp5b5mfn51h",
"reference": "dfbzfotsrbv4n5s82t4mp5b5mfn51h"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Verify Authorization
Check the status of an authorization request
Path Parameters
Response
5 object properties
2 object properties
/customer/authorization/verify/{reference}curl https://api.paystack.co/customer/authorization/verify/dfbzfotsrbv4n5s82t4mp5b5mfn51h \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.verifyAuthorization("dfbzfotsrbv4n5s82t4mp5b5mfn51h");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.verify_authorization("dfbzfotsrbv4n5s82t4mp5b5mfn51h")
puts response.data{
"status": true,
"message": "Authorization retrieved successfully",
"data": {
"authorization_code": "AUTH_JV4T9Wawdj",
"channel": "direct_debit",
"bank": "Guaranty Trust Bank",
"active": true,
"customer": {
"code": "CUS_24lze1c8i2zl76y",
"email": "[email protected]"
}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "Authorization does not exist or does not belong to integration"
}Copy link Deactivate Authorization
Deactivate an authorization for any payment channel.
Request Body
Response
/customer/authorization/deactivatecurl https://api.paystack.co/customer/authorization/deactivate \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_code": "AUTH_xxxIjkZVj5"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.deactivateAuthorization({
authorization_code: "AUTH_xxxIjkZVj5"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.deactivate_authorization({
authorization_code: "AUTH_xxxIjkZVj5"
})
puts response.data{
"status": true,
"message": "Authorization has been deactivated"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Initialize Direct Debit
Initialize the process of linking an account to a customer for Direct Debit transactions
Path Parameters
Request Body
2 object properties
3 object properties
Response
3 object properties
/customer/{id}/initialize-direct-debitcurl https://api.paystack.co/customer/297346561/initialize-direct-debit \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"account": {},
"address": {}
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.initializeDirectDebit("297346561", {
account: {},
address: {}
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.initialize_direct_debit("297346561", {
account: {},
address: {}
})
puts response.data{
"status": true,
"message": "Authorization initialized",
"data": {
"redirect_url": "https://link.paystack.com/ll6b0szngj1f27k",
"access_code": "ll6b0szngj1f27k",
"reference": "1er945lpy4txyki"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Direct Debit Activation Charge
Trigger an activation charge on an inactive mandate on behalf of your customer
Path Parameters
Request Body
Response
/customer/{id}/directdebit-activation-chargecurl https://api.paystack.co/customer/297346561/directdebit-activation-charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_id": 1069309917
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.directDebitActivationCharge("297346561", {
authorization_id: 1069309917
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.direct_debit_activation_charge("297346561", {
authorization_id: 1069309917
})
puts response.data{
"status": true,
"message": "Mandate is queued for retry"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Mandate Authorizations
Get the list of direct debit mandates associated with a customer
Path Parameters
Response
4 object properties
/customer/{id}/directdebit-mandate-authorizationscurl https://api.paystack.co/customer/297346561/directdebit-mandate-authorizations \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.customer.fetchMandateAuthorizations("297346561");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.customer.fetch_mandate_authorizations("297346561")
puts response.data{
"status": true,
"message": "Mandate authorizations retrieved successfully",
"data": [
{
"id": 164098,
"status": "active",
"mandate_id": 512003,
"authorization_id": 110049014,
"authorization_code": "AUTH_8Lol0pNt14",
"integration_id": 463433,
"account_number": "0123456789",
"bank_code": "032",
"bank_name": null,
"customer": {
"id": 43975700,
"customer_code": "CUS_2eusy8uwe34s23fy",
"email": "[email protected]",
"first_name": "Smith",
"last_name": "Bel"
},
"authorized_at": "2024-09-27T10:57:53.824Z"
}
],
"meta": {
"per_page": 50,
"next": null,
"count": 1,
"total": 1
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}