Payments
How to charge a card
In a nutshell
Submit a card charge, handle Charge API response states, and verify the final result.
For when to choose this flow, see Charge API.
Copy linkSubmit the initial charge
Send the customer email, amount, and card details to https://api.paystack.co/charge.
{
"email": "[email protected]",
"amount": "10000",
"card": {
"cvv": "408",
"number": "4084084084084081",
"expiry_month": "01",
"expiry_year": "99"
},
"pin": "0000"
}
curl https://api.paystack.co/charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d @charge.json \
-X POST
Track the data.reference from every response. You need it for follow-up actions and final verification.
Copy linkHandle the next action
Use data.status as the next action for the charge.
data.status | What to do |
|---|---|
send_pin | Collect the card PIN and submit it with the reference. |
send_otp | Collect the OTP sent by the bank and submit it with the reference. |
send_phone | Collect the phone number tied to the bank account and submit it with the reference. |
send_birthday | Collect the customerβs birthday and submit it with the reference. |
send_address | Collect street address, city, state, and ZIP code, then submit them with the reference. |
open_url | Redirect the customer to data.url to complete bank-controlled authentication. |
pending | Wait at least 10 seconds, then check the pending charge or verify the transaction. |
pay_offline | Show the offline instruction, such as a USSD code, and wait for completion. |
success | Move to verification. |
failed or timeout | Stop the flow and start a new charge if the customer wants to retry. |
Copy linkSubmit follow-up responses
Submit a PIN:
curl https://api.paystack.co/charge/submit_pin \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"pin":"0000","reference":"apg8mnjf5yg7zp8"}' \
-X POST
Submit an OTP:
curl https://api.paystack.co/charge/submit_otp \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"otp":"123456","reference":"vpw8wvwz4lghrgb"}' \
-X POST
Submit a phone number:
curl https://api.paystack.co/charge/submit_phone \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"08000000000","reference":"apg8mnjf5yg7zp8"}' \
-X POST
Submit a birthday:
curl https://api.paystack.co/charge/submit_birthday \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"birthday":"1990-01-31","reference":"apg8mnjf5yg7zp8"}' \
-X POST
For open_url, redirect the customer to the returned URL. If you want Paystack to force this hosted authentication path, add "use_hosted_url": true to the original charge payload.
Copy linkVerify the outcome
After the flow completes, verify the transaction with the charge reference:
curl https://api.paystack.co/transaction/verify/:reference \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET
Deliver value only when data.status is success. Also confirm the amount matches what you intended to charge.
Copy linkHandle webhook confirmation
Use the charge.success webhook as your primary signal to fulfill orders, grant access, or update your database. The customer can close the page before your callback runs, but the webhook still arrives.
Add your webhook URL on the Paystack Dashboard, and verify the signature on every event with your webhook signing secret.
Keep server-side verification for redirects, retries, and reconciliation.