Recurring Charges

In A Nutshell
In a nutshell
Once a customer has made the first successful payment with their card, you can store the customer's card authorization and use it for subsequent transactions. This currently only works for card!

Charge the first transaction

You can initialize this first charge from web or your mobile app. Check out the different integration methods for web and mobile.

Why do I need to charge the user to add their cards?

  1. Local regulations require that users authenticate the card through 2FA in an initial transaction before we can charge the card subsequently.
  2. It allows us to ensure that the card is valid and can be charged for subsequent transactions.
Minimum charge amount

The minimum amount we recommend for the first charge is NGN 50.00, GHS 0.10, ZAR 1.00, or USD 0.20. Lower amounts are not guaranteed to work on all card brands or banks.

It is standard practice to credit the user back with value (in your app) worth the tokenization amount, or simply refund the money back.

Get the Card authorization

If the first transaction is successful, you can listen to events on your webhook endpoint. Alternatively, you can use the Verify TransactionAPI endpoint to confirm the status of the transaction. In either case, the response looks like the sample below:

2 ...
3 "data": {
4 ...
5 "authorization": {
6 "authorization_code":"AUTH_8dfhjjdt",
7 "card_type":"visa",
8 "last4":"1381",
9 "exp_month":"08",
10 "exp_year":"2018",
11 "bin":"412345",
12 "bank":"TEST BANK",
13 "channel":"card",
14 "signature": "SIG_idyuhgd87dUYSHO92D",
15 "reusable":true,
16 "country_code":"NG",
17 "account_name": "BoJack Horseman"
18 },
19 ...
20 }

You'll notice that the data object in the response contains an authorization object within it, which contains the details of the payment instrument (card in this case) that the user paid with.

authorization_codeThis is the code that is used to charge the card subsequently
card_typeThis tells you the card brand - Visa, Mastercard, etc
last4The last 4 digits of the card. This is one of the details you can use to help the user identify the card
exp_month The expiry month of the card in digits. Eg. "01" means January
exp_yearThe expiry year of the card
binThe first 6 digits of the card. This and the last 4 digits constitute the masked pan
bankThe customer's bank, the bank that issued the card
channelWhat payment channel this is. In this case, it is a card payment
signatureA unique identifier for the card being used. While new authorization codes are created each time a card is used, the card's signature will remain the same.
reusableA boolean flag that tells you if an authorization can be used for a recurring charge. You should only attempt to use the authorization_code if this flag returns as true.
country_codeA two-letter country code (ISO 3166-1 alpha-2) representing the country of the bank where the card was issued

Store the authorization

Next, you need to store the authorization and the email used for the transaction. These details can be used to charge the card subsequently. Every payment instrument that is used on your site/app has a unique signature . The signature can be used to ensure that you do not save an authorization multiple times.


It is important to store the entire authorization object in order not to lose any context regarding the card.

It is also important to store the email used to create an authorization because only the email used to create an authorization can be used to charge it. If you rely on the user's email stored on your system and the user changes it, the authorization can no longer be charged.

When you have the whole authorization object saved, you can display customer payment details at the point of payment to charge recurrently. For example, when the user wants to pay again, you can display the card for the user as Access Bank Visa card ending with 1234.

Charge the authorization

When the user selects the card for a new transaction or when you want to charge them subsequently, you send the authorization_code, user's email and the amount you want to charge to the charge authorizationAPI endpoint.

Show Response
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "authorization_code" : "AUTH_pmx3mgawyd", email: "", amount: "300000" }'
2 "status": true,
3 "message": "Charge attempted",
4 "data": {
5 "amount": 300000,
6 "currency": "NGN",
7 "transaction_date": "2020-05-27T11:45:03.000Z",
8 "status": "success",
9 "reference": "cn65lf4ixmkzvda",
10 "domain": "test",
11 "metadata": "",
12 "gateway_response": "Approved",
13 "message": null,
14 "channel": "card",
15 "ip_address": null,
16 "log": null,
17 "fees": 14500,
18 "authorization": {
19 "authorization_code": "AUTH_pmx3mgawyd",
20 "bin": "408408",
21 "last4": "4081",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa DEBIT",
26 "bank": "Test Bank",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_2Gvc6pNuzJmj4TCchXfp",
31 "account_name": null
32 },
33 "customer": {
34 "id": 23215815,
35 "first_name": null,
36 "last_name": null,
37 "email": "",
38 "customer_code": "CUS_wt0zmhzb0xqd4nr",
39 "phone": null,
40 "metadata": null,
41 "risk_action": "default"
42 },
43 "plan": null,
44 "id": 696105928
45 }
Charging at intervals
If your application needs to charge the authorizations at certain intervals, it means your server needs to have a cron job that runs at particular intervals and picks all the authorizations that needs to be charged.