Bank transfer payments are one-time payments that your customers can use to pay you through their online banking applications. The Pay with Bank Transfer payment method is available on Kora's Checkout and via API.

Accepting Bank Transfer Payments via API

One way to accept bank transfer payments is by using our Bank Transfer API. The following guide will show you how to generate single-use bank accounts for your transactions successfully.

Prerequisites:

1. Before starting, ensure that your Kora account is activated.
2. To accept Bank Transfer payments via API, you need to enable this feature on your account. Contact our team at [email protected] to request the activation of bank transfer payments via API on your account.

💡

Please note that, currently, the Bank Transfer API service is only available for Nigerian Naira (NGN) transactions.

To accept bank transfer payments via API, you can make an API call to the Pay with bank transfer API with the required payment information. Once the call is successful, a dynamic virtual bank account will be generated for the transaction, which your customer can use to make the payment.

A dynamic virtual bank account is a temporary, single-use bank account that can be used to accept one-time payments for transactions. It is dynamic because it is only valid and usable for a limited period of time and for a single transaction, after which it expires. A new and unique dynamic virtual bank account is created for each new transaction under the Pay with Bank Transfer method.

🚧

Presently, the dynamic virtual bank accounts generated for the Bank Transfer payments include Wema Bank, Sterling Bank, and Providus Bank. Additional bank options will be made available over time.

Once you have collected the necessary payment information from your customer, prepare your request to look like the example shown below.

{
    "reference": "test-payment-1", 
    "amount": 1500,
    "currency": "NGN",
    "notification_url": "https://merchant-redirect-url.com",
    "customer": {
    	"name": "John Doe",
    	"email": "[email protected]"
    }
}

The parameters for this request include:

Here's what the response to the request would look like:

{
 "status": true,
 "message": "Bank transfer initiated successfully",
  "data": {
      "currency": "NGN",
      "amount": 1500,
      "amount_expected": 1500,
      "fee": 22.5,
       "vat": 1.69,
       "reference": "idMain02",
       "payment_reference": "idMain02",
       "status": "processing",
       "narration": "Payment on Demo Merchant",
       "merchant_bears_cost": true,
       "bank_account": {
         "account_name": "Demo account",
         "account_number": "7590031627",
          "bank_name": "wema",
            "bank_code": "035",
            "expiry_date_in_utc": "2023-06-05T16:58:09.193Z"
        },
        "customer": {
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

💡

Note: amount expected is the actual amount that your customer is meant to pay for the transaction, and is dependent on who bears the cost for the transaction.

Getting notified of payments

Once a payment has been made to the generated bank account, we will send a webhook notification to the URL you provided for webhook notifications. The reference included in the notification payload can be used to retrieve the payment details.

You can read more about how to handle webhook notifications here.

See an example of a webhook notification below:

{
  "event": "charge.success",
  "data": {
    "reference": "kpy-test-ref",
    "currency": "NGN",
    "amount": 1500,
    "fee": 22.5,
    "status": "success",
}

Before giving value to the customer, it is advisable to requery the transaction by sending a request to the Transaction Query API. To do this, make a GET Request to the Transaction Query API endpoint using the reference returned in the webhook notification request payload.

Testing the Pay with Bank Transfer API on Sandbox

To test the Pay with bank transfer API on the sandbox environment, all you need to do is to switch your Kora dashboard to test mode and access your test secret key in the API configurations section. Use the test secret key for authorization instead of your live secret key.
By default, transactions initiated via the bank transfer API on sandbox are completed automatically after 2 minutes. That is, sandbox payments to the bank accounts generated would be automatically triggered without any action from you. However, if you would like to test the payment flow yourself, you can add an additional field called auto_complete to the request payload for the bank transfer API.

{
    "reference": "test-payment-1", 
    "amount": 1000,
    "currency": "NGN",
    "notification_url": "https://merchant-redirect-url.com",
    "customer": {
    	"name": "John Doe",
    	"email": "[email protected]"
    },
   “auto_complete”: false // this is the additional field to add
}

When the auto_complete field is set to false, you would be required to trigger a payment to the bank account yourself. You can do this by making use of the Sandbox Credit API for Virtual Bank Accounts. Sandbox Virtual Bank Account Credit API.

All you need to do is to pass the account number returned from the bank transfer API and the amount you want to pay.