API StatusCoverageError DocsSupport Portal

Recurring payments

Suggest Edits

With subscriptions, you can charge your customer on a recurring basis. A subscription might not seem much different from a one-time charge. But to manage subscription payments, you need to retain more information about your customers, so you can charge them automatically in the future and allow them to maintain appropriate access to your product or service.

Initiate via the API

Here's what the code above means;

  1. Initiate payment
  • When you make a POST request to this endpoint, you'd have to specify the account Id you which to debit and the account Id you wish to credit, and of course the amount as parameters.
  1. The default type value is one-time, so you'd have to specify recurring.
  2. The schedule option is where you define the interval you'd like to start and end the payments, the interval could be monthly/weekly/yearly.
  3. Amounts are always set by default to KOBO!
  4. The currency attribute is set by default to NGN, for our Nigeria customers, but is optional.

Note - While the account to credit property is optional the account to debit is required

📝

If you called the right endpoint and entered the correct parameters, you should have a successful JSON response like the one below, else a failed response.

curl -X POST https://api.okra.ng/v2/pay/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "account_to_debit":  ACCOUNT ID,
    "account_to_credit": ACCOUNT ID, //optional
    "type": "recurring",
    "schedule": { // required
                    interval: "monthly",
                    startDate: "YYYY-MM-DD", // If blank will default to today
                    endDate: "YYYY-MM-DD" //If blank will not stop
            }, 
        "amount": 10000, //kobo e.g. 100.00 naira = 10000,
        "currency": "NGN" // only NGN supported for now
}'

{
    "status": "success",
    "message": "Payment succesfully initiated!",
    "data": {
        "payment": {
            "record": "5fc44a4859a9542d6962266e",
            "amount": 10000,
            "bank_response": null,
            "created_at": "2020-11-30T01:26:33.526Z",
            "credit_account": "Okra Wallet",
            "currency": "NGN",
            "customer": "5e98fd2178b73e2656b93609",
            "debit_account": "5e98f3196f65141382e96781",
            "email": null,
            "env": "production",
            "error": null,
            "last_updated": "2020-11-30T01:26:33.526Z",
            "link": null,
            "meta": null,
            "owner": "5d9288ea182d3d000cb7c486",
            "ref": "nMo4RhqE7ymBlYQ",
            "schedule": null,
            "source": "api",
            "status": "initialize",
            "id": "5fc44a499016589c6d2a661b"
        },
        "okra_wallet": {
            "amount": 1000,
            "currency": "NGN",
            "last_updated": "2020-11-26T15:52:25.108Z",
            "id": "5fb9868c4c805c0d64b519b5"
        },
        "callback_url": "https://api.okra.ng/v2/callback?record=5fc44a4859a9542d6962266e&method=PAYMENT",
        "customer": {
            "name": "GAVIN BELSON",
            "id": "5e98fd2178b73e2656b93609",
            "account": {
                "id": "5e98f3196f65141382e96781",
                "name": "EDISON MADUABUCHUKWU OBODO",
                "nuban": "0033823682",
                "bank": {
                    "name": "Stanbic IBTC Bank",
                    "slug": "stanbic-ibtc-bank",
                    "id": "5d6fe57a4099cc4b210bbeb6",
                    "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Stanbic+IBTC+Bank+Logo.svg",
                    "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Stanbic+IBTC+Bank+Logo.png",
                    "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Stanbic+IBTC+Bank+Logo+Color.svg"
                }
            }
        }
    }
}

⚠

If the startDate property is left empty, it assumes the current date, and if the endDate has no value the payment continues, i.e the customer will continuously be charged. Therefore, it's advisable to always have a value for start and end dates.

📘

You can also initiate a recurring payment authorization, the steps are similar to what we have above.

url -X POST https://api.okra.ng/v2/pay/authorization/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
  "authorization": "xxxxxxxxxxxxxxxx",
  "amount": 10000,
  "initialAmount": 7000,
  "currency": "NGN",
  "startDate": "2021/05/21",
  "endDate": "2021/06/27",
  "interval": "monthly",
  "oneTime": false
}'

{
    "status": "success",
    "message": "Payment authorization was successfully updated and will begin 2021-03-10 with an initial payment of NGN 10000 and continue with payments of NGN 10000 on an ongoing basis until cancelled",
    "data": {
        "authorization": {
            "_id": "602ba395062f875c2a7d433b",
            "customer": "5e9bbfb856ec36e888195d03",
            "accounts": [
                "6026776de26cb3db2b5250c2"
            ],
            "disconnect": false,
            "disconnected_at": null,
            "duration": {
                "startDate": "2021-03-10T11:49:37.141Z",
                "endDate": null,
                "oneTime": true,
                "interval": "monthly"
            },
            "initialAmount": 7000,
            "initiated": false,
            "amount": 10000
        }
    }
}

Initiate via the widget

This section will teach you how to seamlessly integrate a recurring payment via the Widget, so you can charge your customer on a recurring basis.

Setting up a recurring payment via our widget is a simple as ABC, simply update your widget by adding payment and charge to your widget options as below:

Click here to view SDK integration docs.

const options = {
... {other widget options} ... 
payment: true,
charge: {
      type: 'recurring', 
      amount: 50000, // amount in KOBO
      note: '', // optional note
          schedule: { // required
                    interval: 'monthly',
                    startDate: 'YYYY-MM-DD', // If blank will default to today
                    endDate: 'YYYY-MM-DD' //If blank will not stop
            }, 
      currency: 'NGN', // supports 'NGN'
      account: 'xxxxxxxxxxxxxxxx' // Your account ID to credit
  }
}

Surprised? 😲
Let me explain what's going on here;

  1. To initiate a recurring payment you'd have to set payment to true
  2. The default type value is one-time, so you'd have to change it to recurring.

Recurring payment means you charge the customer at a certain interval or recurring basis.

  1. Amounts are always set by default to KOBO!
  2. The note attributes are optional, yet necessary if you wish to describe the payment.
  3. The schedule option is where you define the interval you'd like to start and end the payments, the interval could be monthly/weekly/yearly.
  4. The currency attribute is set by default to NGN, for our Nigeria customers, but is optional.
  5. The account attributes connote the account ID you wish to credit.

Initiate via the dashboard

You can also initiate recurring payments via the dashboard in minutes.
Check out this guide

Updated about 1 year ago