rexedge/paystack-transactions

Paystack Transactions

The Transactions API lets you create and manage payments on your integration. This covers the entire transaction lifecycle from initialization through verification.

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

Transaction Lifecycle

Initialize (server) → Complete (client/redirect) → Verify (server) + Webhook

Endpoints

| Method | Endpoint | Description | | --- | --- | --- | | POST | /transaction/initialize | Initialize a transaction | | GET | /transaction/verify/:reference | Verify a transaction | | GET | /transaction | List transactions | | GET | /transaction/:id | Fetch a transaction | | POST | /transaction/charge_authorization | Charge a saved authorization | | GET | /transaction/timeline/:id_or_reference | View transaction timeline | | GET | /transaction/totals | Get transaction totals | | GET | /transaction/export | Export transactions as CSV | | POST | /transaction/partial_debit | Partial debit on an authorization |

Initialize Transaction

POST /transaction/initialize

Creates a payment and returns an authorization_url (for redirect) and access_code (for Popup/InlineJS).

Parameters (Body)

| Param | Type | Required | Description | | --- | --- | --- | --- | | amount | string | Yes | Amount in subunits (kobo). "50000" = NGN 500 | | email | string | Yes | Customer's email address | | reference | string | No | Unique ref. Alphanumeric + - . = only | | currency | string | No | NGN, USD, GHS, ZAR, KES. Defaults to integration currency | | callback_url | string | No | Override the dashboard callback URL | | channels | array | No | ["card","bank","ussd","qr","mobile_money","bank_transfer","eft","apple_pay"] | | plan | string | No | Plan code for subscription-based payment | | invoice_limit | integer | No | Max charges for subscription | | metadata | string | No | Stringified JSON with custom_fields array | | subaccount | string | No | Subaccount code e.g. ACCT_8f4s1eq7ml6rlzj | | split_code | string | No | Split code e.g. SPL_98WF13Eb3w | | transaction_charge | integer | No | Flat fee override for split (in subunits) | | bearer | string | No | "account" or "subaccount" — who pays Paystack fees |

Response

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/3ni8kdavz62431k",
    "access_code": "3ni8kdavz62431k",
    "reference": "re4lyvq3s3"
  }
}

Server Action Example (Next.js)

"use server";
import { paystackRequest } from "@/lib/paystack";

export async function initializePayment(email: string, amountInNaira: number) {
  const result = await paystackRequest<{
    authorization_url: string;
    access_code: string;
    reference: string;
  }>("/transaction/initialize", {
    method: "POST",
    body: JSON.stringify({
      email,
      amount: Math.round(amountInNaira * 100).toString(),
      callback_url: `${process.env.NEXT_PUBLIC_APP_URL}/payment/callback`,
    }),
  });
  return result.data;
}

Client-Side Popup (InlineJS)

"use client";
import PaystackInline from "@paystack/inline-js";

function PayButton({ email, amount }: { email: string; amount: number }) {
  const handlePay = async () => {
    // 1. Initialize on server
    const { access_code } = await initializePayment(email, amount);

    // 2. Open Popup with access_code
    const popup = new PaystackInline();
    popup.openIframe({
      accessCode: access_code,
      onSuccess: (response) => {
        // 3. Verify on server — NEVER trust this alone
        verifyTransaction(response.reference);
      },
      onClose: () => console.log("Payment window closed"),
    });
  };

  return <button onClick={handlePay}>Pay ₦{amount}</button>;
}

Redirect Method

After initializing, redirect the user to authorization_url. Paystack redirects back to your callback_url with ?trxref=REFERENCE&reference=REFERENCE in the query string. Verify server-side immediately.

// app/payment/callback/page.tsx
import { paystackRequest } from "@/lib/paystack";

export default async function PaymentCallback({
  searchParams,
}: {
  searchParams: Promise<{ reference?: string }>;
}) {
  const { reference } = await searchParams;
  if (!reference) return <p>No reference provided</p>;

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

  if (result.data.status === "success") {
    return <p>Payment successful!</p>;
  }
  return <p>Payment failed: {result.data.status}</p>;
}

Verify Transaction

GET /transaction/verify/:reference

Always verify server-side after payment. The reference is in the callback URL query params or returned from Popup's onSuccess.

const result = await paystackRequest<{
  id: number;
  status: "success" | "failed" | "abandoned";
  reference: string;
  amount: number;
  currency: string;
  channel: string;
  paid_at: string;
  authorization: {
    authorization_code: string;
    reusable: boolean;
    card_type: string;
    last4: string;
    bank: string;
  };
  customer: { email: string; id: number };
}>(`/transaction/verify/${encodeURIComponent(reference)}`);

Check result.data.status === "success" and validate result.data.amount matches expected amount before fulfilling the order.

List Transactions

GET /transaction

Query Parameters

| Param | Type | Description | | --- | --- | --- | | perPage | integer | Records per page (default 50) | | page | integer | Page number (default 1) | | customer | integer | Filter by customer ID | | terminalid | string | Filter by Terminal ID | | status | string | "success", "failed", or "abandoned" | | from | datetime | Start date e.g. 2024-01-01T00:00:00.000Z | | to | datetime | End date | | amount | integer | Filter by amount (in subunits) |

const params = new URLSearchParams({ status: "success", perPage: "20" });
const result = await paystackRequest<Transaction[]>(`/transaction?${params}`);

Fetch Transaction

GET /transaction/:id

Fetch a single transaction by its numeric ID.

const result = await paystackRequest<Transaction>(`/transaction/${transactionId}`);

Charge Authorization

POST /transaction/charge_authorization

Charge a customer's previously saved card (where authorization.reusable === true).

| Param | Type | Required | Description | | --- | --- | --- | --- | | amount | string | Yes | Amount in subunits | | email | string | Yes | Customer's email | | authorization_code | string | Yes | e.g. AUTH_72btv547 | | reference | string | No | Unique transaction reference | | currency | string | No | Currency code | | queue | boolean | No | Set true for scheduled/bulk charges |

const result = await paystackRequest<Transaction>(
  "/transaction/charge_authorization",
  {
    method: "POST",
    body: JSON.stringify({
      authorization_code: "AUTH_72btv547",
      email: "[email protected]",
      amount: "20000",
    }),
  }
);

Transaction Timeline

GET /transaction/timeline/:id_or_reference

Returns a step-by-step history of the transaction (attempted payment method, success/failure, time spent).

const result = await paystackRequest<{
  start_time: number;
  time_spent: number;
  attempts: number;
  errors: number;
  success: boolean;
  history: Array<{ type: string; message: string; time: number }>;
}>(`/transaction/timeline/${reference}`);

Transaction Totals

GET /transaction/totals

Returns aggregate volume and count. Supports from, to, perPage, page query params.

const result = await paystackRequest<{
  total_transactions: number;
  total_volume: number;
  total_volume_by_currency: Array<{ currency: string; amount: number }>;
  pending_transfers: number;
}>("/transaction/totals");

Export Transactions

GET /transaction/export

Returns a CSV download link. Supports all list filters plus settled, settlement, payment_page.

const params = new URLSearchParams({ from: "2024-01-01", status: "success" });
const result = await paystackRequest<{ path: string }>(
  `/transaction/export?${params}`
);
// result.data.path is a time-limited S3 URL to the CSV

Partial Debit

POST /transaction/partial_debit

Debit a portion of a customer's available balance on an authorization. Useful for metered billing.

| Param | Type | Required | Description | | --- | --- | --- | --- | | authorization_code | string | Yes | Auth code from previous transaction | | currency | string | Yes | NGN or GHS | | amount | string | Yes | Amount in subunits | | email | string | Yes | Customer email tied to the auth code | | reference | string | No | Unique reference | | at_least | string | No | Minimum amount to charge if full amount fails |

const result = await paystackRequest<Transaction>(
  "/transaction/partial_debit",
  {
    method: "POST",
    body: JSON.stringify({
      authorization_code: "AUTH_72btv547",
      currency: "NGN",
      amount: "20000",
      email: "[email protected]",
      at_least: "10000",
    }),
  }
);

Important Notes

• Transaction IDs are unsigned 64-bit integers — store as string in TypeScript to avoid precision loss
• Always verify server-side after payment — never trust client-side callbacks alone
• Amount validation: always confirm result.data.amount matches your expected amount after verification
• The authorization_code from a successful transaction can be saved and reused for future charges if authorization.reusable === true
• Metadata supports custom_fields for dashboard display — stringify the JSON before sending