Sign in

Paystack Documentation

Welcome to the Paystack Developer Documentation where you'll learn how to build amazing payment experiences with the Paystack API.

Quick start

Accept a payment

Take a test card payment in three API calls, then confirm it on your server before you give value.

Before you begin

Copy your test secret key from Developers → API configuration on your Paystack Dashboard and set it as PAYSTACK_SECRET_KEY. Node.js samples need Node 18 or later, saved as an .mjs file.

  1. Start the payment from your server. The response has a checkout link (authorization_url) and a reference.

    Used in the request and response.

    500000 cents is KES 5,000

POSTapi.paystack.co/transaction/initialize

# Create a transaction. 500000 cents is KES 5,000.
curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 500000
  }' \
  -X POST
// Create a transaction. 500000 cents is KES 5,000.
const key = process.env.PAYSTACK_SECRET_KEY;
const url =
  "https://api.paystack.co/transaction/initialize";
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "amount": 500000
  }),
});
const { data } = await response.json();

// Open authorization_url to pay. Keep the reference.
console.log(data.authorization_url, data.reference);
Test card
Card number   4084 0840 8408 4081
CVV           408
Expiry date   Any date in the future

GETapi.paystack.co/transaction/verify/:reference

# Check the payment on your server before you give value.
# Replace REFERENCE with the reference from step 1.
curl https://api.paystack.co/transaction/verify/REFERENCE \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY"
// Replace REFERENCE with the reference from step 1.
const reference = "REFERENCE";
const key = process.env.PAYSTACK_SECRET_KEY;
const url =
  `https://api.paystack.co/transaction/verify/${reference}`;
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}` },
});
const { data } = await response.json();

// Give value only if status is "success" and amounts match.
console.log(data.status, data.amount);
// Save this code to charge the card again later.
console.log(data.authorization.authorization_code);

Run all 3 steps in one file

Copy accept-payment.mjs with your values, then run node accept-payment.mjs.

Make a transfer

Pay an M-PESA number from your Paystack balance. In test mode, no money leaves your account.

  1. Save the account you want to pay. The response has a recipient_code you use to send money.

POSTapi.paystack.co/transferrecipient

# Save the M-PESA number to pay. MPESA is its bank code.
# Confirm the number with your customer before you pay.
curl https://api.paystack.co/transferrecipient \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_money",
    "name": "Wanjiru Kamau",
    "account_number": "0712345678",
    "bank_code": "MPESA",
    "currency": "KES"
  }' \
  -X POST
// Save the M-PESA number to pay. MPESA is its bank code.
// Confirm the number with your customer before you pay.
const key = process.env.PAYSTACK_SECRET_KEY;
const url = "https://api.paystack.co/transferrecipient";
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "mobile_money",
    "name": "Wanjiru Kamau",
    "account_number": "0712345678",
    "bank_code": "MPESA",
    "currency": "KES"
  }),
});
const { data } = await response.json();

// Save the recipient_code to pay this account again.
console.log(data.recipient_code);

POSTapi.paystack.co/transfer

# Send KES 1,000 (100000 cents) from your balance.
# Replace RECIPIENT_CODE with the code from step 1.
# Use a new reference for each transfer; reuse it to retry.
curl https://api.paystack.co/transfer \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "balance",
    "amount": 100000,
    "currency": "KES",
    "recipient": "RECIPIENT_CODE",
    "reference": "my_first_transfer_0001"
  }' \
  -X POST
// Send KES 1,000 (100000 cents) from your balance.
const key = process.env.PAYSTACK_SECRET_KEY;
const url = "https://api.paystack.co/transfer";
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "balance",
    amount: 100000,
    currency: "KES",
    // Replace RECIPIENT_CODE with the code from step 1.
    recipient: "RECIPIENT_CODE",
    // A new reference for each transfer; reuse it to retry.
    reference: `transfer_${Date.now()}`,
  }),
});
const { data } = await response.json();

// If status is "otp", finalize it with the OTP you got.
console.log(data.status, data.reference);

GETapi.paystack.co/transfer/verify/:reference

# Replace REFERENCE with the reference from step 2.
# In production, listen for transfer.success instead.
curl https://api.paystack.co/transfer/verify/REFERENCE \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY"
// Replace REFERENCE with the reference from step 2.
const reference = "REFERENCE";
const key = process.env.PAYSTACK_SECRET_KEY;
const url =
  `https://api.paystack.co/transfer/verify/${reference}`;
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}` },
});
const { data } = await response.json();

// In production, listen for transfer.success instead.
console.log(data.status);

Run all 3 steps in one file

Copy make-transfer.mjs with your values, then run node make-transfer.mjs.