Sign in

Payments

Charge your first card in 10 minutes

View as Markdown

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:

ScenarioCard numberCVVPINOTP
No validation4084 0840 8408 4081408——
PIN + OTP validation5060 6666 6666 6666 6661231234123456

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.

Was this page helpful?