Creating a One-time-payment

Accept payments by creating charges

Overview

Okra allows you to initiate a direct NIP (instant payment) EFT transfer on your customer’s behalf. This is a seamless instant settlement payment that is transferred direct from your customer’s bank account to your company's corporate account connected to Okra.

🚧

Avoid NSF Fees

With Okra, you can check your customer’s bank account before you initiate a payment. This allows you to capture payments seamlessly without having to worry about insufficient funds. Check out our Balance product to begin.

To get started, in the next section you learn how you can integrating one-time payment via the widget, in less than 2 minutes, else if you desire to integrate one-time payment via our API check this guide instead.

Via the widget

To initiate on-time-payment via the widgets, 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: 'one-time',  // recurring
      amount: 50000, // amount in KOBO
      note:  "description of payment" || optional,
      currency: "NGN" || optional // defaults to NGN,
      account: '5f450b2689a23801307c8b5b' // Your account ID to credit
  }
}

Let me explain what's going on here;

  1. To initiate payment you'd have to set payment to true
  2. The default type value is one-time

One-time payment means you only have to charge the customer once.

  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 currency attribute is set by default to NGN, for our Nigeria customers, but is optional.
  4. The account attributes connote the account ID you wish to credit.

Let customers determine the amount

If you want your customers to set the amount themselves, all you'd have to do is make the amount attribute has a null value. During the payment, the customer will automatically be prompted to enter their desired amount.

const options = {
... {other widget options} ... 
payment: true,
charge: {
      type: 'one-time' or 'recurring',
        amount: null, //user will be prompted to enter amount
      currency: 'NGN', //supports 'NGN'
      account: '5f450b2689a23801307c8b5b' // Your companies Okra account id
  }
}

One-Time Payment Via API

❗️

Has Your Customer Authorized?

Your customer must first authorize you to debit them before you can use this route. Setup Payment for Later

How it Works?

In using the API, there are about three options available, they include;

1. Initiate Payment - Account ID

  • In this option, when you make a POST request to this endpoint, you'd have to provide the account Id you which to debit and the account Id you wish to credit, and of course the amount as parameters.
    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
        "amount": 10000, //kobo e.g. 100.00 naira = 10000,
        "currency": "NGN" // only NGN supported for now,
    "wallet_currency": "USD", "RND", "KYS" //optional to charge a wallet that is not your NGN
}'
const okra_client = require("okra-node")
okra_client.initiate(accessToken
                     {
                     account_to_debit: "5fe0a6f8ee69d878a679ef39",
                     account_to_credit: "5fe0a6f8ee69d878a679ef39",
                     amount:4000,
                     currency: "NGN" 
                     }, (err, results) => {
    // Handle err
    const payments = results.initiate;
    });
{
    "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"
                }
            }
        }
    }
}
{
    "status": "error",
    "message": "Initiatial Auth Error - Payment -- visit https://get.okra.ng/okra-pay-docs for more info",
    "data": {
        "payment": {
            "record": "5fc44c56455b2530f2cfb95c",
            "amount": 10000,
            "bank_response": null,
            "created_at": "2020-11-30T01:35:20.043Z",
            "credit_account": "Okra Wallet",
            "currency": "NGN",
            "customer": "5e98fd2178b73e2656b93609",
            "debit_account": "5e98f3196f65141382e96781",
            "email": null,
            "env": "production",
            "error": {
                "type": "error",
                "error": true,
                "status": false,
                "code": 1027,
                "method": "Initiatial Auth Error - Payment",
                "message": "Customer has not completed their initial authorizaion. Please authorize the user for payments before trying again."
            },
            "last_updated": "2020-11-30T01:35:21.667Z",
            "link": null,
            "meta": null,
            "owner": "5d9288ea182d3d000cb7c486",
            "ref": "HNzKPlhwKVUTtkp",
            "schedule": null,
            "source": "api",
            "status": "error",
            "id": "5fc44c589016589c6d2a9d0b"
        },
        "okra_wallet": {
            "amount": 1000,
            "currency": "NGN",
            "last_updated": "2020-11-26T15:52:25.108Z",
            "id": "5fb9868c4c805c0d64b519b5"
        },
        "callback_url": null,
        "customer": null
    }
}
{
    "status": "error",
    "message": "You must provide a valid `account_to_debit` to continue or visit https://get.okra.ng/okra-pay-docs for more info",
    "data": {
        "success": false,
        "msg": "You must provide a valid `account_to_debit` to continue or visit https://get.okra.ng/okra-pay-docs for more info"
    }
}

2. Intiate Payment - Nuban/Bank

  • This option is quite similar to the first, just that you have the Nuban param which is optional and another param which is the bank id

You can find the list of bank coverage and their corresponding IDs check here.
Note: The response is also similar to the first.

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,
    "nuban": ACCOUNT NUBAN, //optional,
    "bank": BANK ID, // can be found on our Bank Coverage page
        "amount": 10000, //kobo e.g. 100.00 naira = 10000,
        "currency": "NGN" // only NGN supported for now,
    "wallet_currency": "USD", "RND", "KYS" //optional to charge a wallet that is not your NGN
}'

3. Initiate Payment - Bulk

  • Once again the params and the responses are quite similar to the first, the only difference is that it's mostly required when the need to make payment to more than one bank or account is required, hence the term, Bulk.

The unique fields in a bulk payment are:

  • account_to_debit
  • A payment array with nuban and bank id as properties.
curl -X POST https://api.okra.ng/v2/pay/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
   "account_to_debit": "604881fb4cfd831580335612",
   "amount": 10000,
   "currency": "NGN",
   "payments": [{ 
       "nuban": "1928394883",
       "bank": "5d6fe57a4099cc4b210bbeb3"
   }],
   "callback_url": "https://api.webhook.com/okra-webhoook", //optional
   "wallet_currency": "USD", "RND", "KYS" //optional to charge a wallet that is not your NGN
}'

//you can send account_to_debit, amount, and currency per payment as well

:information-source:
Check out our Payment Reference to test it out.


Did this page help you?