Transaction

Overview

The Transaction class provides methods for interacting with Paystack’s Transaction API. This module allows you to initialize transactions, verify payments, list transactions, charge saved authorizations, and more.

Methods

initialize

Initializes a transaction from your backend.

async initialize(transaction: TxnInitializeInput): Promise<TxnInitializeSuccess | GenericError>

TxnInitializeInput

required

The transaction details to initialize.

Show properties

string

required

Amount to charge (in kobo for NGN, pesewas for GHS, cents for ZAR and USD)

string

required

Customer’s email address

'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'

Currency in which amount should be charged (defaults to NGN)

string

Unique transaction reference. Only alphanumeric characters allowed

string

Fully qualified URL to redirect to when transaction is completed

string

If transaction is to create a subscription, provide plan code here

number

Number of invoices to raise during subscription

any

Stringified JSON object of custom data

array

An array of payment channels to control what channels you want to make available to the user. Available channels: card, bank, ussd, qr, mobile_money, bank_transfer, eft, apple_pay

string

The split code of the transaction split

string

The code for the subaccount that owns the payment

string

A flat fee to charge the subaccount for this transaction

'account' | 'subaccount'

Who bears Paystack charges

object

Show properties

string

URL to redirect user to for payment

string

Access code for the transaction

string

Unique reference for this transaction

Example Usage:

const { data, error } = await paystack.transaction.initialize({
  amount: "20000",
  email: "customer@email.com",
  currency: "NGN",
  reference: "unique-reference-123",
});

if (error) {
  console.error("Transaction initialization failed:", error);
} else {
  console.log("Redirect user to:", data.authorization_url);
}

verify

Confirms the status of a transaction.

async verify(reference: string): Promise<TxnVerifySuccess | GenericError>

string

required

The transaction reference to verify

object

Show properties

number

Transaction ID

string

Domain type

string

Transaction status (success, failed, abandoned, etc.)

string

Transaction reference

number

Amount charged in kobo/cents

string

Currency code

string

Payment channel used

string

Gateway response message

object

Customer information object

object

Authorization details (for card payments)

any

Custom metadata passed during initialization

number

Fees charged

string

ISO datetime when payment was made

string

ISO datetime when transaction was created

Example Usage:

const { data, error } = await paystack.transaction.verify("reference-123");

if (error) {
  console.error("Verification failed:", error);
} else if (data.status === "success") {
  console.log("Payment successful:", data);
}

list

Lists transactions carried out on your integration.

async list(input: TxnListInput): Promise<TxnListSuccess | GenericError>

TxnListInput

required

Query parameters for listing transactions.

Show properties

number

Number of records to fetch per page (defaults to 50)

number

Page number to retrieve (defaults to 1)

string

Filter by customer ID

string

Filter by terminal ID

'success' | 'failed' | 'abandoned'

Filter by transaction status

Date

Start date for date range filter

string

End date for date range filter (ISO datetime)

array

Array of transaction objects

object

Show properties

string | null

Next page URL

string | null

Previous page URL

number

Records per page

Example Usage:

const { data, error } = await paystack.transaction.list({
  perPage: 100,
  page: 1,
  status: "success",
});

if (error) {
  console.error("Failed to list transactions:", error);
} else {
  console.log(`Found ${data.length} transactions`);
}

getTransactionById

Retrieves details of a transaction carried out on your integration.

async getTransactionById(id: number): Promise<TxnSingleSuccess | GenericError>

number

required

The ID of the transaction

object

Complete transaction object with all details (same structure as verify response)

Example Usage:

const { data, error } = await paystack.transaction.getTransactionById(12345);

if (error) {
  console.error("Failed to fetch transaction:", error);
} else {
  console.log("Transaction details:", data);
}

chargeAuthorization

Charges an authorization marked as reusable.

async chargeAuthorization(input: TxnChargeInput): Promise<TxnChargeSuccess | GenericError>

TxnChargeInput

required

The charge details.

Show properties

number

required

Amount to charge in kobo/cents

string

required

Customer’s email address

string

required

Valid authorization code to charge

string

Unique transaction reference

'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'

Currency in which amount should be charged

any

Custom data object

array

Payment channels to use (card or bank)

string

Subaccount code

number

Flat fee to charge the subaccount

'account' | 'subaccount'

Who bears Paystack charges (defaults to account)

boolean

Queue transaction (defaults to false)

object

Show properties

number

Amount charged

string

Currency code

string

ISO datetime of transaction

string

Transaction status

string

Transaction reference

object

Authorization details

object

Customer information

number

Transaction ID

Example Usage:

const { data, error } = await paystack.transaction.chargeAuthorization({
  amount: 10000,
  email: "customer@email.com",
  authorization_code: "AUTH_code123",
});

if (error) {
  console.error("Charge failed:", error);
} else {
  console.log("Charge successful:", data.status);
}

viewTxnTimeline

Views the timeline of a transaction.

async viewTxnTimeline(id_or_reference: string): Promise<TxnTimelineSuccess | GenericError>

string

required

The ID or reference of the transaction

object

Show properties

string

ISO time when transaction started

number

Time spent in milliseconds

number

Number of attempts

number

Number of errors

boolean

Whether transaction succeeded

boolean

Whether transaction was from mobile

array

Array of timeline events

Example Usage:

const { data, error } = await paystack.transaction.viewTxnTimeline("reference-123");

if (error) {
  console.error("Failed to fetch timeline:", error);
} else {
  console.log("Transaction timeline:", data.history);
}

getTxnTotals

Retrieves the total volume of transactions received on your integration.

async getTxnTotals(input: GenericInput): Promise<TxnTotalsSuccess | GenericError>

GenericInput

required

Query parameters for transaction totals.

Show properties

number

Records per page

number

Page number

string

Start date (ISO datetime)

string

End date (ISO datetime)

object

Show properties

number

Total number of transactions

number

Total transaction volume

array

Volume breakdown by currency

number

Pending transfers count

array

Pending transfers by currency

Example Usage:

const { data, error } = await paystack.transaction.getTxnTotals({
  perPage: 50,
  page: 1,
});

if (error) {
  console.error("Failed to fetch totals:", error);
} else {
  console.log(`Total transactions: ${data.total_transactions}`);
}

exportTxns

Exports a list of transactions carried out on your integration.

async exportTxns(input: TxnExportInput): Promise<TxnExportSuccess | GenericError>

TxnExportInput

required

Query parameters for exporting transactions.

Show properties

number

Records per page

number

Page number

string

Start date (ISO datetime)

string

End date (ISO datetime)

string

Customer ID filter

'success' | 'failed' | 'abandoned'

Transaction status filter

string

Currency filter

number

Amount filter

boolean

Settlement status filter

number

Settlement ID filter

number

Payment page ID filter

object

Show properties

string

URL to download the export file

string

ISO datetime when the export expires

Example Usage:

const { data, error } = await paystack.transaction.exportTxns({
  from: "2024-01-01T00:00:00Z",
  to: "2024-12-31T23:59:59Z",
  status: "success",
});

if (error) {
  console.error("Export failed:", error);
} else {
  console.log("Download export from:", data.path);
}

partialDebit

Retrieves part of a payment from a customer.

async partialDebit(input: TxnPartialDebitInput): Promise<TxnPartialDebitSuccess | GenericError>

TxnPartialDebitInput

required

The partial debit details.

Show properties

string

required

Authorization code for the transaction

'NGN' | 'GHS'

required

Currency (defaults to NGN)

number

required

Amount to debit

string

required

Customer’s email address

string

Unique transaction reference

number

Minimum amount to charge

object

Show properties

number

Amount charged

string

Currency code

string

Transaction status

string

Transaction reference

number

Originally requested amount

Example Usage:

const { data, error } = await paystack.transaction.partialDebit({
  authorization_code: "AUTH_code123",
  currency: "NGN",
  amount: 50000,
  email: "customer@email.com",
  at_least: 30000,
});

if (error) {
  console.error("Partial debit failed:", error);
} else {
  console.log(`Charged ${data.amount} of ${data.requested_amount}`);
}

Core

Modules

Overview

Methods

initialize

verify

list

getTransactionById

chargeAuthorization

viewTxnTimeline

getTxnTotals

exportTxns

partialDebit

​Overview

​Methods

​initialize

​verify

​list

​getTransactionById

​chargeAuthorization

​viewTxnTimeline

​getTxnTotals

​exportTxns

​partialDebit

​Related Guides

Overview

Methods

initialize

verify

list

getTransactionById

chargeAuthorization

viewTxnTimeline

getTxnTotals

exportTxns

partialDebit

Related Guides