Copy link Initialize Transaction

Create a new transaction

Request Body

emailrequiredstring
Customer's email address
amountrequiredinteger
Amount should be in smallest denomination of the currency.
currencystring
List of all support currencies
EnumGHSKESNGNZARUSD
referencestring
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
channelsarray[string]
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
callback_urlstring
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
planstring
If transaction is to create a subscription to a predefined plan, provide plan code here. This would invalidate the value provided in amount
invoice_limitinteger
Number of times to charge customer during subscription to plan
split_codestring
The split code of the transaction split
splitobject
Split configuration for transactions
6 object properties
namerequiredstring
Name of the transaction split
typerequiredstring
The type of transaction split you want to create.
Enumpercentageflat
subaccountsrequiredarray[object]
A list of object containing subaccount code and number of shares
currencyrequiredstring
The transaction currency
EnumNGNGHSZARUSD
bearer_typestring
This allows you specify how the transaction charge should be processed
Enumsubaccountaccountall-proportionalall
bearer_subaccountstring
This is the subaccount code of the customer or partner that would bear the transaction charge if you specified subaccount as the bearer type
subaccountstring
The code for the subaccount that owns the payment
transaction_chargestring
A flat fee to charge the subaccount for a transaction. This overrides the split percentage set when the subaccount was created
bearerstring
The bearer of the transaction charge
Enumaccountsubaccount
labelstring
Used to replace the email address shown on the Checkout
metadataobject
JSON object of custom data

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
3 object properties
authorization_urlrequiredstring
access_coderequiredstring
referencerequiredstring
POST/transaction/initialize
curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 10000
  }' \
  -X POST
import { 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.data
Response
{
  "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

emailrequiredstring
Customer's email address
amountrequiredinteger
Amount in the lower denomination of your currency
authorization_coderequiredstring
Valid authorization code to charge
referencestring
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
currencystring
List of all support currencies
EnumGHSKESNGNZARUSD
split_codestring
The split code of the transaction split
splitobject
Split configuration for transactions
6 object properties
namerequiredstring
Name of the transaction split
typerequiredstring
The type of transaction split you want to create.
Enumpercentageflat
subaccountsrequiredarray[object]
A list of object containing subaccount code and number of shares
currencyrequiredstring
The transaction currency
EnumNGNGHSZARUSD
bearer_typestring
This allows you specify how the transaction charge should be processed
Enumsubaccountaccountall-proportionalall
bearer_subaccountstring
This is the subaccount code of the customer or partner that would bear the transaction charge if you specified subaccount as the bearer type
subaccountstring
The code for the subaccount that owns the payment
transaction_chargestring
A flat fee to charge the subaccount for a transaction. This overrides the split percentage set when the subaccount was created
bearerstring
The bearer of the transaction charge
Enumaccountsubaccount
metadatastring
Stringified JSON object of custom data
queueboolean
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
statusrequiredboolean
messagerequiredstring
datarequiredobject
17 object properties
amountrequiredinteger
currencyrequiredstring
transaction_daterequiredstring
statusrequiredstring
referencerequiredstring
domainrequiredstring
metadatarequiredstring
gateway_responserequiredstring
messagerequiredstring
channelrequiredstring
ip_addressrequiredstring
logrequiredobject
8 object properties
start_timerequiredinteger
time_spentrequiredinteger
attemptsrequiredinteger
errorsrequiredinteger
successrequiredboolean
mobilerequiredboolean
inputrequiredarray[object]
historyrequiredarray[object]
feesrequiredinteger
authorizationrequiredobject
13 object properties
authorization_coderequiredstring
binrequiredstring
last4requiredstring
exp_monthrequiredstring
exp_yearrequiredstring
channelrequiredstring
card_typerequiredstring
bankrequiredstring
country_coderequiredstring
brandrequiredstring
reusablerequiredboolean
signaturerequiredstring
account_namerequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
1 object property
calling_codestring
risk_actionrequiredstring
international_format_phonerequiredstring
planrequiredstring
idrequiredinteger
POST/transaction/charge_authorization
curl 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 POST
import { 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.data
Response
{
  "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

emailrequiredstring
Customer's email address
amountrequiredintegerint64
Specified in the lowest denomination of your currency
authorization_coderequiredstring
Valid authorization code to charge
currencyrequiredstring
List of all support currencies
EnumGHSKESNGNZARUSD
at_leaststring
Minimum amount to charge
referencestring
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
18 object properties
amountrequiredinteger
currencyrequiredstring
transaction_daterequiredstring
statusrequiredstring
referencerequiredstring
domainrequiredstring
metadatarequiredstring
gateway_responserequiredstring
messagerequiredstring
channelrequiredstring
ip_addressrequiredstring
logrequiredobject
8 object properties
start_timerequiredinteger
time_spentrequiredinteger
attemptsrequiredinteger
errorsrequiredinteger
successrequiredboolean
mobilerequiredboolean
inputrequiredarray[object]
historyrequiredarray[object]
feesrequiredinteger
authorizationrequiredobject
13 object properties
authorization_coderequiredstring
binrequiredstring
last4requiredstring
exp_monthrequiredstring
exp_yearrequiredstring
channelrequiredstring
card_typerequiredstring
bankrequiredstring
country_coderequiredstring
brandrequiredstring
reusablerequiredboolean
signaturerequiredstring
account_namerequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
planrequiredinteger
requested_amountrequiredinteger
idrequiredinteger
POST/transaction/partial_debit
curl 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 POST
import { 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.data
Response
{
  "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

referencerequiredstring
The transaction reference to verify

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
32 object properties
idrequiredinteger
domainrequiredstring
statusrequiredstring
referencerequiredstring
receipt_numberrequiredstring
amountrequiredinteger
messagerequiredstring
gateway_responserequiredstring
paid_atrequiredstring
created_atrequiredstring
channelrequiredstring
currencyrequiredstring
ip_addressrequiredstring
metadatarequiredstring
logrequiredobject
8 object properties
start_timerequiredinteger
time_spentrequiredinteger
attemptsrequiredinteger
errorsrequiredinteger
successrequiredboolean
mobilerequiredboolean
inputrequiredarray[object]
historyrequiredarray[object]
feesrequiredinteger
fees_splitrequiredstring
authorizationrequiredobject
15 object properties
authorization_codestring
binstring
last4string
exp_monthstring
exp_yearstring
channelstring
card_typestring
bankstring
country_codestring
brandstring
reusableboolean
signaturestring
account_namestring
receiver_bank_account_numberstring
receiver_bankstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredstring
risk_actionrequiredstring
international_format_phonerequiredstring
planrequiredstring
splitrequiredobject
order_idrequiredstring
paidAtrequiredstring
createdAtrequiredstring
requested_amountrequiredinteger
pos_transaction_datarequiredstring
sourcerequiredstring
fees_breakdownrequiredstring
connectrequiredstring
transaction_daterequiredstring
plan_objectrequiredobject
9 object properties
idinteger
namestring
plan_codestring
descriptionstring
amountinteger
intervalstring
send_invoicesboolean
send_smsboolean
currencystring
subaccountrequiredobject
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.data
Response
{
  "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

use_cursorboolean
A flag to indicate if cursor based pagination should be used
nextstring
An alphanumeric value returned for every cursor based retrieval, used to retrieve the next set of data
previousstring
An alphanumeric value returned for every cursor based retrieval, used to retrieve the previous set of data
per_pageinteger
The number of records to fetch per request
pageinteger
The offset to retrieve data from
fromstring
The start date
tostring
The end date
statusstring
Filter transaction by status
Enumsuccessfailedabandonedreversed
sourcestring
The origin of the payment
EnummerchantApicheckoutposvirtualTerminal
terminal_idstring
Filter transactions by a terminal ID
virtual_account_numberstring
Filter transactions by a virtual account number
customer_codestring
Filter transactions by a customer code
amountinteger
Filter transactions by a specific amount
settlementinteger
The settlement ID to filter for settled transactions
channelstring
The payment method the customer used to complete the transaction
Enumcardposbankdedicated_nubanussdbank_transfer
subaccount_codestring
Filter transaction by subaccount code
split_codestring
Filter transaction by split code

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
6 object properties
totalrequiredinteger
total_volumerequirednumber
skippedrequiredinteger
perPagerequiredstring
pagerequiredinteger
pageCountrequiredinteger
GET/transaction
curl 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.data
Response
{
  "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

idrequiredinteger
The ID of the transaction to fetch

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
31 object properties
idrequiredinteger
domainrequiredstring
statusrequiredstring
referencerequiredstring
receipt_numberrequiredstring
amountrequiredinteger
messagerequiredstring
gateway_responserequiredstring
helpdesk_linkrequiredstring
paid_atrequiredstring
created_atrequiredstring
channelrequiredstring
currencyrequiredstring
ip_addressrequiredstring
metadatarequiredobject
1 object property
custom_fieldsrequiredarray[object]
logrequiredobject
8 object properties
start_timerequiredinteger
time_spentrequiredinteger
attemptsrequiredinteger
errorsrequiredinteger
successrequiredboolean
mobilerequiredboolean
inputrequiredarray[object]
historyrequiredarray[object]
feesrequiredinteger
fees_splitrequiredinteger
authorizationrequiredobject
15 object properties
authorization_coderequiredstring
binrequiredstring
last4requiredstring
exp_monthrequiredstring
exp_yearrequiredstring
channelrequiredstring
card_typerequiredstring
bankrequiredstring
country_coderequiredstring
brandrequiredstring
reusablerequiredboolean
signaturerequiredstring
account_namerequiredstring
receiver_bank_account_numberrequiredstring
receiver_bankrequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
planrequiredobject
subaccountrequiredobject
splitrequiredobject
order_idrequiredstring
paidAtrequiredstring
createdAtrequiredstring
requested_amountrequiredinteger
pos_transaction_datarequiredstring
sourcerequiredobject
3 object properties
typerequiredstring
sourcerequiredstring
identifierrequiredstring
fees_breakdownrequiredstring
connectrequiredstring
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.data
Response
{
  "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

idrequiredinteger
The ID of the transaction to fetch

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
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.data
Response
{
  "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

fromstring
The start date
tostring
The end date

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
5 object properties
total_transactionsrequiredinteger
total_volumerequiredinteger
total_volume_by_currencyrequiredarray[object]
pending_transfersrequiredinteger
pending_transfers_by_currencyrequiredarray[object]
GET/transaction/totals
curl 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.data
Response
{
  "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

fromstring
The start date
tostring
The end date
statusstring
Filter by the status of the transaction
Enumsuccessfailedabandonedreversedall
customernumber
Filter by customer ID
subaccount_codestring
Filter by subaccount code
settlementinteger
Filter by the settlement ID

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
2 object properties
pathrequiredstring
expiresAtrequiredstring
GET/transaction/export
curl 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.data
Response
{
  "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
}