api
Cancel

No result found for:

Transactions

The Transactions API allows you create and manage payments on your integration.

Initialize Transaction

Initialize a transaction from your backend

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
amount
String
Amount should be in the subunit of the supported currency
email
String
Customer's email address
currency
String
The transaction currency. Defaults to your integration currency.
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
callback_url
String
Fully qualified url, e.g. https://example.com/ . Use this to override the callback url provided on the dashboard for this transaction
plan
String
If transaction is to create a subscription to a predefined plan, provide plan code here. This would invalidate the value provided in amount
invoice_limit
Integer
Number of times to charge customer during subscription to plan
metadata
String
Stringified JSON object of custom data. Kindly check the Metadata page for more information.
channels
Array
An array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include: ["card", "bank", "ussd", "qr", "mobile_money", "bank_transfer", "eft"]
split_code
String
The split code of the transaction split. e.g. SPL_98WF13Eb3w
subaccount
String
The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_charge
Integer
An amount used to override the split configuration for a single split payment. If set, the amount specified goes to the main account regardless of the split configuration.
bearer
String
Who bears Paystack charges? account or subaccount (defaults to account).
Show optional parameters
POST/transaction/initialize
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/initialize"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "email": "customer@email.com", 
7  "amount": "20000"
8}'
9

10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Authorization URL created",
4  "data": {
5    "authorization_url": "https://checkout.paystack.com/0peioxfhpn",
6    "access_code": "0peioxfhpn",
7    "reference": "7PVGX8MEk85tgeEpVDtD"
8  }
9}

Verify Transaction

Confirm the status of a transaction

Transaction ID data type

If you plan to store or make use of the the transaction ID, you should represent it as a unsigned 64-bit integer. To learn more, check out our changelog.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
reference
String
The transaction reference used to intiate the transaction
GET/transaction/verify/:reference
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/verify/{reference}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Verification successful",
4  "data": {
5    "id": 2009945086,
6    "domain": "test",
7    "status": "success",
8    "reference": "rd0bz6z2wu",
9    "amount": 20000,
10    "message": null,
11    "gateway_response": "Successful",
12    "paid_at": "2022-08-09T14:21:32.000Z",
13    "created_at": "2022-08-09T14:20:57.000Z",
14    "channel": "card",
15    "currency": "NGN",
16    "ip_address": "100.64.11.35",
17    "metadata": "",
18    "log": {
19      "start_time": 1660054888,
20      "time_spent": 4,
21      "attempts": 1,
22      "errors": 0,
23      "success": true,
24      "mobile": false,
25      "input": [],
26      "history": [
27        {
28          "type": "action",
29          "message": "Attempted to pay with card",
30          "time": 3
31        },
32        {
33          "type": "success",
34          "message": "Successfully paid with card",
35          "time": 4
36        }
37      ]
38    },
39    "fees": 100,
40    "fees_split": null,
41    "authorization": {
42      "authorization_code": "AUTH_ahisucjkru",
43      "bin": "408408",
44      "last4": "4081",
45      "exp_month": "12",
46      "exp_year": "2030",
47      "channel": "card",
48      "card_type": "visa ",
49      "bank": "TEST BANK",
50      "country_code": "NG",
51      "brand": "visa",
52      "reusable": true,
53      "signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
54      "account_name": null
55    },
56    "customer": {
57      "id": 89929267,
58      "first_name": null,
59      "last_name": null,
60      "email": "hello@email.com",
61      "customer_code": "CUS_i5yosncbl8h2kvc",
62      "phone": null,
63      "metadata": null,
64      "risk_action": "default",
65      "international_format_phone": null
66    },
67    "plan": null,
68    "split": {},
69    "order_id": null,
70    "paidAt": "2022-08-09T14:21:32.000Z",
71    "createdAt": "2022-08-09T14:20:57.000Z",
72    "requested_amount": 20000,
73    "pos_transaction_data": null,
74    "source": null,
75    "fees_breakdown": null,
76    "transaction_date": "2022-08-09T14:20:57.000Z",
77    "plan_object": {},
78    "subaccount": {}
79  }
80}

List Transaction

List transactions carried out on your integration

Transaction ID data type

If you plan to store or make use of the the transaction ID, you should represent it as a unsigned 64-bit integer. To learn more, check out our changelog.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
customer
Integer
Specify an ID for the customer whose transactions you want to retrieve
terminalid
String
The Terminal ID for the transactions you want to retrieve
status
String
Filter transactions by status ('failed', 'success', 'abandoned')
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
amount
Integer
Filter transactions by amount using the supported currency code
Show optional parameters
GET/transaction
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Transactions retrieved",
4  "data": [
5    {
6      "id": 5833,
7      "domain": "test",
8      "status": "failed",
9      "reference": "icy9ma6jd1",
10      "amount": 100,
11      "message": null,
12      "gateway_response": "Declined",
13      "paid_at": null,
14      "created_at": "2016-09-29T00:00:05.000Z",
15      "channel": "card",
16      "currency": "NGN",
17      "ip_address": null,
18      "metadata": null,
19      "timeline": null,
20      "customer": {
21        "first_name": "Test",
22        "last_name": "Dummy",
23        "email": "test@dummy.com",
24        "phone": "16504173147",
25        "metadata": null,
26        "customer_code": "CUS_1uld4hluw0g2gn0"
27      },
28      "authorization": {},
29      "plan": {},
30      "requested_amount": 100
31    },
32    {
33      "id": 298126,
34      "domain": "live",
35      "status": "failed",
36      "reference": "z1gsnks86e6kfo8",
37      "amount": 10000,
38      "message": null,
39      "gateway_response": "Declined",
40      "paid_at": null,
41      "created_at": "2016-09-29T00:03:22.000Z",
42      "channel": "card",
43      "currency": "NGN",
44      "ip_address": null,
45      "metadata": {
46        "custom_fields": [
47          {
48            "display_name": "Mobile Number",
49            "variable_name": "mobile_number",
50            "value": "+2348012345678"
51          }
52        ]
53      },
54      "log": null,
55      "fees": null,
56      "paidAt": "2016-09-29T00:03:25.000Z",
57      "createdAt": "2016-09-29T00:03:22.000Z",
58      "authorization": {
59        "authorization_code": "AUTH_86gs11dr",
60        "bin": "539983",
61        "last4": "0061",
62        "exp_month": "08",
63        "exp_year": "2018",
64        "card_type": "mastercard DEBIT",
65        "bank": "Guaranty Trust Bank",
66        "country_code": "NG",
67        "brand": "mastercard",
68        "account_name": "BoJack Horseman"
69      },
70      "customer": {
71        "id": 8279,
72        "first_name": "Test",
73        "last_name": "Dummy",
74        "email": "test@dummy.com",
75        "phone": "16504173147",
76        "customer_code": "CUS_1uld4hluw0g2gn0",
77        "metadata": null,
78        "risk_action": "default"
79      },
80      "requested_amount": 10000
81    }
82  ],
83  "meta": {
84    "total": 1,
85    "skipped": 0,
86    "perPage": 50,
87    "page": 1,
88    "pageCount": 1
89  }
90}

Fetch Transaction

Get details of a transaction carried out on your integration

Transaction ID data type

If you plan to store or make use of the the transaction ID, you should represent it as a unsigned 64-bit integer. To learn more, check out our changelog.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
id
Integer
An ID for the transaction to fetch
GET/transaction/:id
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/{id}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Transaction retrieved",
4  "data": {
5    "id": 292584114,
6    "domain": "test",
7    "status": "success",
8    "reference": "203520101",
9    "amount": 10000,
10    "message": null,
11    "gateway_response": "Successful",
12    "paid_at": "2019-10-09T13:03:28.000Z",
13    "created_at": "2019-10-09T13:00:16.000Z",
14    "channel": "card",
15    "currency": "NGN",
16    "ip_address": "197.211.43.98",
17    "metadata": {
18      "custom_fields": [
19        {
20          "display_name": "Mobile Number",
21          "variable_name": "mobile_number",
22          "value": "+2348012345678"
23        }
24      ],
25      "referrer": "http://localhost:3001/integration/microphone.html?"
26    },
27    "log": {
28      "start_time": 1570626018,
29      "time_spent": 192,
30      "attempts": 1,
31      "errors": 0,
32      "success": true,
33      "mobile": false,
34      "input": [],
35      "history": [
36        {
37          "type": "action",
38          "message": "Attempted to pay with card",
39          "time": 191
40        },
41        {
42          "type": "success",
43          "message": "Successfully paid with card",
44          "time": 192
45        }
46      ]
47    },
48    "fees": 150,
49    "fees_split": null,
50    "authorization": {
51      "authorization_code": "AUTH_2e4k18sj52",
52      "bin": "408408",
53      "last4": "4081",
54      "exp_month": "12",
55      "exp_year": "2020",
56      "channel": "card",
57      "card_type": "visa DEBIT",
58      "bank": "Test Bank",
59      "country_code": "NG",
60      "brand": "visa",
61      "reusable": true,
62      "signature": "SIG_JrPFkMYhcu8AD75eQWKl",
63      "account_name": "BoJack Horseman"
64    },
65    "customer": {
66      "id": 1809887,
67      "first_name": null,
68      "last_name": null,
69      "email": "customer@email.com",
70      "customer_code": "CUS_0c35ys9w8ma5tbr",
71      "phone": null,
72      "metadata": null,
73      "risk_action": "deny"
74    },
75    "plan": {},
76    "subaccount": {},
77    "order_id": null,
78    "paidAt": "2019-10-09T13:03:28.000Z",
79    "createdAt": "2019-10-09T13:00:16.000Z",
80    "requested_amount": 1500000
81  }
82}

Charge Authorization

All authorizations marked as reusable can be charged with this endpoint whenever you need to receive payments

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
amount
String
Amount should be in the subunit of the supported currency
email
String
Customer's email address
authorization_code
String
Valid authorization code to charge
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
currency
String
Currency in which amount should be charged.
metadata
String
Stringified JSON object. Add a custom_fields attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
channels
Array
Send us 'card' or 'bank' or 'card','bank' as an array to specify what options to show the user paying
subaccount
String
The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_charge
Integer
A flat fee to charge the subaccount for this transaction in the subunit of the supported currency. This overrides the split percentage set when the subaccount was created. Ideally, you will need to use this if you are splitting in flat rates (since subaccount creation only allows for percentage split).
bearer
String
Who bears Paystack charges? account or subaccount (defaults to account).
queue
Boolean
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. Send queue:true to take advantage of our queued charging.
Show optional parameters
POST/transaction/charge_authorization
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/charge_authorization"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "email": "customer@email.com", 
7  "amount": "20000", 
8  "authorization_code": "AUTH_72btv547"
9}'
10

11curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "amount": 27000,
6    "currency": "NGN",
7    "transaction_date": "2020-05-27T11:45:03.000Z",
8    "status": "success",
9    "reference": "cn65lf4ixmkzvda",
10    "domain": "test",
11    "metadata": "",
12    "gateway_response": "Approved",
13    "message": null,
14    "channel": "card",
15    "ip_address": null,
16    "log": null,
17    "fees": 14500,
18    "authorization": {
19      "authorization_code": "AUTH_pmx3mgawyd",
20      "bin": "408408",
21      "last4": "4081",
22      "exp_month": "12",
23      "exp_year": "2020",
24      "channel": "card",
25      "card_type": "visa DEBIT",
26      "bank": "Test Bank",
27      "country_code": "NG",
28      "brand": "visa",
29      "reusable": true,
30      "signature": "SIG_2Gvc6pNuzJmj4TCchXfp",
31      "account_name": null
32    },
33    "customer": {
34      "id": 23215815,
35      "first_name": null,
36      "last_name": null,
37      "email": "mail@mail.com",
38      "customer_code": "CUS_wt0zmhzb0xqd4nr",
39      "phone": null,
40      "metadata": null,
41      "risk_action": "default"
42    },
43    "plan": null,
44    "id": 696105928
45  }
46}

View Transaction Timeline

View the timeline of a transaction

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
id_or_reference
String
The ID or the reference of the transaction
GET/transaction/timeline/:id_or_reference
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/timeline/{id_or_reference}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Timeline retrieved",
4  "data": {
5    "time_spent": 9061,
6    "attempts": 1,
7    "authentication": null,
8    "errors": 1,
9    "success": false,
10    "mobile": false,
11    "input": [],
12    "channel": "card",
13    "history": [
14      {
15        "type": "open",
16        "message": "Opened payment page",
17        "time": 1
18      },
19      {
20        "type": "input",
21        "message": "Filled these fields: card number, card expiry, card cvc",
22        "time": 39
23      },
24      {
25        "type": "action",
26        "message": "Attempted to pay",
27        "time": 39
28      },
29      {
30        "type": "error",
31        "message": "Error: Declined",
32        "time": 48
33      },
34      {
35        "type": "input",
36        "message": "Filled these fields: card expiry, card cvc",
37        "time": 9061
38      },
39      {
40        "type": "close",
41        "message": "Page closed",
42        "time": 9061
43      }
44    ]
45  }
46}

Transaction Totals

Total amount received on your account

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/transaction/totals
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/totals"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Transaction totals",
4  "data": {
5    "total_transactions": 10,
6    "unique_customers": 3,
7    "total_volume": 14000,
8    "total_volume_by_currency": [
9      {
10        "currency": "NGN",
11        "amount": 14000
12      }
13    ],
14    "pending_transfers": 24000,
15    "pending_transfers_by_currency": [
16      {
17        "currency": "NGN",
18        "amount": 24000
19      }
20    ]
21  }
22}

Export Transaction

Export a list of transactions carried out on your integration

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
customer
Integer
Specify an ID for the customer whose transactions you want to retrieve
status
String
Filter transactions by status ('failed', 'success', 'abandoned')
currency
String
Specify the transaction currency to export
amount
Integer
Filter transactions by amount, using the supported currency
settled
Boolean
Set to true to export only settled transactions. false for pending transactions. Leave undefined to export all transactions
settlement
Integer
An ID for the settlement whose transactions we should export
payment_page
Integer
Specify a payment page's id to export only transactions conducted on said page
Show optional parameters
GET/transaction/export
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/export"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4

5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Export successful",
4  "data": {
5    "path": "https://files.paystack.co/exports/100032/1460290758207.csv"
6  }
7}

Partial Debit

Retrieve part of a payment from a customer

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
authorization_code
String
Authorization Code
currency
String
Specify the currency you want to debit. Allowed values are NGN or GHS.
amount
String
Amount should be in the subunit of the supported currency
email
String
Customer's email address (attached to the authorization code)
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
at_least
String
Minimum amount to charge
Show optional parameters
POST/transaction/partial_debit
cURL
1#!/bin/sh
2url="https://api.paystack.co/transaction/partial_debit"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "authorization_code": "AUTH_72btv547", 
7  "currency": "NGN", 
8  "amount": "20000",
9  "email": "customer@email.com"
10}'
11

12curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "amount": 409013,
6    "currency": "NGN",
7    "transaction_date": "2022-08-23T12:44:47.000Z",
8    "status": "success",
9    "reference": "iae89f2pj791ayd",
10    "domain": "test",
11    "metadata": "",
12    "gateway_response": "Approved",
13    "message": null,
14    "channel": "card",
15    "ip_address": null,
16    "log": null,
17    "fees": 2046,
18    "authorization": {
19      "authorization_code": "AUTH_dyzaebwx58",
20      "bin": "408408",
21      "last4": "4081",
22      "exp_month": "12",
23      "exp_year": "2030",
24      "channel": "card",
25      "card_type": "visa ",
26      "bank": "TEST BANK",
27      "country_code": "NG",
28      "brand": "visa",
29      "reusable": true,
30      "signature": "SIG_yEXu7dLBeqG0kU7g95Ke",
31      "account_name": null
32    },
33    "customer": {
34      "id": 37651078,
35      "first_name": null,
36      "last_name": null,
37      "email": "member@test.com",
38      "customer_code": "CUS_q8vst7djnx3vq6d",
39      "phone": null,
40      "metadata": null,
41      "risk_action": "default",
42      "international_format_phone": null
43    },
44    "plan": 0,
45    "requested_amount": 500000,
46    "id": 2044566393
47  }
48}