One-time payments

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 directly from your customer’s bank account to your company's corporate account connected to Okra.

In the next section, you learn how you can integrate one-time payment via the widget and via the API, in minutes.

Initiate via the widget

To initiate a one-time-payment via the widgets, simply update your widget properties 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',
      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;

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

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

Amounts are always set by default to KOBO!
The note attributes are optional, yet necessary if you wish to describe the payment.
The currency attribute is set by default to NGN, for our Nigeria customers, but is optional.
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
  }
}

Initiate via the API

Asides from having been able to initiate payment via the widget, you can also utilize the API to initiate a payment. Using the method comes with a lot of flexibility.

1. Using 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: "xxxxxxxxxxxxxxxxxxx",
                     account_to_credit: "xxxxxxxxxxxxxxxxxx",
                     amount:4000,
                     currency: "NGN" 
                     }, (err, results) => {
    // Handle err
    const payments = results.initiate;
    });

{
    "status": "success",
    "message": "Payment succesfully initiated!",
    "data": {
        "payment": {
            "record": "xxxxxxxxxxxxxxx",
            "amount": 10000,
            "bank_response": null,
            "created_at": "2020-11-30T01:26:33.526Z",
            "credit_account": "Okra Wallet",
            "currency": "NGN",
            "customer": "xxxxxxxxxxxxxxx",
            "debit_account": "xxxxxxxxxxxxxxx",
            "email": null,
            "env": "production",
            "error": null,
            "last_updated": "2020-11-30T01:26:33.526Z",
            "link": null,
            "meta": null,
            "owner": "xxxxxxxxxxxxxxx",
            "ref": "nMo4RhqE7ymBlYQ",
            "schedule": null,
            "source": "api",
            "status": "initialize",
            "id": "xxxxxxxxxxxxxxx"
        },
        "okra_wallet": {
            "amount": 1000,
            "currency": "NGN",
            "last_updated": "2020-11-26T15:52:25.108Z",
            "id": "xxxxxxxxxxxxxxx"
        },
        "callback_url": "https://api.okra.ng/v2/callback?record=5fc44a4859a9542d6962266e&method=PAYMENT",
        "customer": {
            "name": "GAVIN BELSON",
            "id": "xxxxxxxxxxxxxxx",
            "account": {
                "id": "5e98f3196f65141382e96781",
                "name": "EDISON MADUABUCHUKWU OBODO",
                "nuban": "0033823682",
                "bank": {
                    "name": "Stanbic IBTC Bank",
                    "slug": "stanbic-ibtc-bank",
                    "id": "xxxxxxxxxxxxxxx",
                    "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"
                }
            }
        }
    }
}

{
      "method":"PAYMENT",
      "callback_type":"PAYMENT",
      "callback_code":"PAYMENT_SUCCESS",
      "type":"CALLBACK",
      "code":"PAYMENT_SUCCESS",
      "callbackURL":"http://localhost:5000/v2/callback",
      "env":"production",
      "status":"is_success",
      "started_at":"2021-09-13T16:36:46.997Z",
      "ended_at":"2021-09-13T16:39:01.346Z",
      "message":"Record callback started!",
      "accountId":"609aa830dd46hfd2604a518f",
      "meta_responses":null,
      "options":{},
      "meta":{},
      "bankName":"Guaranty Trust Bank",
      "bankType":"ind",
      "bankId":"5d6o9hg4s099cc4b210bbeb3",
      "bankSlug":"guaranty-trust-bank",
      "record":"613f7c8c37a198uhbv4efce9",
      "recordId":"6190ok7627a1679413eefce9",
      "callback_url":"https://api.okra.ng/v2/callback?record=613f7c8c37a198uhbv4efce9&method=PAYMENT",
      "login_type":"mobile",
      "customerId":"608b0098yt5fg42a4989c70c",
      "identityType":"bvn",
      "customerEmail":[
         "[email protected]"
      ],
      "country":"NG",
      "extras":{
         
      },
      "garnishment":{
         "amount_collected":10000
      },
      "schedule":{
         "current_amount":0,
         "paymentId":"613f7e0a7a7b6917bee79ef5"
      },
      "paymentId":"613f7c8c37a198uhbv4efce9",
      "link":null,
      "payment":{
         "_id":"613f7c8c37a198uhbv4efce9",
         "record":"613f7c8c37a198uhbv4efce9",
         "amount":10000,
         "available_balance":null,
         "bank":"5d6fe57a4099cc4b210bbeb3",
         "bank_response":{
            "CODE":"1000",
            "MESSAGE":"TRANSACTION SUCCESSFUL",
            "SESSIONID":"0000132186543073850000325621364",
            "ERROR":null,
            "STATUSCODE":null,
            "STATUSMESSAGE":null,
            "NIBSSRESPONSECODE":" 00",
            "BANKDOWNTIMEMESSAGE":"",
            "DestAccName":"OKRA WALLET"
         },
         "created_at":"2021-09-13T16:36:26.652Z",
         "credit_account":"5eaaff7741318jh464b964d3",
         "currency":"NGN",
         "current_project":"6050d01a9307g087a64462cf",
         "debit_account":"609aa830dd48gf72604a518f",
         "email":null,
         "env":"production",
         "error":null,
         "error_response":null,
         "fee":26.88,
         "last_updated":"2021-09-13T16:38:58.809Z",
         "link":null,
         "meta":{
            
         },
         "meta_responses":null,
         "owner":"5d9288ea182d38v00cb7c486",
         "ref":"Okra, Inc via OKR PAY Ref _XbpOiwNX",
         "schedule":null,
         "source":"link",
         "status":"success",
         "customer":"608b03b09doj2d2a4989c70c"
      },
      "current_project":"6050d00o9306f087a64462cf",
      "owner":"5d9288ea182d3dho0cb7c486"
   },
   "serverResponse":{
      "status":"error",
      "message":"Record does not match this user, please use your correct Bearer Token or record does not exist!",
      "data":null
   }

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

📘
Account_to_debit must be an okra_id(authenticated account)
Account_to_credit can either be an okra_id(if the account has been authenticated) or nuban and bank

2. Using NUBAN / Bank

This option is quite similar to the first, just that you have to include 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
}'

Initiate via the dashboard

After a successful login to your dashboard, click on payment on the side nav.
Next, click on the “Records”.
Select the **single payment** tab on the page to initiate debit.

To initiate debit Input the fields in the form as seen below.

Account to debit: Choose from the dropdown menu, what account you want to debit
Amount: The monetary amount of the transaction in the lowest denomination e.g NGN
Interval: This represents the period you want the debit to commence, the options are daily, weekly, monthly, quarterly, bi-annually, and annually.

Initiate via bulk upload

The bulk payment feature allows you to make bulk payments from a bulk list.
The endpoint accepts a POST request, with product and file as required parameters.
The product parameter takes initiate_payment as the value, while the file requires you to upload a CSV file.

Key	Value
file	your_CSV_file
product	initiate_payment

This endpoint returns the following details:

✔ file name
✔ owner id
✔ product
✔ status
✔ user id

📘
This CSV file is the bulklist

Prerequisite

If you're on a sandbox mode, ensure you create a customer using this guide.
Setup your webhook
File size - The file size should not exceed 5 MB
The bulk list which has to be in a CSV format must have the following columns;

account_to_debit - This involves the account that makes the payment
account_to_credit - This refers to the accounts payments will be made to
amount - The amount in figures
currency - NGN
callback_url - A callback URL

curl -X POST https://api.okra.ng/v2/bulkfiles/initiate
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "account_to_debit":  ACCOUNT ID,
    "account_to_credit": ACCOUNT ID,
        "amount": 10000, //kobo e.g. 100.00 naira = 10000,
        "currency": "NGN" // only NGN supported for now,
    "callback_url": "a valid webhook url"
}'

{
    "status": "success",
    "message": "File successfully uploaded",
    "data": {
        "id": "xxxxxxxxxx",
        "file_name": "yourcsvfile.csv",
        "owner": "xxxxxxxxxx",
        "product": "initiate_payment",
        "status": "in-progress",
        "user": "xxxxxxxxxx"
    }
}

curl -X GET https://api.okra.ng/v2/}/bulkfiles/initiate/verify/:file_id
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "file_id":"xxxxxxxxxx"
}'

👍
💡 Note
If duplicate entries are found in the bulk file, it will be flagged to the user, and only one instance will be processed.
A duplicate entry occurs when more than 1 row is exactly the same or more than 2 rows have the same customer, i.e same account_to_debit and account_to_credit
The user cannot charge the same person twice, it has to be for different amounts and/or currencies.

Initiate via the dashboard

You can also make bulk payments directly from your dashboard.
Login to your dashboard, and click on payment on the side nav.
Next, click on the “Records”.
Select the **bulk payments** tab on the page to initiate debit.

To initiate a bulk payment, upload a CSV document containing your bulk list.

The next step is reviewing the list or possibly replacing the list. If the list looks good, click on the confirm payment and await verification.
Once the payment is verified, you have made successfully made a bulk payment.

To learn about payment verification, check here.

Make quick payments

You can make quick payments in less than 4 clicks for returning users who once linked their account to your platform.
To make quick payment via the widgets, simply update your widget properties, specifically the charge object among other widget options as seen below:

charge: {
      .... other charge fields ...,
      reauth_bank: "banks-slug",
      reauth_account: "account nuban"
}

The reauth_bank and reauth_account are the fields used to identify that a particular user has previously linked their account to your platform, hence the linking phase is skipped.
This approach eliminates account linking duplicates and speeds up paymnet.

Check out our Payment Reference to test the one-time payment endpoint.

👊🏼 Congratulations, you've successfully learned how to initiate a one-time payment via the Widget.
In the next section, you'll learn how you can initiate a one-time payment via our API.