Paystack Customers

The Customers API lets you create and manage customer records on your integration. Customers are automatically created on first charge, but you can also create them explicitly.

Depends on: paystack-setup for the paystackRequest helper and environment config.

Endpoints

Create Customer

POST /customer

Note: first_name, last_name, and phone become required when assigning a Dedicated Virtual Account to customers in Betting, Financial Services, or General Service business categories.

const customer = await paystackRequest<{
  email: string;
  customer_code: string;
  id: number;
}>("/customer", {
  method: "POST",
  body: JSON.stringify({
    email: "customer@example.com",
    first_name: "Zero",
    last_name: "Sum",
    phone: "+2348123456789",
  }),
});
// customer.data.customer_code → "CUS_xnxdt6s1zg1f4nx"

List Customers

GET /customer

const customers = await paystackRequest("/customer?perPage=20&page=1");

Fetch Customer

GET /customer/:email_or_code

Returns full customer details including transactions, subscriptions, and authorizations arrays.

const customer = await paystackRequest(
  `/customer/${encodeURIComponent("CUS_xnxdt6s1zg1f4nx")}`
);
// Includes: customer.data.authorizations[].authorization_code

Update Customer

PUT /customer/:code

await paystackRequest(`/customer/${encodeURIComponent("CUS_xnxdt6s1zg1f4nx")}`, {
  method: "PUT",
  body: JSON.stringify({
    first_name: "BoJack",
    last_name: "Horseman",
  }),
});

Validate Customer Identity

POST /customer/:code/identification

Validates a customer's identity via bank account verification. Returns 202 Accepted — validation happens asynchronously. Listen for customeridentification.success or customeridentification.failed webhooks.

await paystackRequest(
  `/customer/${encodeURIComponent("CUS_xnxdt6s1zg1f4nx")}/identification`,
  {
    method: "POST",
    body: JSON.stringify({
      country: "NG",
      type: "bank_account",
      account_number: "0123456789",
      bvn: "20012345677",
      bank_code: "007",
      first_name: "Asta",
      last_name: "Lavista",
    }),
  }
);
// Returns: { status: true, message: "Customer Identification in progress" }

Whitelist / Blacklist Customer

POST /customer/set_risk_action

await paystackRequest("/customer/set_risk_action", {
  method: "POST",
  body: JSON.stringify({
    customer: "CUS_xr58yrr2ujlft9k",
    risk_action: "deny", // Blacklist this customer
  }),
});

Initialize Authorization

POST /customer/authorization/initialize

Create a reusable authorization code for recurring direct debit transactions.

const auth = await paystackRequest<{
  redirect_url: string;
  access_code: string;
  reference: string;
}>("/customer/authorization/initialize", {
  method: "POST",
  body: JSON.stringify({
    email: "customer@email.com",
    channel: "direct_debit",
    callback_url: "https://example.com/callback",
  }),
});
// Redirect customer to auth.data.redirect_url

Verify Authorization

GET /customer/authorization/verify/:reference

const result = await paystackRequest(
  `/customer/authorization/verify/${encodeURIComponent(reference)}`
);
// result.data.authorization_code, result.data.active

Initialize Direct Debit

POST /customer/:id/initialize-direct-debit

Link a bank account to a customer for direct debit transactions.

const result = await paystackRequest(
  `/customer/${customerId}/initialize-direct-debit`,
  {
    method: "POST",
    body: JSON.stringify({
      account: { number: "0123456789", bank_code: "058" },
      address: { street: "Some Where", city: "Ikeja", state: "Lagos" },
    }),
  }
);
// Redirect customer to result.data.redirect_url

Direct Debit Activation Charge

PUT /customer/:id/directdebit-activation-charge

Trigger an activation charge on an inactive mandate.

await paystackRequest(`/customer/${customerId}/directdebit-activation-charge`, {
  method: "PUT",
  body: JSON.stringify({ authorization_id: 1069309917 }),
});

Fetch Mandate Authorizations

GET /customer/:id/directdebit-mandate-authorizations

const mandates = await paystackRequest(
  `/customer/${customerId}/directdebit-mandate-authorizations`
);
// mandates.data[].status, mandates.data[].authorization_code

Deactivate Authorization

POST /customer/authorization/deactivate

Permanently deactivate a saved card/authorization so it can no longer be used for charges.

await paystackRequest("/customer/authorization/deactivate", {
  method: "POST",
  body: JSON.stringify({
    authorization_code: "AUTH_xxxIjkZVj5",
  }),
});