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>

transaction

TxnInitializeInput

required

The transaction details to initialize.

Show properties

amount

string

required

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

string

required

Customer’s email address

currency

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

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

reference

string

Unique transaction reference. Only alphanumeric characters allowed

callback_url

string

Fully qualified URL to redirect to when transaction is completed

plan

string

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

invoice_limit

number

Number of invoices to raise during subscription

metadata

any

Stringified JSON object of custom data

channels

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

split_code

string

The split code of the transaction split

subaccount

string

The code for the subaccount that owns the payment

transaction_charge

string

A flat fee to charge the subaccount for this transaction

bearer

'account' | 'subaccount'

Who bears Paystack charges

data

object

Show properties

authorization_url

string

URL to redirect user to for payment

access_code

string

Access code for the transaction

reference

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>

reference

string

required

The transaction reference to verify

data

object

Show properties

number

Transaction ID

domain

string

Domain type

status

string

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

reference

string

Transaction reference

amount

number

Amount charged in kobo/cents

currency

string

Currency code

channel

string

Payment channel used

gateway_response

string

Gateway response message

customer

object

Customer information object

authorization

object

Authorization details (for card payments)

metadata

any

Custom metadata passed during initialization

fees

number

Fees charged

paidAt

string

ISO datetime when payment was made

createdAt

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>

input

TxnListInput

required

Query parameters for listing transactions.

Show properties

perPage

number

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

page

number

Page number to retrieve (defaults to 1)

customer

string

Filter by customer ID

terminalId

string

Filter by terminal ID

status

'success' | 'failed' | 'abandoned'

Filter by transaction status

from

Date

Start date for date range filter

string

End date for date range filter (ISO datetime)

data

array

Array of transaction objects

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

data

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>

input

TxnChargeInput

required

The charge details.

Show properties

amount

number

required

Amount to charge in kobo/cents

string

required

Customer’s email address

authorization_code

string

required

Valid authorization code to charge

reference

string

Unique transaction reference

currency

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

Currency in which amount should be charged

metadata

any

Custom data object

channels

array

Payment channels to use (card or bank)

subaccount

string

Subaccount code

transaction_charge

number

Flat fee to charge the subaccount

bearer

'account' | 'subaccount'

Who bears Paystack charges (defaults to account)

queue

boolean

Queue transaction (defaults to false)

data

object

Show properties

amount

number

Amount charged

currency

string

Currency code

transaction_date

string

ISO datetime of transaction

status

string

Transaction status

reference

string

Transaction reference

authorization

object

Authorization details

customer

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>

id_or_reference

string

required

The ID or reference of the transaction

data

object

Show properties

start_time

string

ISO time when transaction started

time_spent

number

Time spent in milliseconds

attempts

number

Number of attempts

errors

number

Number of errors

success

boolean

Whether transaction succeeded

mobile

boolean

Whether transaction was from mobile

history

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>

input

GenericInput

required

Query parameters for transaction totals.

Show properties

perPage

number

Records per page

page

number

Page number

from

string

Start date (ISO datetime)

string

End date (ISO datetime)

data

object

Show properties

total_transactions

number

Total number of transactions

total_volume

number

Total transaction volume

total_volume_by_currency

array

Volume breakdown by currency

pending_transfers

number

Pending transfers count

pending_transfers_by_currency

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>

input

TxnExportInput

required

Query parameters for exporting transactions.

Show properties

perPage

number

Records per page

page

number

Page number

from

string

Start date (ISO datetime)

string

End date (ISO datetime)

customer

string

Customer ID filter

status

'success' | 'failed' | 'abandoned'

Transaction status filter

currency

string

Currency filter

amount

number

Amount filter

settled

boolean

Settlement status filter

settlement

number

Settlement ID filter

payment_page

number

Payment page ID filter

data

object

Show properties

path

string

URL to download the export file

expiresAt

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>

input

TxnPartialDebitInput

required

The partial debit details.

Show properties

authorization_code

string

required

Authorization code for the transaction

currency

'NGN' | 'GHS'

required

Currency (defaults to NGN)

amount

number

required

Amount to debit

string

required

Customer’s email address

reference

string

Unique transaction reference

at_least

number

Minimum amount to charge

data

object

Show properties

amount

number

Amount charged

currency

string

Currency code

status

string

Transaction status

reference

string

Transaction reference

requested_amount

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

Core

Modules

​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