Payments
Charge your first card in 10 minutes
In a nutshell
Create a customer, charge a test card with the Charge API, handle prompts, and verify the result.
This tutorial walks through a first card charge with the Charge API. You will create a customer record, submit a card charge, respond to any PIN or OTP prompts, and confirm the final result.
Note: Direct card charging is intended for PCI DSS compliant businesses.
Copy linkStep 1: Create a customer
Create the customer first so you have a clear customer record tied to the email you will charge.
curl https://api.paystack.co/customer \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"first_name": "Zero",
"last_name": "Sum",
"phone": "+2348123456789"
}' \
-X POST
Save the returned customer_code and keep using the same email for the charge flow.
Copy linkStep 2: Pick a test card
Use one of Paystack’s test cards from the test environment:
| Scenario | Card number | CVV | PIN | OTP |
|---|---|---|---|---|
| No validation | 4084 0840 8408 4081 | 408 | — | — |
| PIN + OTP validation | 5060 6666 6666 6666 666 | 123 | 1234 | 123456 |
Any future expiry date works in test mode.
Copy linkStep 3: Initialize the card charge
Submit the charge to https://api.paystack.co/charge with the card object. This follows the card charge structure in Paystack’s card charging guide.
{
"email": "[email protected]",
"amount": "10000",
"card": {
"cvv": "123",
"number": "5060666666666666666",
"expiry_month": "01",
"expiry_year": "99"
}
}
A successful API call can return a next action instead of a final success immediately:
{
"status": true,
"message": "Charge attempted",
"data": {
"reference": "apg8mnjf5yg7zp8",
"status": "send_pin"
}
}
Copy linkStep 4: Handle PIN or OTP prompts
When the response is send_pin, collect the card PIN and submit it with the reference.
curl https://api.paystack.co/charge/submit_pin \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"pin": "1234",
"reference": "apg8mnjf5yg7zp8"
}' \
-X POST
A later response may ask for OTP:
{
"status": true,
"message": "Charge attempted",
"data": {
"reference": "vpw8wvwz4lghrgb",
"status": "send_otp",
"display_text": "Please enter OTP sent to..."
}
}
Submit the OTP with the same reference:
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
Depending on the card and bank, you may also see send_phone, send_birthday, send_address, open_url, or pending.
Copy linkStep 5: Verify the final outcome
After the authentication steps complete, verify the transaction from your server.
curl https://api.paystack.co/transaction/verify/:reference \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET
Only treat the payment as successful when data.status is success.
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.
Copy linkStep 6: Store reusable authorization details if needed
When the transaction succeeds, the verify response can include data.authorization. Store the full authorization object and the email used for the transaction if you plan to run recurring charges later.
Copy linkWhat you built
You built a first Charge API flow that:
- created a Paystack customer
- charged a test card directly
- handled PIN and OTP steps
- verified the transaction result
- prepared the authorization for future recurring use
Next, move to the task-focused guide for charging a card, or compare this approach with hosted Checkout.