Transaction
A collection of endpoints for managing payments
Copy link Initialize Transaction
Create a new transaction
Request Body
Customer's email address
Amount should be in smallest denomination of the currency.
List of all support currencies
EnumGHSKESNGNZARUSD
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
An array of payment channels to control what channels you want to make available to the user to make a payment with
Array values (10)
apple_paybankbank_transfercapitec_paycardeftmobile_moneypayattitudeqrussd
Fully qualified url, e.g. https://example.com/ to redirect your customers to after a successful payment. Use this to override the callback url provided on the dashboard for this transaction
If transaction is to create a subscription to a predefined plan, provide plan code here.
This would invalidate the value provided in amount
Number of times to charge customer during subscription to plan
The split code of the transaction split
Split configuration for transactions
6 object properties
Name of the transaction split
The type of transaction split you want to create.
Enumpercentageflat
A list of object containing subaccount code and number of shares
The transaction currency
EnumNGNGHSZARUSD
This allows you specify how the transaction charge should be processed
Enumsubaccountaccountall-proportionalall
This is the subaccount code of the customer or partner that would bear the transaction charge if you specified subaccount as the bearer type
The code for the subaccount that owns the payment
A flat fee to charge the subaccount for a transaction.
This overrides the split percentage set when the subaccount was created
The bearer of the transaction charge
Enumaccountsubaccount
Used to replace the email address shown on the Checkout
JSON object of custom data
Response
200
3 object properties
POST
/transaction/initializecurl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 10000
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.initialize({
email: "[email protected]",
amount: 10000
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.initialize({
email: "[email protected]",
amount: 10000
})
puts response.dataResponse
{
"status": true,
"message": "Authorization URL created",
"data": {
"authorization_url": "https://checkout.paystack.com/3ni8kdavz62431k",
"access_code": "3ni8kdavz62431k",
"reference": "re4lyvq3s3"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "validation_error",
"code": "string",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Charge Authorization
Charge all authorizations marked as reusable with this endpoint whenever you need to receive payments
Request Body
Customer's email address
Amount in the lower denomination of your currency
Valid authorization code to charge
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
List of all support currencies
EnumGHSKESNGNZARUSD
The split code of the transaction split
Split configuration for transactions
6 object properties
Name of the transaction split
The type of transaction split you want to create.
Enumpercentageflat
A list of object containing subaccount code and number of shares
The transaction currency
EnumNGNGHSZARUSD
This allows you specify how the transaction charge should be processed
Enumsubaccountaccountall-proportionalall
This is the subaccount code of the customer or partner that would bear the transaction charge if you specified subaccount as the bearer type
The code for the subaccount that owns the payment
A flat fee to charge the subaccount for a transaction.
This overrides the split percentage set when the subaccount was created
The bearer of the transaction charge
Enumaccountsubaccount
Stringified JSON object of custom data
If you are making a scheduled charge call, it is a good idea to queue them so the processing system does not get overloaded causing transaction processing errors.
Response
200
17 object properties
8 object properties
13 object properties
9 object properties
1 object property
POST
/transaction/charge_authorizationcurl https://api.paystack.co/transaction/charge_authorization \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 30000,
"authorization_code": "AUTH_df1l5ehnym"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.chargeAuthorization({
email: "[email protected]",
amount: 30000,
authorization_code: "AUTH_df1l5ehnym"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.charge_authorization({
email: "[email protected]",
amount: 30000,
authorization_code: "AUTH_df1l5ehnym"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"amount": 35247,
"currency": "NGN",
"transaction_date": "2024-08-22T10:53:49.000Z",
"status": "success",
"reference": "0m7frfnr47ezyxl",
"domain": "test",
"metadata": "",
"gateway_response": "Approved",
"message": null,
"channel": "card",
"ip_address": null,
"log": null,
"fees": 10247,
"authorization": {
"authorization_code": "AUTH_uh8bcl3zbn",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
},
"customer": {
"id": 181873746,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_1rkzaqsv4rrhqo6",
"phone": null,
"metadata": {
"custom_fields": [
{
"display_name": "Customer email",
"variable_name": "customer_email",
"value": "[email protected]"
}
]
},
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"id": 4099490251
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Partial Debit
Retrieve part of a payment from a customer
Request Body
Customer's email address
Specified in the lowest denomination of your currency
Valid authorization code to charge
List of all support currencies
EnumGHSKESNGNZARUSD
Minimum amount to charge
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
Response
200
18 object properties
8 object properties
13 object properties
9 object properties
POST
/transaction/partial_debitcurl https://api.paystack.co/transaction/partial_debit \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 40510,
"authorization_code": "AUTH_df1l5ehnym",
"currency": "GHS"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.partialDebit({
email: "[email protected]",
amount: 40510,
authorization_code: "AUTH_df1l5ehnym",
currency: "GHS"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.partial_debit({
email: "[email protected]",
amount: 40510,
authorization_code: "AUTH_df1l5ehnym",
currency: "GHS"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"amount": 50000,
"currency": "NGN",
"transaction_date": "2024-08-22T11:13:48.000Z",
"status": "success",
"reference": "ofuhmnzw05vny9j",
"domain": "test",
"metadata": "",
"gateway_response": "Approved",
"message": null,
"channel": "card",
"ip_address": null,
"log": null,
"fees": 10350,
"authorization": {
"authorization_code": "AUTH_uh8bcl3zbn",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
},
"customer": {
"id": 181873746,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_1rkzaqsv4rrhqo6",
"phone": null,
"metadata": {
"custom_fields": [
{
"display_name": "Customer email",
"variable_name": "customer_email",
"value": "[email protected]"
}
]
},
"risk_action": "default",
"international_format_phone": null
},
"plan": 0,
"requested_amount": 50000,
"id": 4099546180
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Verify Transaction
Verify a previously initiated transaction using it's reference
Path Parameters
The transaction reference to verify
Response
200
32 object properties
8 object properties
15 object properties
9 object properties
9 object properties
GET
/transaction/verify/{reference}curl https://api.paystack.co/transaction/verify/re4lyvq3s3 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.verify("re4lyvq3s3");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.verify("re4lyvq3s3")
puts response.dataResponse
{
"status": true,
"message": "Verification successful",
"data": {
"id": 4099260516,
"domain": "test",
"status": "success",
"reference": "re4lyvq3s3",
"receipt_number": null,
"amount": 40333,
"message": null,
"gateway_response": "Successful",
"paid_at": "2024-08-22T09:15:02.000Z",
"created_at": "2024-08-22T09:14:24.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": "197.210.54.33",
"metadata": "",
"log": {
"start_time": 1724318098,
"time_spent": 4,
"attempts": 1,
"errors": 0,
"success": true,
"mobile": false,
"input": [],
"history": [
{
"type": "action",
"message": "Attempted to pay with card",
"time": 3
},
{
"type": "success",
"message": "Successfully paid with card",
"time": 4
}
]
},
"fees": 10283,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_uh8bcl3zbn",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
},
"customer": {
"id": 181873746,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_1rkzaqsv4rrhqo6",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"split": {},
"order_id": null,
"paidAt": "2024-08-22T09:15:02.000Z",
"createdAt": "2024-08-22T09:14:24.000Z",
"requested_amount": 30050,
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null,
"connect": null,
"transaction_date": "2024-08-22T09:14:24.000Z",
"plan_object": {},
"subaccount": {}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link List Transactions
List transactions that has occurred on your integration
Query Parameters
A flag to indicate if cursor based pagination should be used
An alphanumeric value returned for every cursor based retrieval, used to retrieve the next set of data
An alphanumeric value returned for every cursor based retrieval, used to retrieve the previous set of data
The number of records to fetch per request
The offset to retrieve data from
The start date
The end date
Filter transaction by status
Enumsuccessfailedabandonedreversed
The origin of the payment
EnummerchantApicheckoutposvirtualTerminal
Filter transactions by a terminal ID
Filter transactions by a virtual account number
Filter transactions by a customer code
Filter transactions by a specific amount
The settlement ID to filter for settled transactions
The payment method the customer used to complete the transaction
Enumcardposbankdedicated_nubanussdbank_transfer
Filter transaction by subaccount code
Filter transaction by split code
Response
200
6 object properties
GET
/transactioncurl https://api.paystack.co/transaction \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.list({
use_cursor: true,
next: "NEXT"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.list({
use_cursor: true,
next: "NEXT"
})
puts response.dataResponse
{
"status": true,
"message": "Transactions retrieved",
"data": [
{
"id": 4099260516,
"domain": "test",
"status": "success",
"reference": "re4lyvq3s3",
"amount": 40333,
"message": null,
"gateway_response": "Successful",
"paid_at": "2024-08-22T09:15:02.000Z",
"created_at": "2024-08-22T09:14:24.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": "197.210.54.33",
"metadata": null,
"log": {
"start_time": 1724318098,
"time_spent": 4,
"attempts": 1,
"errors": 0,
"success": true,
"mobile": false,
"input": [],
"history": [
{
"type": "action",
"message": "Attempted to pay with card",
"time": 3
},
{
"type": "success",
"message": "Successfully paid with card",
"time": 4
}
]
},
"fees": 10283,
"fees_split": null,
"customer": {
"id": 181873746,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"phone": null,
"metadata": {
"custom_fields": [
{
"display_name": "Customer email",
"variable_name": "customer_email",
"value": "[email protected]"
}
]
},
"customer_code": "CUS_1rkzaqsv4rrhqo6",
"risk_action": "default"
},
"authorization": {
"authorization_code": "AUTH_uh8bcl3zbn",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
},
"plan": {},
"split": {},
"subaccount": {},
"order_id": null,
"paidAt": "2024-08-22T09:15:02.000Z",
"createdAt": "2024-08-22T09:14:24.000Z",
"requested_amount": 30050,
"source": {
"source": "merchant_api",
"type": "api",
"identifier": null,
"entry_point": "transaction_initialize"
},
"connect": null,
"pos_transaction_data": null
}
],
"meta": {
"next": "dW5kZWZpbmVkOjQwMTM3MDk2MzU=",
"previous": null,
"perPage": 50
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Transaction
Fetch a transaction to get its details
Path Parameters
The ID of the transaction to fetch
Response
200
31 object properties
1 object property
8 object properties
15 object properties
9 object properties
3 object properties
GET
/transaction/{id}curl https://api.paystack.co/transaction/4099260516 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.fetch("4099260516");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.fetch("4099260516")
puts response.dataResponse
{
"status": true,
"message": "Transaction retrieved",
"data": {
"id": 4099260516,
"domain": "test",
"status": "success",
"reference": "re4lyvq3s3",
"receipt_number": null,
"amount": 40333,
"message": null,
"gateway_response": "Successful",
"helpdesk_link": null,
"paid_at": "2024-08-22T09:15:02.000Z",
"created_at": "2024-08-22T09:14:24.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": "197.210.54.33",
"metadata": "",
"log": {
"start_time": 1724318098,
"time_spent": 4,
"attempts": 1,
"errors": 0,
"success": true,
"mobile": false,
"input": [],
"history": [
{
"type": "action",
"message": "Attempted to pay with card",
"time": 3
},
{
"type": "success",
"message": "Successfully paid with card",
"time": 4
}
]
},
"fees": 10283,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_uh8bcl3zbn",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2030",
"channel": "card",
"card_type": "visa ",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
"account_name": null
},
"customer": {
"id": 181873746,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_1rkzaqsv4rrhqo6",
"phone": null,
"metadata": {
"custom_fields": [
{
"display_name": "Customer email",
"variable_name": "customer_email",
"value": "[email protected]"
}
]
},
"risk_action": "default",
"international_format_phone": null
},
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2024-08-22T09:15:02.000Z",
"createdAt": "2024-08-22T09:14:24.000Z",
"requested_amount": 30050,
"pos_transaction_data": null,
"source": {
"type": "api",
"source": "merchant_api",
"identifier": null
},
"fees_breakdown": null,
"connect": null
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Transaction Timeline
Fetch the steps taken from the initiation to the completion of a transaction
Path Parameters
The ID of the transaction to fetch
Response
200
GET
/transaction/timeline/{id}curl https://api.paystack.co/transaction/timeline/3936799950 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.timeline("3936799950");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.timeline("3936799950")
puts response.dataResponse
{
"status": true,
"message": "Timeline retrieved",
"data": {
"start_time": 1724318098,
"time_spent": 4,
"attempts": 1,
"errors": 0,
"success": true,
"mobile": false,
"input": [],
"history": [
{
"type": "action",
"message": "Attempted to pay with card",
"time": 3
},
{
"type": "success",
"message": "Successfully paid with card",
"time": 4
}
]
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Transaction Totals
Get the total amount of all transactions
Query Parameters
The start date
The end date
Response
200
5 object properties
GET
/transaction/totalscurl https://api.paystack.co/transaction/totals \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.totals({
from: "2024-06-01T00:00:01Z",
to: "2024-06-30T13:36:54Z"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.totals({
from: "2024-06-01T00:00:01Z",
to: "2024-06-30T13:36:54Z"
})
puts response.dataResponse
{
"status": true,
"message": "Transaction totals",
"data": {
"total_transactions": 42670,
"total_volume": 6617829946,
"total_volume_by_currency": [
{
"currency": "NGN",
"amount": 6617829946
},
{
"currency": "USD",
"amount": 28000
}
],
"pending_transfers": 6617829946,
"pending_transfers_by_currency": [
{
"currency": "NGN",
"amount": 6617829946
},
{
"currency": "USD",
"amount": 28000
}
]
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Export Transactions
Download transactions that occurred on your integration for a specific timeframe
Query Parameters
The start date
The end date
Filter by the status of the transaction
Enumsuccessfailedabandonedreversedall
Filter by customer ID
Filter by subaccount code
Filter by the settlement ID
Response
200
2 object properties
GET
/transaction/exportcurl https://api.paystack.co/transaction/export \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.transaction.export({
from: "2024-06-01T00:00:01Z",
to: "2024-06-30T13:36:54Z"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.transaction.export({
from: "2024-06-01T00:00:01Z",
to: "2024-06-30T13:36:54Z"
})
puts response.dataResponse
{
"status": true,
"message": "Export successful",
"data": {
"path": "https://s3.eu-west-1.amazonaws.com/files.paystack.co/exports/463433/transactions/Integration_name_transactions_1724324423843.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI7CL5IZL2DJHOPPA%2F20240822%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20240822T110023Z&X-Amz-Expires=60&X-Amz-Signature=40525f4f361e07c09a445a1a6888d135758abd507ed988ee744c2d94ea14cf1e&X-Amz-SignedHeaders=host",
"expiresAt": "2024-08-22 11:01:23"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}