Charge
A collection of endpoints for configuring and managing the payment channels when initiating a payment
Copy link Create Charge
Initiate a payment by integrating the payment channel of your choice.
Response
200
32 object properties
1 object property
8 object properties
15 object properties
9 object properties
POST
/chargecurl https://api.paystack.co/charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.create();
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.create()
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"amount": 200,
"currency": "NGN",
"transaction_date": "2017-05-24T05:56:12.000Z",
"status": "success",
"reference": "zuvbpizfcf2fs7y",
"domain": "test",
"metadata": {
"custom_fields": [
{
"display_name": "Merchant name",
"variable_name": "merchant_name",
"value": "Van Damme"
},
{
"display_name": "Paid Via",
"variable_name": "paid_via",
"value": "API call"
}
]
},
"gateway_response": "Successful",
"message": null,
"channel": "card",
"ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
"log": null,
"fees": 3,
"authorization": {
"authorization_code": "AUTH_6tmt288t0o",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2020",
"channel": "card",
"card_type": "visa visa",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_uSYN4fv1adlAuoij8QXh",
"account_name": "BoJack Horseman"
},
"customer": {
"id": 14571,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_hns72vhhtos0f0k",
"phone": null,
"metadata": null,
"risk_action": "default"
},
"plan": null
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Submit PIN
Submit PIN to continue a charge
Request Body
Customer's PIN for the ongoing transaction
Transaction reference that requires the PIN
Response
200
14 object properties
12 object properties
6 object properties
POST
/charge/submit_pincurl https://api.paystack.co/charge/submit_pin \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"pin": "1234",
"reference": "5bwib5v6anhe9xa"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.submitPin({
pin: "1234",
reference: "5bwib5v6anhe9xa"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.submit_pin({
pin: "1234",
reference: "5bwib5v6anhe9xa"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"id": 2046671778,
"domain": "test",
"status": "success",
"reference": "36xz3b9rie9ppvz",
"amount": 10000,
"message": "madePayment",
"gateway_response": "Approved",
"paid_at": "2022-08-24T12:00:18.000Z",
"created_at": "2022-08-24T11:58:41.000Z",
"channel": "bank",
"currency": "NGN",
"ip_address": "172.31.68.204",
"metadata": "",
"log": null,
"fees": 50,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_nrp5ly1goc",
"bin": "000XXX",
"last4": "X000",
"exp_month": "12",
"exp_year": "9999",
"channel": "bank",
"card_type": "",
"bank": "Zenith Bank",
"country_code": "NG",
"brand": "Zenith Emandate",
"reusable": false,
"signature": null,
"account_name": null
},
"customer": {
"id": 44494174,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_cm4hqzmhg0u0ded",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"split": {},
"order_id": null,
"paidAt": "2022-08-24T12:00:18.000Z",
"createdAt": "2022-08-24T11:58:41.000Z",
"requested_amount": 10000,
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null,
"transaction_date": "2022-08-24T11:58:41.000Z",
"plan_object": {},
"subaccount": {}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Submit OTP
Submit OTP to complete a charge
Request Body
Customer's OTP for ongoing transaction
The reference of the ongoing transaction
Response
200
14 object properties
12 object properties
6 object properties
POST
/charge/submit_otpcurl https://api.paystack.co/charge/submit_otp \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"otp": "123456",
"reference": "5bwib5v6anhe9xa"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.submitOtp({
otp: "123456",
reference: "5bwib5v6anhe9xa"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.submit_otp({
otp: "123456",
reference: "5bwib5v6anhe9xa"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"id": 2046671778,
"domain": "test",
"status": "success",
"reference": "36xz3b9rie9ppvz",
"amount": 10000,
"message": "madePayment",
"gateway_response": "Approved",
"paid_at": "2022-08-24T12:00:18.000Z",
"created_at": "2022-08-24T11:58:41.000Z",
"channel": "bank",
"currency": "NGN",
"ip_address": "172.31.68.204",
"metadata": "",
"log": null,
"fees": 50,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_nrp5ly1goc",
"bin": "000XXX",
"last4": "X000",
"exp_month": "12",
"exp_year": "9999",
"channel": "bank",
"card_type": "",
"bank": "Zenith Bank",
"country_code": "NG",
"brand": "Zenith Emandate",
"reusable": false,
"signature": null,
"account_name": null
},
"customer": {
"id": 44494174,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_cm4hqzmhg0u0ded",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"split": {},
"order_id": null,
"paidAt": "2022-08-24T12:00:18.000Z",
"createdAt": "2022-08-24T11:58:41.000Z",
"requested_amount": 10000,
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null,
"transaction_date": "2022-08-24T11:58:41.000Z",
"plan_object": {},
"subaccount": {}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Submit Phone
Submit phone number when requested
Request Body
Customer's mobile number
The reference of the ongoing transaction
Response
200
15 object properties
12 object properties
6 object properties
POST
/charge/submit_phonecurl https://api.paystack.co/charge/submit_phone \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+2348123456789",
"reference": "5bwib5v6anhe9xa"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.submitPhone({
phone: "+2348123456789",
reference: "5bwib5v6anhe9xa"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.submit_phone({
phone: "+2348123456789",
reference: "5bwib5v6anhe9xa"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"id": 2046671778,
"domain": "test",
"status": "success",
"reference": "36xz3b9rie9ppvz",
"amount": 10000,
"message": "madePayment",
"gateway_response": "Approved",
"paid_at": "2022-08-24T12:00:18.000Z",
"created_at": "2022-08-24T11:58:41.000Z",
"channel": "bank",
"currency": "NGN",
"ip_address": "172.31.68.204",
"metadata": "",
"log": null,
"fees": 50,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_nrp5ly1goc",
"bin": "000XXX",
"last4": "X000",
"exp_month": "12",
"exp_year": "9999",
"channel": "bank",
"card_type": "",
"bank": "Zenith Bank",
"country_code": "NG",
"brand": "Zenith Emandate",
"reusable": false,
"signature": null,
"account_name": null
},
"customer": {
"id": 44494174,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_cm4hqzmhg0u0ded",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"split": {},
"order_id": null,
"paidAt": "2022-08-24T12:00:18.000Z",
"createdAt": "2022-08-24T11:58:41.000Z",
"requested_amount": 10000,
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null,
"transaction_date": "2022-08-24T11:58:41.000Z",
"plan_object": {},
"subaccount": {}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Submit Birthday
Submit the customer's birthday when requested
Request Body
Customer's birthday in the format YYYY-MM-DD e.g 2016-09-21
The reference of the ongoing transaction
Response
200
2 object properties
POST
/charge/submit_birthdaycurl https://api.paystack.co/charge/submit_birthday \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"birthday": "1961-09-21",
"reference": "5bwib5v6anhe9xa"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.submitBirthday({
birthday: "1961-09-21",
reference: "5bwib5v6anhe9xa"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.submit_birthday({
birthday: "1961-09-21",
reference: "5bwib5v6anhe9xa"
})
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"id": 2046671778,
"domain": "test",
"status": "success",
"reference": "36xz3b9rie9ppvz",
"amount": 10000,
"message": "madePayment",
"gateway_response": "Approved",
"paid_at": "2022-08-24T12:00:18.000Z",
"created_at": "2022-08-24T11:58:41.000Z",
"channel": "bank",
"currency": "NGN",
"ip_address": "172.31.68.204",
"metadata": "",
"log": null,
"fees": 50,
"fees_split": null,
"authorization": {
"authorization_code": "AUTH_nrp5ly1goc",
"bin": "000XXX",
"last4": "X000",
"exp_month": "12",
"exp_year": "9999",
"channel": "bank",
"card_type": "",
"bank": "Zenith Bank",
"country_code": "NG",
"brand": "Zenith Emandate",
"reusable": false,
"signature": null,
"account_name": null
},
"customer": {
"id": 44494174,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_cm4hqzmhg0u0ded",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"plan": null,
"split": {},
"order_id": null,
"paidAt": "2022-08-24T12:00:18.000Z",
"createdAt": "2022-08-24T11:58:41.000Z",
"requested_amount": 10000,
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null,
"transaction_date": "2022-08-24T11:58:41.000Z",
"plan_object": {},
"subaccount": {}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Submit Address
Send the details of the customer's address for address verification
Request Body
Customer's address
Customer's city
Customer's state
Customer's zipcode
The reference of the ongoing transaction
Response
200Request successful
POST
/charge/submit_addresscurl https://api.paystack.co/charge/submit_address \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": "140 N 2ND ST",
"city": "Stroudsburg",
"state": "PA",
"zip_code": "18360",
"reference": "5bwib5v6anhe9xa"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.charge.submitAddress({
address: "140 N 2ND ST",
city: "Stroudsburg",
state: "PA",
zip_code: "18360",
reference: "5bwib5v6anhe9xa"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.submit_address({
address: "140 N 2ND ST",
city: "Stroudsburg",
state: "PA",
zip_code: "18360",
reference: "5bwib5v6anhe9xa"
})
puts response.dataResponse
{
"message": "Charge attempted",
"status": true,
"data": {
"message": "",
"paidAt": "2020-05-21T15:16:00.000Z",
"plan": null,
"log": null,
"ip_address": "35.177.113.19",
"createdAt": "2020-05-21T15:14:25.000Z",
"domain": "live",
"fees": 390,
"metadata": "",
"requested_amount": 10000,
"id": 102039,
"currency": "NGN",
"status": "success",
"transaction_date": "2020-05-21T15:14:25.000Z",
"reference": "7c7rpkqpc0tijs8",
"subaccount": {},
"customer": {
"email": "[email protected]",
"last_name": "Ben",
"metadata": null,
"customer_code": "CUS_bpy9ciomcstg55y",
"risk_action": "default",
"first_name": "Jude",
"phone": "",
"id": 16200
},
"order_id": null,
"plan_object": {},
"authorization": {
"signature": "SIG_5wBvKoAT64nwSJgZkHvQ",
"authorization_code": "AUTH_82e26bc6yb",
"reusable": true,
"exp_month": "08",
"card_type": "visa DEBIT",
"last4": "4633",
"account_name": "BoJack Horseman",
"channel": "card",
"brand": "visa",
"country_code": "US",
"bin": "440066",
"bank": "",
"exp_year": "2024"
},
"channel": "card",
"amount": 10000,
"created_at": "2020-05-21T15:14:25.000Z",
"gateway_response": "Approved",
"fees_split": null,
"paid_at": "2020-05-21T15:16:00.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link 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.
Path Parameters
The reference of the ongoing transaction
Response
200
14 object properties
12 object properties
6 object properties
GET
/charge/{reference}curl https://api.paystack.co/charge/5bwib5v6anhe9xa \
-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.charge.check("5bwib5v6anhe9xa");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.charge.check("5bwib5v6anhe9xa")
puts response.dataResponse
{
"status": true,
"message": "Charge attempted",
"data": {
"amount": 200,
"currency": "NGN",
"transaction_date": "2017-05-24T05:56:12.000Z",
"status": "success",
"reference": "zuvbpizfcf2fs7y",
"domain": "test",
"metadata": {
"custom_fields": [
{
"display_name": "Merchant name",
"variable_name": "merchant_name",
"value": "Van Damme"
},
{
"display_name": "Paid Via",
"variable_name": "paid_via",
"value": "API call"
}
]
},
"gateway_response": "Successful",
"message": null,
"channel": "card",
"ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
"log": null,
"fees": 3,
"authorization": {
"authorization_code": "AUTH_6tmt288t0o",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2020",
"channel": "card",
"card_type": "visa visa",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_uSYN4fv1adlAuoij8QXh",
"account_name": "BoJack Horseman"
},
"customer": {
"id": 14571,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_hns72vhhtos0f0k",
"phone": null,
"metadata": null,
"risk_action": "default"
},
"plan": 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
}