Recurring Payments

Overview

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.

Recurring Payments via Our API

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"
                }
            }
        }
    }
}

How it works?

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.

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.

url -X POST https://api.okra.ng/v2/pay/authorization/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
  "authorization": "602ba395062f875c2a7d433b",
  "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
        }
    }
}

Run in PostmanRun in Postman

Recurring Payment Via 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: '5f450b2689a23801307c8b5b' // 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.

📘

NOTE

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.

Run in PostmanRun in Postman

Initiate Future Payments

Okra gives you the flexibility to set up recurring or one time debit for a future date and also set when the debit should stop. You can have one-time payment by adding OneTime: true or interval payments by setting interval: monthly/weekly/yearly

url -X POST https://api.okra.ng/v2/pay/authorization/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
  "authorization": "602ba395062f875c2a7d433b",
  "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
        }
    }
}

Run in PostmanRun in Postman

Cancel Future Payment

You can cancel a Payment if you no longer intend to use it to collect payment from the customer.

url -X POST https://api.okra.ng/v2/pay/authorization/cancel
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
  "authorization": "602ba395062f875c2a7d433b",
  "customer": "5e9bbfb856ec36e888195d03",
  "link": "602ba2c5cf08f006d11df72a",
  "account": "6026776de26cb3db2b5250c2"
}'
{
    "status": "success",
    "message": "Payment authorization(s) successfully cancelled!",
    "data": {
        "authorizations": [
            {
                "duration": {
                    "startDate": "2021-03-10T11:49:37.141Z",
                    "endDate": null,
                    "interval": null,
                    "oneTime": true
                },
                "accounts": [],
                "initialAmount": null,
                "amount": 10000,
                "initiated": false,
                "disconnect": true,
                "disconnected_at": "2021-03-10T13:12:41.508Z",
                "_id": "602ba395062f875c2a7d433b",
                "customer": {
                    "_id": "5e9bbfb856ec36e888195d03",
                    "name": "Lorem Ipsum"
                },
                "bank": {
                    "_id": "5f0cf73e8a8bcc18b8156ad7",
                    "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+icon.svg",
                    "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+Bank+Logo+(White).svg",
                    "name": "Kuda Bank",
                    "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Kuda+Bank.png"
                },
                "disconnected_by": "5f2922b59afab10984102e52"
            }
        ]
    }
}

Reauthorise Future Payment

Okra allows you to reauthorise a previously cancelled payment.

📘

NB

Reauthorising a cancelled authorisation (only works if it was not cancelled by the customer).

Run in PostmanRun in Postman

url -X POST https://api.okra.ng/v2/pay/authorization/reauth
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
  "authorization": "602ba395062f875c2a7d433b",
  "customer": "5e9bbfb856ec36e888195d03",
  "link": "602ba2c5cf08f006d11df72a",
  "account": "6026776de26cb3db2b5250c2"
}'
{
    "status": "success",
    "message": "Payment authorization(s) successfully re-authorized!",
    "data": {
        "authorizations": [
            {
                "duration": {
                    "startDate": "2021-03-10T11:49:37.141Z",
                    "endDate": null,
                    "interval": null,
                    "oneTime": true
                },
                "accounts": [
                    {
                        "_id": "6026776de26cb3db2b5250c2",
                        "name": "Lorem Ipsum",
                        "nuban": "4577765436"
                    }
                ],
                "initialAmount": null,
                "amount": 10000,
                "initiated": false,
                "disconnect": false,
                "disconnected_at": null,
                "_id": "602ba395062f875c2a7d433b",
                "customer": {
                    "_id": "5e9bbfb856ec36e888195d03",
                    "name": "Lorem Ipsum"
                },
                "bank": {
                    "_id": "5f0cf73e8a8bcc18b8156ad7",
                    "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+icon.svg",
                    "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+Bank+Logo+(White).svg",
                    "name": "Kuda Bank",
                    "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Kuda+Bank.png"
                },
                "disconnected_by": null
            }
        ]
    }
}

List Payment Authorisations

You can also view the list of all your payment authorizations.

url -X POST https://api.okra.ng/v2/pay/authorization/list
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
 "page": "1"
}'
{
    "status": "success",
    "message": "Customer payment authorizations successfully retrieved",
    "data": {
        "authorizations": [
            {
                "owner": "5d9288ea182d3d000cb7c486",
                "env": "production-sandbox",
                "link": "602ba2c5cf08f0er4d11df72a,
                "payLink": "602ba2c5cf08f006d11df72a",
                "customer": "602d7a668299304ef0df55f2",
                "accounts": [
                    {
                        "_id": "6046795da67cb326c5a1277e",
                        "bank": {
                            "_id": "5d6fe57a4099cc4b210bbec0",
                            "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Access+Bank+PLC+Logo+Color.svg",
                            "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Access+Bank+PLC+Logo.svg",
                            "name": "Access Bank"
                        },
                        "nuban": "2345677887",
                        "customer": {
                            "_id": "602d7a668299304ef0df55f2",
                            "name": "Jane Evans"
                        },
                        "name": "Jane Evans"
                    }
                ],
                "bank": "5d6fe57a4099cc4b210bbec0",
                "duration": {
                    "startDate": null,
                    "endDate": null,
                    "interval": null,
                    "oneTime": true
                },
                "initiated": false,
                "credential": "60467b4ba67cb326c5a16e3a",
                "garnish": false,
                "history": [
                    "60467b21a67cb326c5a167f6",
                    "604680d1a67cb326c5a21264"
                ],
                "disconnect": false,
                "disconnected_at": null
            }
        ],
        "pagination": {
            "totalDocs": 1,
            "limit": 10,
            "hasPrevPage": false,
            "hasNextPage": false,
            "page": 1,
            "totalPages": 1,
            "pagingCounter": 1,
            "prevPage": null,
            "nextPage": null
        }
    }
}

Run in PostmanRun in Postman


Did this page help you?