Charges

The Charge API allows you to configure payment channel of your choice when initiating a payment.

Create Charge

Initiate a payment by integrating the payment channel of your choice.

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

Customer's email address

Amount in subunit of the supported currency

The split code of a previously created split. e.g. SPL_98WF13Eb3w

The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

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.

Use this param to indicate who bears the transaction charges. Allowed values are: account or subaccount (defaults to account).

Bank account to charge (don't send if charging an authorization code)

Takes the settings for the Pay with Transfer (PwT) channel. Pass in the account_expires_at param to set the expiry time.

USSD type to charge (don't send if charging an authorization code, bank or card)

Mobile money details (don't send if charging an authorization code, bank or card). Currently supported in Ghana and Kenya only.

Takes a provider parameter with the value set to: scan-to-pay. Currently supported in South Africa only.

An authorization code to charge (don't send if charging a bank account)

4-digit PIN (send with a non-reusable authorization code)

Used for passing additional details for your post-payment processes

Unique transaction reference. Only -, .`, = and alphanumeric characters allowed.

This is the unique identifier of the device a user uses in making payment. Only -, .`, = and alphanumeric characters allowed.

1#!/bin/sh
2url="https://api.paystack.co/charge"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "email": "customer@email.com",
7  "amount": "10000",
8  "metadata": {
9    "custom_fields": [
10      {
11        "value": "makurdi",
12        "display_name": "Donation for",
13        "variable_name": "donation_for"
14      }
15    ]
16  },
17  "bank": {
18      "code": "057",
19      "account_number": "0000000000"
20  },
21  "birthday": "1995-12-23"
22}'
23
24curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "amount": 200,
6    "currency": "NGN",
7    "transaction_date": "2017-05-24T05:56:12.000Z",
8    "status": "success",
9    "reference": "zuvbpizfcf2fs7y",
10    "domain": "test",
11    "metadata": {
12      "custom_fields": [
13        {
14          "display_name": "Merchant name",
15          "variable_name": "merchant_name",
16          "value": "Van Damme"
17        },
18        {
19          "display_name": "Paid Via",
20          "variable_name": "paid_via",
21          "value": "API call"
22        }
23      ]
24    },
25    "gateway_response": "Successful",
26    "message": null,
27    "channel": "card",
28    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
29    "log": null,
30    "fees": 3,
31    "authorization": {
32      "authorization_code": "AUTH_6tmt288t0o",
33      "bin": "408408",
34      "last4": "4081",
35      "exp_month": "12",
36      "exp_year": "2020",
37      "channel": "card",
38      "card_type": "visa visa",
39      "bank": "TEST BANK",
40      "country_code": "NG",
41      "brand": "visa",
42      "reusable": true,
43      "signature": "SIG_uSYN4fv1adlAuoij8QXh",
44      "account_name": "BoJack Horseman"
45    },
46    "customer": {
47      "id": 14571,
48      "first_name": null,
49      "last_name": null,
50      "email": "test@email.co",
51      "customer_code": "CUS_hns72vhhtos0f0k",
52      "phone": null,
53      "metadata": null,
54      "risk_action": "default"
55    },
56    "plan": null
57  }
58}

Submit PIN

Submit PIN to continue a charge

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

PIN submitted by user

Reference for transaction that requested pin

1#!/bin/sh
2url="https://api.paystack.co/charge/submit_pin"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "pin": "1234", 
7  "reference": "5bwib5v6anhe9xa"
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "id": 2046671778,
6    "domain": "test",
7    "status": "success",
8    "reference": "36xz3b9rie9ppvz",
9    "amount": 10000,
10    "message": "madePayment",
11    "gateway_response": "Approved",
12    "paid_at": "2022-08-24T12:00:18.000Z",
13    "created_at": "2022-08-24T11:58:41.000Z",
14    "channel": "bank",
15    "currency": "NGN",
16    "ip_address": "172.31.68.204",
17    "metadata": "",
18    "log": null,
19    "fees": 50,
20    "fees_split": null,
21    "authorization": {
22      "authorization_code": "AUTH_nrp5ly1goc",
23      "bin": "000XXX",
24      "last4": "X000",
25      "exp_month": "12",
26      "exp_year": "9999",
27      "channel": "bank",
28      "card_type": "",
29      "bank": "Zenith Bank",
30      "country_code": "NG",
31      "brand": "Zenith Emandate",
32      "reusable": false,
33      "signature": null,
34      "account_name": null
35    },
36    "customer": {
37      "id": 44494174,
38      "first_name": null,
39      "last_name": null,
40      "email": "charge@email.com",
41      "customer_code": "CUS_cm4hqzmhg0u0ded",
42      "phone": null,
43      "metadata": null,
44      "risk_action": "default",
45      "international_format_phone": null
46    },
47    "plan": null,
48    "split": {},
49    "order_id": null,
50    "paidAt": "2022-08-24T12:00:18.000Z",
51    "createdAt": "2022-08-24T11:58:41.000Z",
52    "requested_amount": 10000,
53    "pos_transaction_data": null,
54    "source": null,
55    "fees_breakdown": null,
56    "transaction_date": "2022-08-24T11:58:41.000Z",
57    "plan_object": {},
58    "subaccount": {}
59  }
60}

Submit OTP

Submit OTP to complete a charge

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

OTP submitted by user

Reference for ongoing transaction

1#!/bin/sh
2url="https://api.paystack.co/charge/submit_otp"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "otp": "123456", 
7  "reference": "5bwib5v6anhe9xa"
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "id": 2046671778,
6    "domain": "test",
7    "status": "success",
8    "reference": "36xz3b9rie9ppvz",
9    "amount": 10000,
10    "message": "madePayment",
11    "gateway_response": "Approved",
12    "paid_at": "2022-08-24T12:00:18.000Z",
13    "created_at": "2022-08-24T11:58:41.000Z",
14    "channel": "bank",
15    "currency": "NGN",
16    "ip_address": "172.31.68.204",
17    "metadata": "",
18    "log": null,
19    "fees": 50,
20    "fees_split": null,
21    "authorization": {
22      "authorization_code": "AUTH_nrp5ly1goc",
23      "bin": "000XXX",
24      "last4": "X000",
25      "exp_month": "12",
26      "exp_year": "9999",
27      "channel": "bank",
28      "card_type": "",
29      "bank": "Zenith Bank",
30      "country_code": "NG",
31      "brand": "Zenith Emandate",
32      "reusable": false,
33      "signature": null,
34      "account_name": null
35    },
36    "customer": {
37      "id": 44494174,
38      "first_name": null,
39      "last_name": null,
40      "email": "charge@email.com",
41      "customer_code": "CUS_cm4hqzmhg0u0ded",
42      "phone": null,
43      "metadata": null,
44      "risk_action": "default",
45      "international_format_phone": null
46    },
47    "plan": null,
48    "split": {},
49    "order_id": null,
50    "paidAt": "2022-08-24T12:00:18.000Z",
51    "createdAt": "2022-08-24T11:58:41.000Z",
52    "requested_amount": 10000,
53    "pos_transaction_data": null,
54    "source": null,
55    "fees_breakdown": null,
56    "transaction_date": "2022-08-24T11:58:41.000Z",
57    "plan_object": {},
58    "subaccount": {}
59  }
60}

Submit Phone

Submit phone number when requested

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

Phone submitted by user

Reference for ongoing transaction

1#!/bin/sh
2url="https://api.paystack.co/charge/submit_phone"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "phone": "08012345678", 
7  "reference": "5bwib5v6anhe9xa"
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "id": 2046671778,
6    "domain": "test",
7    "status": "success",
8    "reference": "36xz3b9rie9ppvz",
9    "amount": 10000,
10    "message": "madePayment",
11    "gateway_response": "Approved",
12    "paid_at": "2022-08-24T12:00:18.000Z",
13    "created_at": "2022-08-24T11:58:41.000Z",
14    "channel": "bank",
15    "currency": "NGN",
16    "ip_address": "172.31.68.204",
17    "metadata": "",
18    "log": null,
19    "fees": 50,
20    "fees_split": null,
21    "authorization": {
22      "authorization_code": "AUTH_nrp5ly1goc",
23      "bin": "000XXX",
24      "last4": "X000",
25      "exp_month": "12",
26      "exp_year": "9999",
27      "channel": "bank",
28      "card_type": "",
29      "bank": "Zenith Bank",
30      "country_code": "NG",
31      "brand": "Zenith Emandate",
32      "reusable": false,
33      "signature": null,
34      "account_name": null
35    },
36    "customer": {
37      "id": 44494174,
38      "first_name": null,
39      "last_name": null,
40      "email": "charge@email.com",
41      "customer_code": "CUS_cm4hqzmhg0u0ded",
42      "phone": null,
43      "metadata": null,
44      "risk_action": "default",
45      "international_format_phone": null
46    },
47    "plan": null,
48    "split": {},
49    "order_id": null,
50    "paidAt": "2022-08-24T12:00:18.000Z",
51    "createdAt": "2022-08-24T11:58:41.000Z",
52    "requested_amount": 10000,
53    "pos_transaction_data": null,
54    "source": null,
55    "fees_breakdown": null,
56    "transaction_date": "2022-08-24T11:58:41.000Z",
57    "plan_object": {},
58    "subaccount": {}
59  }
60}

Submit Birthday

Submit Birthday when requested

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

Birthday submitted by user e.g. 2016-09-21

Reference for ongoing transaction

1#!/bin/sh
2url="https://api.paystack.co/charge/submit_birthday"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "birthday": "1961-09-21", 
7  "reference": "5bwib5v6anhe9xa"
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "id": 2046671778,
6    "domain": "test",
7    "status": "success",
8    "reference": "36xz3b9rie9ppvz",
9    "amount": 10000,
10    "message": "madePayment",
11    "gateway_response": "Approved",
12    "paid_at": "2022-08-24T12:00:18.000Z",
13    "created_at": "2022-08-24T11:58:41.000Z",
14    "channel": "bank",
15    "currency": "NGN",
16    "ip_address": "172.31.68.204",
17    "metadata": "",
18    "log": null,
19    "fees": 50,
20    "fees_split": null,
21    "authorization": {
22      "authorization_code": "AUTH_nrp5ly1goc",
23      "bin": "000XXX",
24      "last4": "X000",
25      "exp_month": "12",
26      "exp_year": "9999",
27      "channel": "bank",
28      "card_type": "",
29      "bank": "Zenith Bank",
30      "country_code": "NG",
31      "brand": "Zenith Emandate",
32      "reusable": false,
33      "signature": null,
34      "account_name": null
35    },
36    "customer": {
37      "id": 44494174,
38      "first_name": null,
39      "last_name": null,
40      "email": "charge@email.com",
41      "customer_code": "CUS_cm4hqzmhg0u0ded",
42      "phone": null,
43      "metadata": null,
44      "risk_action": "default",
45      "international_format_phone": null
46    },
47    "plan": null,
48    "split": {},
49    "order_id": null,
50    "paidAt": "2022-08-24T12:00:18.000Z",
51    "createdAt": "2022-08-24T11:58:41.000Z",
52    "requested_amount": 10000,
53    "pos_transaction_data": null,
54    "source": null,
55    "fees_breakdown": null,
56    "transaction_date": "2022-08-24T11:58:41.000Z",
57    "plan_object": {},
58    "subaccount": {}
59  }
60}

Submit Address

Submit address to continue a charge

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

Address submitted by user

Reference for ongoing transaction

City submitted by user

State submitted by user

Zipcode submitted by user

1#!/bin/sh
2url="https://api.paystack.co/charge/submit_address"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "reference": "7c7rpkqpc0tijs8",
7  "address": "140 N 2ND ST",
8  "city": "Stroudsburg",
9  "state": "PA",
10  "zip_code": "18360"
11}'
12
13curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "message": "Charge attempted",
3  "status": true,
4  "data": {
5    "message": "",
6    "paidAt": "2020-05-21T15:16:00.000Z",
7    "plan": null,
8    "log": null,
9    "ip_address": "35.177.113.19",
10    "createdAt": "2020-05-21T15:14:25.000Z",
11    "domain": "live",
12    "fees": 390,
13    "metadata": "",
14    "requested_amount": 10000,
15    "id": 102039,
16    "currency": "NGN",
17    "status": "success",
18    "transaction_date": "2020-05-21T15:14:25.000Z",
19    "reference": "7c7rpkqpc0tijs8",
20    "subaccount": {},
21    "customer": {
22      "email": "ben@jude.com",
23      "last_name": "Ben",
24      "metadata": null,
25      "customer_code": "CUS_bpy9ciomcstg55y",
26      "risk_action": "default",
27      "first_name": "Jude",
28      "phone": "",
29      "id": 16200
30    },
31    "order_id": null,
32    "plan_object": {},
33    "authorization": {
34      "signature": "SIG_5wBvKoAT64nwSJgZkHvQ",
35      "authorization_code": "AUTH_82e26bc6yb",
36      "reusable": true,
37      "exp_month": "08",
38      "card_type": "visa DEBIT",
39      "last4": "4633",
40      "account_name": "BoJack Horseman",
41      "channel": "card",
42      "brand": "visa",
43      "country_code": "US",
44      "bin": "440066",
45      "bank": "",
46      "exp_year": "2024"
47    },
48    "channel": "card",
49    "amount": 10000,
50    "created_at": "2020-05-21T15:14:25.000Z",
51    "gateway_response": "Approved",
52    "fees_split": null,
53    "paid_at": "2020-05-21T15:16:00.000Z"
54  }
55}

Check Pending Charge

When you get pending as a charge status or if there was an exception when calling any of the /charge endpoints, wait 10 seconds or more, then make a check to see if its status has changed. Don't call too early as you may get a lot more pending than you should.

Headers

Set value to Bearer SECRET_KEY

Path Parameters

The reference to check

1#!/bin/sh
2url="https://api.paystack.co/charge/{reference}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Charge attempted",
4  "data": {
5    "amount": 200,
6    "currency": "NGN",
7    "transaction_date": "2017-05-24T05:56:12.000Z",
8    "status": "success",
9    "reference": "zuvbpizfcf2fs7y",
10    "domain": "test",
11    "metadata": {
12      "custom_fields": [
13        {
14          "display_name": "Merchant name",
15          "variable_name": "merchant_name",
16          "value": "Van Damme"
17        },
18        {
19          "display_name": "Paid Via",
20          "variable_name": "paid_via",
21          "value": "API call"
22        }
23      ]
24    },
25    "gateway_response": "Successful",
26    "message": null,
27    "channel": "card",
28    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
29    "log": null,
30    "fees": 3,
31    "authorization": {
32      "authorization_code": "AUTH_6tmt288t0o",
33      "bin": "408408",
34      "last4": "4081",
35      "exp_month": "12",
36      "exp_year": "2020",
37      "channel": "card",
38      "card_type": "visa visa",
39      "bank": "TEST BANK",
40      "country_code": "NG",
41      "brand": "visa",
42      "reusable": true,
43      "signature": "SIG_uSYN4fv1adlAuoij8QXh",
44      "account_name": "BoJack Horseman"
45    },
46    "customer": {
47      "id": 14571,
48      "first_name": null,
49      "last_name": null,
50      "email": "test@email.co",
51      "customer_code": "CUS_hns72vhhtos0f0k",
52      "phone": null,
53      "metadata": null,
54      "risk_action": "default"
55    },
56    "plan": null
57  }
58}