Skip to content

Payments Example

Introduction

In this example we'll go through all of the steps and give examples on what you'll need to do to implement a call to pay out funds to customers. Once you've read through this guide you'll know everything that is required by us for you to use our payout system.

Let's assume you operate in the US, and would like to use our site to send funds to Nigerian bank accounts. You have a user registered and KYC'd on your site called Jane Doe. She is a recurring user on your site, and her user ID in your system is Sender:US:234523. She creates a transaction on your site asking you to send 400 NGN to her partner in Nigeria John Doe. She is going to fund the transaction in USD. Let's assume the transaction created in your system has an ID of Transaction:NGN:17523.

Once you have the details collected on your end, you can then initiate the transaction in our system. This example will guide you through the details you need to set and what calls you need to make.

We require that all implementations to our site pass our onboarding test before we allow users to access our prouction site. This example shows the preferred solution to all requirements we have, so following this example will make sure you will adhere to our requirements and will hopefully pass our onboarding test.

This guide assumes that you are doing a full KYC on your senders which we have approved.

Authentication

First thing is that you'll need to authenticate to use our site. You can get your API key and secret by contacting our team.

You need to contact us before you are allowed to use our sandbox environment. Once you reach out to us you'll also be invited to our Skype group where you can post questions about our API that will be answered by our Engineering team. We prefer technical communication to go through this Skype group.

Once you obtain your api key and secret you'll need to set up your environment with them:

See the authentication documentation for more details on the authentication process.

Sender details

Next step is setting up the sender details. Generally you'll need to send us the following information for every sender:

  • first_name
  • last_name
  • country_code
  • phone_number
  • birth_date

You should also send us the ID you use in your local system to link to this sender, in this example Sender:US:234523. By doing so you'll be able to handle senders much easier in our system.

Being able to re-use senders is one of our main requirements for successful onboarding. By linking the senders from your system to our system you can make sure you won't have issues fulfilling this dependency.

{
    "type": "person", // required
        // person
        // business

    "first_name": "Jane", // required
    "last_name": "Doe", // required

    "birth_date": "1997-01-01", // required

    "gender": "female",
        // male
        // female

    "identification_type": "passport",
        // driving_license
        // passport
        // other

    "identification_number": "LOL12345", // required if 'identification_type' present
    "identification_expiry": "3002-01-01",

    "country_code": "USA", // required
    "city": "City",
    "street": "Street",
    "postal_code": "12345",

    "phone_number": "+14158586273", // required, international format
    "email": "[email protected]",

    "ip": "127.0.0.1",

    "external_id": "Sender:US:234523" // required
}

Recipient details

Once you have the sender let's set up the recipient as well. In this example we're going to do an bank payout to NGA, which requires a name and the bank account details. Other payout providers might have different requirements, to check them please see our payout details documentation.

{
    "type": "person",
        // person
        // business

    "first_name": "John", // required
    "last_name": "Doe", // required

    "birth_date": "1970-01-01",

    "gender": "male",
        // male
        // female

    "country_code": "NGA", // required
    "city": "City",
    "street": "Street",
    "postal_code": "12345",

    "phone_number": "+14158586273", // required, international format
    "email": "[email protected]",

    "bank_name": "Example bank",
    "bank_code": "111",
    "bank_account": "1111111111",
    "bank_account_type": "current"
}

Business recipient

In case you need to transfer to a business, you can set the type to business, and pass the company name in the first_name and last_name fields. The rest of the details are the same as for a person.

{
    "type": "business",
        // person
        // business

    "first_name": "Example Company", // required
    "last_name": "Ltd", // required

    "country_code": "NGA", // required
    "city": "City",
    "street": "Street",
    "postal_code": "12345",

    "bank_name": "Example bank",
    "bank_code": "111",
    "bank_account": "1111111111",
    "bank_account_type": "current"
}

Tying all together

Finally we need to tie the sender and recipient together into a transaction. The are couple extra details required: the external ID of this transaction (how you refer to this transaction in your system), currency this transaction will be funded (the currency you held your balance with us).

You'll also need to send in how much you wish to send. In this example we're sending 400 NGN, that are going to be received in NGN - we'll calculate the input_amount_in_cents based on the exchange rates.

External ID is a required field for transactions, sending it can help tie transactions between our systems easier. Also you can use it to block duplicate transactions as we won't allow you to send in another transaction with the same external ID in the future.

{
    "sender": {
        // sender details from the previous section
    },
    "recipient": {
        // recipient details from the previous section
    },
    "type": "bank", 
    "input_currency_code": "USD",
    "output_currency_code": "NGN",
    "output_amount_in_cents": "40000",
    "external_id": "Transaction:NGN:17523"
}

Creating the transaction

Now that we have generated the objects, we'll need to call the endpoint. The easiest way is to use our create endpoint which will create the transaction.

Using this endpoint you should create and fund the transactions separately, and double check the amounts inside the transaction after it has been created, and only fund it afterwards. Transactions will never initate payments before they are funded.

POST /transactions

{
    // full transaction details from the previous section
}

Info

Please note that as you can usually always expect validation errors calling any of our endpoints, so you should always check for errors when calling our APIs. A transaction which has validation errors is never created, you have to re-create it once the problems with the details have been fixed.

Funding the transaction

After you have created transaction, and happy with input_amount_in_cents, which we will charge from your internal balance, you can fund the transaction. You can read more on funding payments in the transaction flow documentation.

POST /transactions/[GLOCURRENCY_TRANSACTION_ID]/fund

Waiting for the transaction to complete

Once the transaction is created and funded it goes into our processing queue. During this processing we will constantly try to pay out the funds. Dependent on the payment corridor and the recipient this can take anything from couple of minutes to a couple of days. In order to let you know when the transaction has finished paying out we will send out a notification to your registered webhook address, to let you know that the transaction has finished processing.

To set up webhooks you can use the API. We will always call the endpoint you set up here using POST, and the request will always contain the Authorization-Nonce and Authorization-Signature headers, so you can use them to validate that the request is coming from us.

See the webhooks documentation for more details on what you can expect to receive on the endpoint you register with us.

You will need to handle three major webhook events namely transaction.paid_out, transaction.refunded and transaction.error. The first one will notify you if the transaction was succesfully paid out to the recipient. The second one will notify you if a transaction was cancelled and the funds have been returned to your balance. Finally the last one will notify you if there was a problem while trying to pay out the recipient.

If you don’t do full KYC then you should also sign up for the sender.approved event which will notify you if a sender is approved and can start transacting, and the sender.rejected event which signals if there is a problem with the sender.

If the transaction was paid there is nothing more to do from our end, you can update the system on your end to let your customer know that the transaction has paid out. On cancellation you’ll need to update your system to know that this transaction will not process further.

If there was an error you can find the error description in the state_reason field of the transaction. Note that this error is usually technical in nature hence we don’t suggest to showing this to your customer verbatim. It can be shown to your customer support staff however.

Getting the transaction state manually

While we prefer that you primarily use the webhook facility to get notified about state changes, occasionally you might want to query a transaction’s state in our system so you’ll be able to update it on your end. You can use the Glo Currency Transaction ID for this.

GET /transactions/[GLOCURRENCY_TRANSACTION_ID]

Cancelling transactions

Finally as mentioned above sometimes payment processing can fail for various reasons. While we try as hard as possible to pay out the funds to the intended recipient, occasionally you wish to stop this process and get a refund.

DELETE /transactions/[GLOCURRENCY_TRANSACTION_ID]