Setup Future Payments

Overview

Learn how to retrieve data and charge your customers later

🚧

Bank Coverage

Currently, you can only use future and recurring payments with eligible banks.

Okra's debitLater feature allows you to save a customer’s details without an initial payment. This is helpful if you want to onboard customers now, set them up for payments, and charge them in the future, through the API.

Use this integration to set up recurring payments or to create one-time payments with a final amount determined later, often after the customer receives your service.*

Setting up the Okra Widget

const options = {
  {...widget options...}, // https://okra.readme.io/docs/widget-properties
  debitLater: true,
  debitAmount: 10000, // optional kobo amount 
  debitType: 'one-time', 'recurring', or 'ongoing',
  debitStartDate: 'YYYY-MM-DD', // optional starting date for recurring
  debitEndDate: 'YYYY-MM-DD', // optional starting date for recurring
  debitInterval: 'monthly', 'weekly', 'yearly', //optional recurring interval
}

Verify a payment

While making a payment, communication, or technical issues can prevent your customer from paying and your API from receiving a response. Without this response, you may be unable to verify whether the payment has been processed, or its result.

This may cause you to attempt to cancel or refund the transaction, or risk a duplicate transaction.

Instead, your integration should request the payment status to verify whether the transaction is successful, pending, failed, canceled, or not found.

Payment Status Messages

PENDING

When a payment is waiting for processing

FAILED

When a payment failed

NO_CONSENT

The customer did not approve the payment

COMPLETED

When a payment completed

COMPLETED_PENDING_VALIDATION

When a payment is completed but is pending settlement and validation.

CANCELLED

When a customer canceled a payment or the payment was canceled by the API.

Check a Payment Status

curl -X POST https://api.okra.ng/v2/pay/verify
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{
    "payment_id":"PAYMENT ID"
}'
{
    "status": "success",
    "message": "Payment Status suceccefully retrieved!",
    "data": {
        "payment_status": {
            "_id": "5f88ebf63103d912f1d4baca",
            "amount": 10000, //kobo
            "currency": "NGN",
            "customer": "5f5b67748df30163f294f432",
            "link": {
                "_id": "5f824ed45f283033c424f530",
                "url": "https://dev-pay.okra.ng/wyred",
                "short_url": "wyred",
                "surl": "https://dev.okr.to/wyred"
            },
            "status": "completed",
            "response_status": "success"
        }
    }
}

Payment Refunds

You can refund payments made through links or via the API; you are able to refund the whole amount or part of it. Refunds use your available Okra Wallet balance — this doesn’t include any pending payouts. If your available wallet balance doesn’t cover the amount of the refund, Okra will debit the remaining amount from your connected bank account.

​​If Okra can’t debit the remaining amount from your bank account, your refunds will be pending until you fund your Okra Wallet. You can view a list of all your pending refunds in the Dashboard.

If the original charge underwent currency conversion, the refunded amount converts back using the same process. There are no fees to refund a charge, but the fees from the original charge aren’t returned.

We submit refund requests to your customer’s bank. Your customer sees the refund as a credit approximately 3-10 business days later, depending upon the bank. Once issued, a refund cannot be canceled.

We’ll also send an email to your customer notifying them of the refund if all of these conditions apply:

  • The original charge was created on a Account object in your Okra account.
  • The customer object has a stored email address.
  • You have Email Customers for Refunds enabled.

📘

Not a Developer?

You can initiate refunds directly from the Okra Dashboard via the Payment Links page.

Issue a Refund

Refunds can be issued via the API or the Dashboard and are processed immediately. Once issued, a refund cannot be canceled.

You can issue more than one refund against a charge, but you cannot refund a total greater than the original charge amount.

Refunds via the API

To refund payment via the API, create a Refund and provide the ID of the payment to be refunded.

To refund the customer’s payment, create a refund using the Payment ID, which is equivalent to refunding the underlying charge. You can also optionally refund part of their payment by specifying an amount. You can perform refunds with the API or through the Dashboard.

Note that this does not apply if you Setup Payment for Later or you wish to refund a Payment that has yet to be captured. In this case, you should cancel the Payment Intent instead.

To refund part of a Payment, provide an amount parameter, as an integer in kobo (or the charge currency’s smallest currency unit):

curl -X POST https://api.okra.ng/v2/pay/refund
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{ 
            payment_id: "5fe0a6f8ee69d878a679ef39" ,
        reason: "" //optional reason for customer
        amount: 10000, //optional amount for partial payments
        }'
{
    "status": "success",
    "message": "Refund has been initated; Please verify `reufund_payment` to confirm.",
    "data": {
        "refund": {
            "history": {
                "initiated_at": "2021-03-06T03:06:40.849Z",
                "success_at": null,
                "failed_at": null
            },
            "_id": "6042f1c0186a934962b41829",
            "env": "production-sandbox",
            "owner": null,
            "payment": "5f894ee474b8fde5851af169",
            "receiever": "5f89451c0f0c0775eed267ac",
            "__v": 0,
            "amount": 10000,
            "created_at": "2021-03-06T03:06:40.851Z",
            "currency": "NGN",
            "initiator": "5da4c3564d32480a24663fab",
            "last_updated": "2021-03-06T03:06:40.851Z",
            "reason": null,
            "record": "6042f1c03183ddf6d0e2b7ec",
            "status": "initiated"
        },
        "refund_payment": {
            "success": true,
            "data": {
                "payment": {
                    "record": "6042f1c03183ddf6d0e2b7ec",
                    "amount": 10000,
                    "bank": "5d6fe57a4099cc4b210bbeb3",
                    "bank_response": null,
                    "created_at": "2021-03-06T03:06:42.118Z",
                    "credit_account": "5e86430b6b06ff0dbfa899a9",
                    "currency": "NGN",
                    "customer": null,
                    "debit_account": "5f894d2274b8fde5851a81b5",
                    "email": null,
                    "env": "production-sandbox",
                    "error": null,
                    "fee": null,
                    "last_updated": "2021-03-06T03:06:42.118Z",
                    "link": null,
                    "meta": null,
                    "meta_responses": null,
                    "owner": "5da6358130a943486f33dced",
                    "ref": "dIPC-C8Dhtxka7m",
                    "schedule": null,
                    "source": "api",
                    "status": "initialize",
                    "id": "6042f1c2186a934962b418b5"
                },
                "okra_wallet": {
                    "amount": 4356660,
                    "currency": "NGN",
                    "last_updated": "2021-03-06T03:06:41.040Z",
                    "id": "6029823848295532905ba4fb"
                },
                "callback_url": "https://api.okra.ng/v2/callback?record=6042f1c03183ddf6d0e2b7ec&method=PAYMENT",
                "customer": {
                    "name": "Dami Banwo",
                    "id": "5f89451c0f0c0775eed267ac",
                    "account": {
                        "id": "5f894d2274b8fde5851a81b5",
                        "name": "Dami Banwo",
                        "nuban": "6444696413",
                        "bank": {
                            "name": "Guaranty Trust Bank",
                            "slug": "guaranty-trust-bank",
                            "id": "5d6fe57a4099cc4b210bbeb3",
                            "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/GT+Bank.svg",
                            "png_logo": "http://d1f1tz87xvarxp.cloudfront.net/Nigerian+Banks/Guaranty+Trust+Bank+Logo.png",
                            "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Guaranty+Trust+Bank+Logo+Color.svg"
                        }
                    }
                }
            },
            "error": null,
            "msg": "Payment has been initiated; Please verify to complete"
        }
    }
}
{
    "status": "error",
    "message": "Duplicate request. This payment has already been refunded.",
    "data": {
        "refund": {
            "_id": "6042ee3d186a934962afecac",
            "amount": 10000,
            "created_at": "2021-03-06T02:51:41.413Z",
            "currency": "NGN",
            "history": {
                "initiated_at": "2021-03-06T02:51:41.412Z",
                "success_at": "2021-03-06T02:52:06.055Z",
                "failed_at": null
            },
            "initiator": "5da4c3564d32480a24663fab",
            "reason": null,
            "status": "completed",
            "meta": null,
            "refund_payment": {
                "_id": "6042ee3e186a934962afed71",
                "amount": 10000,
                "credit_account": "5e86430b6b06ff0dbfa899a9",
                "currency": "NGN",
                "customer": "5f89451c0f0c0775eed267ac",
                "debit_account": "5f894d2274b8fde5851a81b5",
                "env": "production-sandbox",
                "owner": "5da6358130a943486f33dced",
                "ref": "OKR PAY Ref 4KwQPxWigTf6KmQ",
                "status": "success"
            }
        }
    }
}
{
    "status": "error",
    "message": "You cannot intiate a refund for an amount greater than the initial payment.",
    "data": {
        "payment": {
            "_id": "5f894ee474b8fde5851af169",
            "record": "5f894ed7a3a1c81492bf3819",
            "__v": 0,
            "amount": 10000,
            "created_at": "2020-10-16T07:42:28.857Z",
            "credit_account": "5e86430b6b06ff0dbfa899a9",
            "currency": "NGN",
            "customer": "5f89451c0f0c0775eed267ac",
            "debit_account": "5f894d2274b8fde5851a81b5",
            "email": null,
            "env": "production-sandbox",
            "error": {},
            "last_updated": "2021-01-08T09:51:54.531Z",
            "link": "5f851e0abd292df866f7fd32",
            "meta": null,
            "owner": "5da6358130a943486f33dced",
            "ref": "OKR PAY Ref E9dv5IK__",
            "schedule": null,
            "source": "link",
            "status": "success",
            "refund_amount": 40000,
            "account_to_debit": "5f894d2274b8fde5851a81b5"
        }
    }
}
{
    "status": "error",
    "message": "You cannot intiate a refund on a payment that is in progress or failed.",
    "data": {
        "payment": {
            "_id": "5f894ee474b8fde5851af169",
            "record": "5f894ed7a3a1c81492bf3819",
            "amount": 10000,
            "created_at": "2020-10-16T07:42:28.857Z",
            "credit_account": "5e86430b6b06ff0dbfa899a9",
            "currency": "NGN",
            "customer": "5f89451c0f0c0775eed267ac",
            "debit_account": "5f894d2274b8fde5851a81b5",
            "email": null,
            "env": "production-sandbox",
            "error": {},
            "last_updated": "2021-01-08T09:51:54.531Z",
            "link": "5f851e0abd292df866f7fd32",
            "meta": null,
            "ref": "OKR PAY Ref E9dv5IK__",
            "schedule": null,
            "source": "link",
            "status": "success",
            "refund_amount": 40000,
            "account_to_debit": "5f894d2274b8fde5851a81b5"
        }
    }
}
{
    "status": "error",
    "message": "You do not have sufficient funds in your wallet to initiate this refund, please pass an `account` ID or lower the refund amount to continue",
    "data": {
        "wallet": {
            "_id": "6029823848295532905ba4fb",
            "amount": 0,
            "currency": "NGN",
            "env": "production-sandbox",
            "last_updated": "2021-03-06T03:06:41.040Z"
        }
    }
}

Cancel a Payment

You can cancel a Payment if you no longer intend to use it to collect payment from the customer. Canceling a Payment is optional, and it’s okay to keep a Payment in an incomplete status. Incomplete Payments are useful in understanding your conversion rates.

A Payment can only be canceled when it has one of the following statuses: initialized or
pending.

curl -X POST https://api.okra.ng/v2/pay/cancel
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{ 
        payment_id: "5fe0a6f8ee69d878a679ef39"
    }'

A Payment can’t be canceled while it is actively processing or once it has succeeded.

When a Payment is canceled, you can no longer use it to perform additional charges. Any operations that your application attempts to perform on a canceled Payment will fail with API Errors.

📘

Check the reference for more info


Did this page help you?