Garnishment

Learn how to collect partial funds from the customer

What is Garnishment?

The Okra garnishment feature helps vendors legally collect money from accounts to repay outstanding debt. It is a great feature for creditors to use, when debtors repeatedly ignore requests to pay back what they owe.

A use case scenario

To further establish how garnishment can come in very handy, let's observe this scenario - Let's assume KiakiaLoanNG company provides a loan to Kingsley (an entrepreneur), the loan amount was 50,000, and the repayment date of the loan is one month. When the one month elapses and Kingsley doesn't have the exact amount (50,000) to repay the loan or is unwilling to repay the loan, KiakiaLoanNG could leverage the garnish feature to debit partial funds from Kingsley periodically until the loan is completely repaid.

How to Implement Garnishment via the API

📘

Implementing garnishment via the API is quite similar to how one-time payment works.
Except for garnishment, you would have to specify that the debitType option is set to true.

Prerequisite

  1. If you're on a sandbox mode, ensure you create a customer using this guide.
  2. You also would have to connect those customers to the widget and authorize them for future payments.
  3. Set your webhook via the widget options, or globally on your dashboard
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": "garnish",
    "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 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
        }
    }
}

What's going on?

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 garnish.
  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.

You have the right knowledge to garnish your customers 🎉, you can test it out using our reference on the sandbox,
In the next section, you will learn how recurring payments work.


Did this page help you?