Transaction flow¶

Introduction¶

Transactions are the main objects in the Glo Currency API, so it's important to understand how to create and manage them. Transactions facilitate money movement from one Sender in a specific currency to one Recipient in another currency.

The main flow of a successful transaction flow is the following:

Transaction is created linking the Sender to the Recipient with the requested amount.
Once the sender is KYC'd and approved the transaction can be funded.
Once the transaction is funded, we will initiate the payout to the recipient.
After the recipient has received the money, the transaction is finished.

Unfortunately not all transactions are successful. The main causes of issues are the following:

Transactions are cancelled automatically if they are not funded within the first hour of creation.
The recipient details might be wrong (for example the destination bank account number is invalid), or there are other issues blocking the successful payout. In these cases the transaction has to be cancelled.
Once the transaction is cancelled, we will refund the money to the account balance.

Creating transactions¶

Transactions can be created by calling the POST /transactions endpoint. The template of transaction requests is the following:

{
    "type": "bank", // type of the transaction,
    "input_currency_code": "USD", // currency to pay in,
    "output_currency_code": "NGN", // the currency to pay out,
    "output_amount_in_cents": "100", // the amount to pay out,
    "sender": {
        // details of the sender
    },
    "recipient": {
        // details of the recipient
    },
    "external_id": // required parameter for adding a custom ID to transactions
}

Note that the external_id field is required. Please see external ID for further information.

A full example transaction creation request with sender creation from USD to NGN would look like the following:

//

Type¶

The type contains which payment method should be user. You can find the commonly used payout types at the payout documentation.

Input currency¶

The input currency describes what currency the transaction will be paid in. For example if you wish to create an EUR to NGN transaction then input currency should be set to EUR.

Output amount and currency¶

This will be the amount that you would like to pay to the recipient. The value here should be in destination currency.

In the transaction create response we will return how much this is in the input currency, and will also return how much we would pay out to the recipient in the output currency.

A few common examples:

Input currency is USD Payout type is bank. Output amount is 40000 NGN.

In this case we will calculate how much 40000 NGN is in USD (as of writing around 105), and will return: input amount is 105 USD and output amount is 40000 NGN
Input currency is USD Payout type is bank. Output amount is 100 USD.

In this case we will simply pay out 100 USD to the recipient. Note that same input and output currencies are only supported if you hold an internal balance with us. If you're interested in that please contact our team.

The output amount is rounded to a specific number of decimal places and this depends on the currency.

Sender¶

This section contains the details of the sender. Every time a specific sender is used the full details should be provided, example:

{
    "type": "person", // required
    "first_name": "Text", // required
    "last_name": "Example", // required
    "birth_date": "2997-01-01", // required
    "gender": "male",
    "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": "1234" // required
}

When a sender is created you will receive a response which contains the sender's state. Possible states for a sender are:

initial - When a sender is created and has not been through any KYC checking (cannot transact)
verified - A sender has passed sanction list checks (cannot transact)
approved - The sender has passed both KYC and sanction checks (can transact)
banned - An admin has banned the sender (cannot transact)
rejected - The sender has failed sanction list checks (cannot transact)
disabled - A sender is put into this state as a result of a delete request via the API (cannot transact)

In order to transact with Glo Currency we need to have an approved sender record. The flow for approving senders depend on whether KYC requirements are waived for your integration or not. In case the KYC requirements are waived then all created senders will be in the approved state immediately, and can be immediately used for transactions.

Please see our KYC documentation on more details about the KYC sender processes.

Sender External ID¶

When creating senders it's a requireement to include the external_id field.

Any time you wish to create a transaction for the same sender you already used, you should use the same external_id. This is so we can tie the transactions made by the same sender together for KYC and AML purposes.

{
    "sender": {
      "external_id": "SENDER_1234"
    },
    // (...)
}

Sender Phone number¶

The sender's phone_number should be in E.164 format and start from from a + sign.

Recipient¶

The recipient describes the country where the money should be sent.

The template for the recipient is the following:

{
    "first_name": "Jane", // required
    "last_name": "Doe", // required
    "birth_date": "1970-01-01",
    "gender": "female",
    "country_code": "USA", // required
    "city": "City",
    "street": "Street",
    "postal_code": "12345",
    "city": "Foo city",
    "bank_name": "Example bank",
    "bank_code": "111",
    "bank_account": "1111111111",
    "bank_account_type": "current",
    "phone_number": "+14158586273", // required, international format
    "email": "[email protected]"
}

Details to fulfill the payment¶

The details to fulfill the payment depend on the chosen payout type. Please check the payout documentation for more details.

Transaction External ID¶

External ID is a required field that allows you to add a custom ID for the transaction, should you wish to link it to a transaction within your own local system. This internal reference value will be displayed in your transaction reports.

We will validate whether we already have transaction with provided external_id in our system or not. This functionality provides a safeguard against transactions being assigned the same external_id. If a duplicate is found, an error will be returned.

Transaction object¶

Once the transaction is created successfully, you will receive back a transaction object. This object will always contain all details about the sender, the transaction and the recipients.

In case the transaction couldn't be created, you will get back a 422 response and inside the errors you should find all of the vaildation messages which should be fixed.

A transaction object looks like the following:

//

As shown, the response contains a lot of information, the most important are the following:

id¶

The ID of the transaction.

state¶

The state of the transaction, which can be one of the following:

initial: Transaction is created, but not yet ready to receive payments (waiting for validation and approving).
verified: Transaction is created, both sender and receipient passed additional validation.
approved: Transaction is created, both sender and recipient are approved. Payment can be received.
pending: Transaction has received a payin, and it’s waiting for the funds to clear.
mispaid: Transaction received funds, but not the requested amount. Transaction will be resized, and will start payout based on the received funds.
received: Transaction has received the correct payin amount and will start processing the payouts.
processing: Payout has been initiated and we’re waiting from a response from the provider.
manual: Payment to the recipient have run into issues. Please check the Transaction state_reason for more information.
paid: Transaction has received correct payins and has performed payout to recipient.
canceled: Transaction has been cancelled.
refunded: Transaction has been cancelled after it has been funded, but the funds have been returned now to the sender either partially or fully.
exception: An exception happened during the processing of the transaction.
error: There was an error from the provider, you can find more details in the state_reason attribute. We will usually retry the transaction at a later date. You can either wait or cancel the transaction.
stuck: We didn't receive a response from the provider in time, and we don't know whether it has been paid our not.

state_reason¶

If there is an error with the transaction you can find the error message in this field.

input_amount and input_currency¶

This is the amount that has to be funded from the internal balance.

sender¶

The full details of the sender. If this is a new sender, please make a note of the external_id field, as that MUST be used in subsequent transaction creation calls that are from the same sender. Please see Sender for more details on how external_id functions.

recipient¶

The full details of the recipient.

may_cancel¶

Shows whether the payout to the recipient can be cancelled at this state or not.

external_id¶

The external ID of a transaction.

Funding transactions¶

When using our system to send funds to customers then usually you'll be using your internal account to fund these transactions. Please contact us so we can set up this internal account with us. If this is the case you'll need to explicitly fund transactions once they are created so we know that you are happy with the transaction to go forward.

Funding transactions can be done using the

POST /transactions/[GLOCURRENCY_TRANSACTION_ID]/fund

endpoint, with empty body.

Once the transaction is funded, we will immediately start trying to pay out the recipient.

Checking the state of the transaction¶

To manually check the state of the transaction, use the

GET /transactions/[GLOCURRENCY_TRANSACTION_ID]

endpoint, where the GLOCURRENCY_TRANSACTION_ID is the id of the transaction (and not the external id).

However to get real-time information on when a transaction's state changes please create webhooks for transaction state changes using the API, where we will send a response every time the transaction's state is changed.

Receiving error messages¶

The error message can be found inside the state_reason field on the transaction.

For example, on an error you will receive a webhook like this:

{
    "webhook": "ffede23b-7423-4f79-8561-785d5127d831",
    "event": "transaction.error",
    "data": {
        "state": "error",
        "state_reason": "Transaction recipient `phone_number` invalid.",
        "state_reason_details": {
            "code": "recipient_phone_number_invalid"
        }
        //
    }
}

For your application to get approved, it MUST support obtaining the error message from the transaction. It MUST also primarily use the webhook functionality to be notified of any errors, and only fall-back to using GET calls against the transaction occasionally.

Cancelling transactions¶

In case there are errors with the payout, or you want to revoke the cash pickup reference number for a cash transaction you can initiate a cancellation request. To do that call the

DELETE /transactions/[GLOCURRENCY_TRANSACTION_ID]

endpoint, where GLOCURRENCY_TRANSACTION_ID is the id of the transaction. If the transaction can be cancelled, this request, once processed, will cancel it. If the transaction was funded from an internal balance, it will then also be refunded.

You can cancel transactions where the may_cancel field of transaction is equal to true.

For your application to get approved it MUST support the cancellation of transaction.

Cancellation is an asynchoronous operation. You should wait for the transaction to change state to refunded before updating your system.