One-time payments
This guide will teach you how to integrate a one-time payment.
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',
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, andannually.
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.
Updated 3 months ago