Paystack Charges

Paystack Charges

The Charge API gives you direct control over which payment channel to use, bypassing the standard Paystack checkout. It supports card, bank, USSD, mobile money, QR, EFT, Capitec Pay, and bank transfers.

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

Charge Flow

The Charge API follows a multi-step flow. After creating a charge, Paystack may request additional authentication:

Create Charge → Check status → If "send_pin"    → Submit PIN    → Check status
                              → If "send_otp"    → Submit OTP    → Check status
                              → If "send_phone"  → Submit Phone  → Check status
                              → If "send_birthday"→ Submit Birthday→ Check status
                              → If "send_address"→ Submit Address → Check status
                              → If "pending"     → Wait 10s      → Check Pending
                              → If "success"     → Done ✓

Endpoints

Create Charge

POST /charge

Core Parameters (Body)

Channel-Specific Parameters

Send ONE of these objects to select the payment channel:

Bank Account (Nigeria)

const result = await paystackRequest("/charge", {
  method: "POST",
  body: JSON.stringify({
    email: "customer@email.com",
    amount: "10000",
    bank: {
      code: "057",           // Bank code (get from List Banks endpoint)
      account_number: "0000000000",
    },
    birthday: "1995-12-23",  // Required for some banks
  }),
});

Bank Account (Kuda Bank)

{
  email: "customer@email.com",
  amount: "10000",
  bank: {
    code: "50211",
    account_number: "0000000000",
    phone: "08012345678",    // Required for Kuda
    token: "123456",         // 6-digit code from Kuda app
  }
}

USSD (Nigeria only)

{
  email: "customer@email.com",
  amount: "10000",
  ussd: { type: "737" }     // 737 (GTBank) — currently only supported type
}

Mobile Money (Ghana, Kenya, Côte d'Ivoire)

// MTN Ghana
{
  email: "customer@email.com",
  amount: "10000",
  mobile_money: {
    phone: "0551234987",
    provider: "mtn"          // mtn | atl | vod (Ghana), mpesa (Kenya), orange | wave (CIV)
  }
}

// M-Pesa Kenya (till number)
{
  email: "customer@email.com",
  amount: "10000",
  mobile_money: {
    account: "TILL_NUMBER",  // Use account instead of phone for M-Pesa till
    provider: "mptill"       // or "mpesa" for phone-based, "mpesa_offline"
  }
}

QR Code (South Africa)

{
  email: "customer@email.com",
  amount: "10000",
  qr: { provider: "scan-to-pay" }
}

EFT (South Africa)

{
  email: "customer@email.com",
  amount: "10000",
  eft: { provider: "ozow" }
}

Capitec Pay (South Africa)

{
  email: "customer@email.com",
  amount: "10000",
  capitec_pay: {
    identifier_key: "CELLPHONE",    // CELLPHONE | IDNUMBER | ACCOUNTNUMBER
    identifier_value: "0712345678"
  }
}

Bank Transfer (Pay with Transfer)

{
  email: "customer@email.com",
  amount: "10000",
  bank_transfer: {
    account_expires_at: "2024-12-31T23:59:59.000Z"  // Expiry for generated account
  }
}

Card (with authorization code)

{
  email: "customer@email.com",
  amount: "10000",
  authorization_code: "AUTH_72btv547",  // From a previous successful charge
  pin: "1234"                           // Only for non-reusable auth codes
}

Split Payment Parameters

Submit PIN

POST /charge/submit_pin

When data.status === "send_pin" in the charge response:

const result = await paystackRequest("/charge/submit_pin", {
  method: "POST",
  body: JSON.stringify({
    pin: "1234",
    reference: "5bwib5v6anhe9xa",
  }),
});

Submit OTP

POST /charge/submit_otp

When data.status === "send_otp":

const result = await paystackRequest("/charge/submit_otp", {
  method: "POST",
  body: JSON.stringify({
    otp: "123456",
    reference: "5bwib5v6anhe9xa",
  }),
});

Submit Phone

POST /charge/submit_phone

When data.status === "send_phone":

const result = await paystackRequest("/charge/submit_phone", {
  method: "POST",
  body: JSON.stringify({
    phone: "08012345678",
    reference: "5bwib5v6anhe9xa",
  }),
});

Submit Birthday

POST /charge/submit_birthday

When data.status === "send_birthday":

const result = await paystackRequest("/charge/submit_birthday", {
  method: "POST",
  body: JSON.stringify({
    birthday: "1995-12-23",
    reference: "5bwib5v6anhe9xa",
  }),
});

Submit Address

POST /charge/submit_address

When data.status === "send_address" (AVS — Address Verification System):

const result = await paystackRequest("/charge/submit_address", {
  method: "POST",
  body: JSON.stringify({
    reference: "7c7rpkqpc0tijs8",
    address: "140 N 2ND ST",
    city: "Stroudsburg",
    state: "PA",
    zipcode: "18360",
  }),
});

Check Pending Charge

GET /charge/:reference

When status is "pending", wait at least 10 seconds before checking:

const result = await paystackRequest<{
  status: string;
  reference: string;
  amount: number;
}>(`/charge/${encodeURIComponent(reference)}`);

// result.data.status: "success" | "failed" | "pending"

Full Charge Flow Example

async function processDirectCharge(chargeData: any) {
  let result = await paystackRequest<any>("/charge", {
    method: "POST",
    body: JSON.stringify(chargeData),
  });

  // Handle multi-step authentication
  while (result.data.status !== "success" && result.data.status !== "failed") {
    switch (result.data.status) {
      case "send_pin":
        const pin = await promptUserForPIN();
        result = await paystackRequest("/charge/submit_pin", {
          method: "POST",
          body: JSON.stringify({ pin, reference: result.data.reference }),
        });
        break;
      case "send_otp":
        const otp = await promptUserForOTP();
        result = await paystackRequest("/charge/submit_otp", {
          method: "POST",
          body: JSON.stringify({ otp, reference: result.data.reference }),
        });
        break;
      case "send_phone":
        const phone = await promptUserForPhone();
        result = await paystackRequest("/charge/submit_phone", {
          method: "POST",
          body: JSON.stringify({ phone, reference: result.data.reference }),
        });
        break;
      case "send_birthday":
        const birthday = await promptUserForBirthday();
        result = await paystackRequest("/charge/submit_birthday", {
          method: "POST",
          body: JSON.stringify({ birthday, reference: result.data.reference }),
        });
        break;
      case "send_address":
        const address = await promptUserForAddress();
        result = await paystackRequest("/charge/submit_address", {
          method: "POST",
          body: JSON.stringify({ ...address, reference: result.data.reference }),
        });
        break;
      case "pending":
        await new Promise((r) => setTimeout(r, 10000)); // Wait 10 seconds
        result = await paystackRequest(`/charge/${result.data.reference}`);
        break;
      default:
        throw new Error(`Unknown charge status: ${result.data.status}`);
    }
  }

  return result.data;
}

Important Notes

• The Charge API is more complex than the standard checkout — only use it when you need direct control over payment channels
• Some bank charges require birthday as part of the initial request
• For pending status, wait at least 10 seconds before polling to avoid rate limiting
• Mobile money providers vary by country: mtn, atl, vod for Ghana; mpesa for Kenya; orange, wave for Côte d'Ivoire
• USSD currently only supports 737 (GTBank) in Nigeria
• PIN and OTP submissions must happen server-side — never collect or transmit these on the client