Card charge

Card charges let you collect card details server-side and process the payment through the API. Because card authentication varies by issuer and market, a single charge can require one or more follow-up steps before it settles.

Handling raw card numbers puts your systems in PCI DSS scope. Confirm your compliance obligations before you collect card details server-side, and never log or persist a full PAN or CVV.

Happy path

Initiate the charge

Send card details, amount, currency, and customer information.

Handle any required step

The transaction may ask for a PIN, OTP, address, or a 3DS redirect.

Wait for the final webhook

A successful or failed transaction_updated event is the real outcome.

Fulfil

Only once the status is successful.

1. Initiate the charge

Send a request to Card Charge.

Field	Type	Required	Description
`amount`	Number	Yes	Amount to charge, e.g. `1500`
`currency`	String	Yes	3-letter currency code, e.g. `KES`, `NGN`, `USD`
`email`	String	Yes	Customer email
`firstName`	String	Yes	Card holder first name
`lastName`	String	Yes	Card holder last name
`externalReference`	String	Yes	Your own unique ID for tracking
`cardDetails.number`	String	Yes	Card PAN
`cardDetails.cvv`	String	Yes	Card CVV
`cardDetails.expMonth`	String	Yes	Expiry month, `MM`
`cardDetails.expYear`	String	Yes	Expiry year, `YY`
`address`	Object	—	Billing address. Required for address verification
`device3DSInfo`	Object	—	Device data used for 3DS risk assessment
`ipAddress`	String	—	Customer IP address
`redirectUrl`	String	—	Return URL after a redirect, provider dependent

{
  "amount": 100,
  "ipAddress": "102.218.103.10",
  "currency": "NGN",
  "email": "w.west@starlabs.com",
  "firstName": "Wally",
  "lastName": "West",
  "externalReference": "525252525",
  "cardDetails": {
    "cvv": "052",
    "number": "4242424242424242",
    "expMonth": "09",
    "expYear": "28"
  },
  "address": {
    "zip": "64101",
    "country": "US",
    "street1": "52 Flash Boulevard",
    "city": "Central City",
    "state": "MO"
  }
}

{
  "amount": 10,
  "ipAddress": "159.26.101.81",
  "currency": "USD",
  "email": "b.wayne@waynetech.com",
  "firstName": "Bruce",
  "lastName": "Wayne",
  "externalReference": "123456789",
  "cardDetails": {
    "cvv": "000",
    "number": "4242424242424242",
    "expMonth": "09",
    "expYear": "28"
  },
  "address": {
    "zip": "10025",
    "country": "US",
    "street1": "1007 Mountain Drive",
    "city": "Gotham City",
    "state": "NJ"
  },
  "device3DSInfo": {
    "colorDepth": 30,
    "screenHeight": 1050,
    "screenWidth": 1680,
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36",
    "timeZone": 180,
    "deviceId": "29b435613857666dhgfdhg3b0a778471fbe9dc72db044886c7cc1175e4af632d4eb"
  }
}

Response

{
  "success": true,
  "status": "PENDING",
  "message": "Request queued"
}

Card charges are processed asynchronously. Track the outcome with the transactionId via Get Transaction, or by listening for webhooks.

Supplying device3DSInfo and ipAddress gives the issuer more signal for risk assessment, which can reduce how often a customer is challenged with 3DS.

2. Identify the required step

Both the transaction status response and the webhook carry a stepRequired field when the charge is waiting on the customer.

`stepRequired`	What it means	What you do
`pin`	Card PIN required	Prompt for the PIN, submit via Authorise Charge
`otp`	Code sent to the customer’s phone or email	Prompt for the code, submit via Authorise Charge
`address_verification`	Billing address must be verified against card records	Collect the address, submit via Authorise Charge
`redirect`	3-D Secure authentication	Send the customer to `redirectUrl`

{
  "success": true,
  "data": {
    "transactionId": "TMNT-JLA-CRISIS-2026",
    "amount": 100,
    "currency": "NGN",
    "createdAt": 1772739561749,
    "chargeStatus": "pending",
    "status": "PENDING",
    "type": "deposit",
    "method": "card",
    "fullTimestamp": "2026-03-05T19:39:21+00:00",
    "externalReference": "EARTH-PRIME-01",
    "stepRequired": "pin",
    "metadata": {
      "senderAccountName": "Diana Prince",
      "cardFirstSix": "194110",
      "cardLastFour": "1984"
    }
  }
}

{
  "success": true,
  "data": {
    "transactionId": "TMNT-JLA-CRISIS-2026",
    "amount": 100,
    "currency": "NGN",
    "chargeStatus": "pending",
    "status": "PENDING",
    "type": "deposit",
    "method": "card",
    "externalReference": "EARTH-PRIME-01",
    "stepRequired": "otp",
    "metadata": {
      "senderAccountName": "Diana Prince",
      "cardFirstSix": "194110",
      "cardLastFour": "1984"
    }
  }
}

{
  "success": true,
  "data": {
    "transactionId": "TMNT-JLA-CRISIS-2026",
    "amount": 100,
    "currency": "NGN",
    "chargeStatus": "pending",
    "status": "PENDING",
    "type": "deposit",
    "method": "card",
    "externalReference": "EARTH-PRIME-01",
    "stepRequired": "address_verification",
    "metadata": {
      "senderAccountName": "Diana Prince",
      "cardFirstSix": "194110",
      "cardLastFour": "1984"
    }
  }
}

{
  "success": true,
  "data": {
    "transactionId": "ARKHAM-ASYLUM-777",
    "amount": 0.5,
    "currency": "USD",
    "chargeStatus": "pending",
    "status": "PENDING",
    "type": "deposit",
    "method": "card",
    "externalReference": "PUDDIN-01",
    "stepRequired": "redirect",
    "metadata": {
      "senderAccountName": "Harleen Quinzel",
      "cardFirstSix": "091192",
      "cardLastFour": "1992"
    },
    "redirectUrl": "https://redirect.com"
  }
}

3. Handle webhooks

The same stepRequired values arrive as transaction_updated events.

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "luQybnMnvjgnWEF6ZFyJ",
    "status": "pending",
    "type": "deposit",
    "stepRequired": "pin",
    "externalReference": "1234567890"
  },
  "timestamp": "2026-03-05T19:39:30.624Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "luQybnMnvjgnWEF6ZFyJ",
    "status": "pending",
    "type": "deposit",
    "stepRequired": "otp",
    "externalReference": "1234567890"
  },
  "timestamp": "2026-03-05T19:39:30.624Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "luQybnMnvjgnWEF6ZFyJ",
    "status": "pending",
    "type": "deposit",
    "stepRequired": "address_verification",
    "externalReference": "1234567890"
  },
  "timestamp": "2026-03-05T19:39:30.624Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "RFJZcgeeTGilZgPp9zyn",
    "status": "pending",
    "type": "deposit",
    "stepRequired": "redirect",
    "externalReference": "12fd3456789x",
    "redirectUrl": "https://redirect.com"
  },
  "timestamp": "2026-03-05T19:42:56.538Z"
}

4. Authorise the charge

For pin, otp, and address_verification, collect the value from the customer and submit it to Authorise Charge.

Field	Type	Required	Description
`type`	String	Yes	`otp`, `pin`, or `address_verification`
`value`	String or Object	Yes	A string for `otp` and `pin`; an address object for `address_verification`

{
  "type": "pin",
  "value": "1234"
}

{
  "type": "otp",
  "value": "123456"
}

{
  "type": "address_verification",
  "value": {
    "street1": "123 Main St",
    "city": "Lagos",
    "state": "Lagos",
    "zip": "100001",
    "country": "NG"
  },
  "transactionsLocation": "transactions"
}

{
  "success": true,
  "message": "Charge Authorisation successful."
}

{
  "success": true,
  "message": "Verification successful. Next step: redirect",
  "stepData": {
    "stepRequired": "redirect",
    "redirectUrl": "https://3ds.bank.com/authorize?token=..."
  }
}

Authorising one step can surface another. Always inspect stepData in the response — a successful PIN submission may still be followed by a 3DS redirect. Loop until no further step is returned, then wait for the final webhook.

5. Handle 3DS redirects

When stepRequired is redirect:

Extract the URL

Take redirectUrl from the webhook, the transaction status, or the stepData of an authorise response.

Send the customer

They land on their bank’s secure authentication page.

Wait for the final webhook

After the customer completes or abandons authentication, the outcome arrives as transaction_updated with successful or failed.

Do not poll aggressively during a redirect flow. The final outcome is delivered by webhook once the bank responds.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Happy path

1. Initiate the charge

2. Identify the required step

3. Handle webhooks

4. Authorise the charge

5. Handle 3DS redirects

​Happy path

​1. Initiate the charge

​2. Identify the required step

​3. Handle webhooks

​4. Authorise the charge

​5. Handle 3DS redirects

Happy path

1. Initiate the charge

2. Identify the required step

3. Handle webhooks

4. Authorise the charge

5. Handle 3DS redirects