Architecture

Authentication

Every API call needs to be authenticated. See the authentication documentation for more details on the authentication process.

Status codes

Generally in our API there are three types of status codes used:

• A 200 status code means that the request was accepted, and there were no issues with it.
• A 422 status code is used whenever there was a validation error with the request. In case of validation errors, they are returned in the errors field.
• A 404 status code is used when the resource you are trying to fetch can not be found.

Rate limiting

When you make request to our API we return in response two headers: X-RateLimit-Limit and X-RateLimit-Remaining. If you exceed the limits you will receive 429 status code alongside with the X-RateLimit-Reset header, which contains a unix timestamp value of when you can safely retry your API call.

Webhooks

A webhook is a callback which enables our API to notify your system of new events concerning your transactions. Whenever objects in the Glo Currency API change state, we can optionally send the object details to a pre-registered webhook address. Webhooks can be created using the Glo Currency API.

Whenever possible we prefer using webhooks to listen on events (for example when a transaction has been paid out) instead of polling the status, and we expect implementations fully utilising webhooks.

Webhooks will always generate a POST request to the specified endpoint, and will also include Authorization-Nonce and Authorization-Signature authentication headers, so their validity can be verified on the receiver end.

You’ll need to reply to the endpoint call with a successful status code (e.g. 200), otherwise we’ll assume that the webhook was not delivered.

The structure of the body we send will follow the following template:

{
    "webhook_id": // the ID of the webhook
    "event_type": // the specific event
        // that was triggered
    "data": {
        // details of
        // the object on which
        // the event happened
    }
}

You can read more about webhooks in the managing webhooks documentation.

Senders

The senders model stores information about who sends the money for the transaction. Only senders that are KYC’d are allowed to pay in money.

If your site already does KYC on the senders, then let us know as we might waive the requirement to send us sender documents to ease the usage of our API. Please also check our KYC documentation for more info.

As with transactions, external IDs should be included for senders when a transaction is created. If this ID already exists in our system, any details sent along with the external ID are used to update the sender.

You can read more on senders in the transaction flow documentation.

Recipients

The recipient model stores information about who receives money from a transaction.

You can read more on recipients and how they work during transactions in the transaction flow documentation.

Transactions

The main model of the Glo Currency API is the Transaction, which store the flow for sending money from one Sender in a specific currency, to one Recipient in another currency.

The transaction model stores information about whether the money has already been paid out or not. Any issues during the payout process are also stored against the transaction.

You can read more on transactions in the transaction flow documentation.

Balances

Once we approve your request and set up your balance, you can use that balance to fund the payin part of the transaction. You can read more on funding transactions from your internal balance in the transaction flow documentation.

If you have a balance with us you can use the GET /accounts endpoint to get all balances or GET /accounts/[CURRENCY_NAME] to obtain balances for specific currency.