Transfers Checkout

Here's how to add Transfers Checkout to your app or website

Introduction

Transfers Checkout is a simple way to initiate instant bank transfers payments directly within your application.

This is different from Transfers Connect, which lets you initiate bank transfers payments but also gives you access to financial information from your users. You can receive your user’s transactions, initiate transactions, and retrieve real-time balances using Transfers Connect.

Installation

You can add Transfers Checkout to your project like this:

index.html

<script src="https://checkout.transfers.africa/lib/lib.bundle.js"></script>

If your project is a mobile app built with native technologies, you can use a Web View to load an HTML page that will have the above code.

Initialise

To initialise Transfers Checkout:

Transfers.init({
    siteName: "<your site or app name>",
    siteUrl: "<your site url>",
    siteLogo: "<url to your logo>",
    publicKey: "<your Transfers public key>"
})

Create transfer charge

To create a transfer charge to any bank account:

const result = await Transfers.charge({
    signature: "<not your signature token - a signature that verifies you're initiating a transaction>",
    amount: "<how much you want to charge in Naira>",
    userId: "<a unique identifier for your user>",
    destinationAccountNumber: "<recipient account number>",
    destinationBankCode: "<recipient bank code>",
    transactionReference: "<a unique identifier for your transaction>",
    name: "optional: <the sender's full name if you want us to ensure that they're sending from their own bank account>"
});

You can retrieve a list of banks and their codes by making a GET request to https://checkout.transfers.africa/banks.json

Charge request signature

For us to know that a request to charge a bank account is truly coming from you and not a bad actor, you must pass the Transfers charge function a signature.

Use the Signature Token provided to you during the onboarding process to generate a signature that is a hex digest of an HMAC-SHA256 hash of your charge arguments:

user_id:payment_reference:amount_kobo:destination_account_number:destination_bank_code

Make sure the amount_kobo in your payload is in kobo and is casted to an integer. For instance, if you're trying to charge 500.32 Naira as your amount, the amount_kobo should be 50032 (and should not be the floating point equivalent e.g do not use 50032.0)

// Ruby example for generating a charge request signature

payload = "#{payment.user_id}:#{payment.reference}:#{payment.amount_kobo}:#{payment.destination_account_number}:#{payment.destination_bank_code}"
OpenSSL::HMAC.hexdigest('sha256', ENV['TRANSFERS_SIGNATURE_TOKEN'], payload)

1. You should never make your signature token public.

2. You should never generate your charge request signature on the client-side. Always request the signature from your server and pass it into Transfers.

Charge to your default settlement account

You can also create a transfer charge to your pre-registered default settlement account:

const result = Transfers.chargeToDefaultAccount({
    signature: "<a signature that verifies you're initiating a transaction>",
    amount: "<how much you want to charge in Naira>",
    userId: "<a unique identifier for your user>",
    transactionReference: "<a unique identifier for your transaction>",
    name: "optional: <the sender's full name if you want us to ensure that they're sending from their own bank account>"
})

Responses

If the transfer charge was successfully created, then result will be:

{ paymentId: "<the transaction reference you passed in earlier>"}

You shouldn't give your users value at this point. That should be done on the server-side and will be explained in the next section of this guide.

If the transfer charge fails or the user closes Transfers Checkout, then result will be:

null