Rest API reference

The documentation below contains the technical interface for integrating the api for In App Purchase or by a third party partner. We offer two systems :

A payment with full api if you want to handle everything.
A payment with webhook for a quick integration.

Prerequisites

Root Url
https://75272b11ec.execute-api.eu-west-3.amazonaws.com/api

attention

For all requests, you have to add in the Header the token provided in the console.
Token should be the Value of the Key Authorization If you use the SDK the header value is set automatically

For example, a simple CURL request is like this:

Request in curl
curl --location 'https://75272b11ec.execute-api.eu-west-3.amazonaws.com/api/mpayment/agency/mobilemoneylist/country?countryCode=CI' \
--header 'Authorization: <TOKEN>'

Process summary

The api is async, so for each call you should have to check if the status changed.

astuce

Gara to introduce callback system Q2 2025.

Here in after the process:

Get the user country code. This part must be done in your application.
With the user country code, get the list of payment methods for this country. If the list is empty you, no payment methods is avaliable for this country.
Display payment methods to the user.
When user select the payment method, ask for a phone number. The app should add by default the indice in the input. For example, if country is Côte d’Ivoire, the input should display +225 by default.
Start cashout payment.
The mobile money system varies from country to country.
- Sometimes you receive a transaction url when your start the transaction. Open directly the url. The user has to fill some info or validate the payment.
Each 10s, check if the transaction status changed. After 3 min, stop checking. And tell the user that there is a time out. This system will be maintained after callback deployment to facilite verification and reconciliation

Process with API

Get the user country code and get the list of payment gateway of the user

You have first to know the user country code by providing a list in the game so the user can select his country.

Then you can get the country code for example SN for Senegal. This country code is used in this step to get the list of payment gateway available for Senegal for example.

Retrieves the list of mobile money providers available in a country

Request Url
Type: GET
Url : <ROOT_API>/mpayment/agency/paymentlist/country?countryCode=<COUNTRY_CODE>&tag=PAYMENT_LIST&isCashin=false

You will receive a list of mobile money available in this country. If no mobile money is available you will receive an empty list.

Note that :

serviceCode: is the unique code used to identify the mobile money
isCoushout: is true when you want to bill a user
isOtpRequired: is true when the mobile mobile asked for an OTP for example Orange in Côte D'Ivoire. In this case, the app should ask the user to provide the OTP

Request Url
[
    {
        "serviceCode": "SN_CASHIN_EMONEY_PART",
        "telecom": "EXPRESSO",
        "type": "MOBILE_MONEY",
        "isCashOut": false,
        "iconUrl": "https://d35dakp7lbtcub.cloudfront.net/mobile-money-icons/e-money.png",
        "isOtpRequired": false
    },
    {
        "serviceCode": "CASHINTIGOPART",
        "telecom": "FREE",
        "type": "MOBILE_MONEY",
        "isCashOut": false,
        "iconUrl": "https://d35dakp7lbtcub.cloudfront.net/mobile-money-icons/free.png",
        "isOtpRequired": false
    },
    {
        "serviceCode": "CASHINOMPART",
        "telecom": "ORANGE",
        "type": "MOBILE_MONEY",
        "isCashOut": false,
        "iconUrl": "https://d35dakp7lbtcub.cloudfront.net/mobile-money-icons/orange.png",
        "isOtpRequired": true
    }]

Start the transaction

Request Url
Type: POST
Url : <ROOT_API>/mpayment/appuser/game/cashoutv1

Body: All parameters here are required. If one is missing the system raises an exception.

Request body

{
    "action": "THIRD_PARTY_TRANSACTION",
    "amount": <FLOAT_OR_INTEGER>,
    "id": , <ID_OF_THE_GAME>,
    "paymentMethodType": "MOBILE_MONEY",
    "phoneNumber": "<PHONE_NUMBER>", 
    "serviceCode": "<SERVICE_CODE>",
    "countryCode" : "<COUNTRY_CODE>",
    "type": "API"            
 }

action: THIRD_PARTY_TRANSACTION if you are a platform or app and IN_APP_PURCHASE for IAP in game.
amount: The amount to be debited.
id: The identifier from the project/game created in Gara Console.
phoneNumber: The user phonumber for the payment
serviceCode: The service code provided by Gara when retrieving the list of available payments.
countryCode: The user country code, for example SN for Senegal.
returnUrl: [Optional] the url of the website we redirect the user if payment succeed or failed

Transaction response

Once the transaction has been launched, it can be in 3 states:

PAYMENT_WAITING_FOR_USER_VALIDATION : The transaction has been successfully initiated and is pending from the user
FAILED: The transaction failed.
Once the transaction is initiated (Waiting for validation or failed), you will receive a body with at least the following information Body: The most important information is status.

Request body
{
  "transactionId": "7c92abba-0504-48ff-884a-fc27519a7a9e",
  "providerTransactionId": null,
  "amount": 51,
  "fees": 0,
  "total": 0,
  "currency": {
    "code": "XAF",
    "name": "FCFA (CEMAC)",
    "symbole": "FCFA",
    "usdunit": 0.00180716
  },
  "garaTransactionDate": "2025-01-22T23:52:51.726+0000",
  "providerTransactionDate": "2025-01-22T23:52:53.069+0000",
  "isCashIn": false,
  "action": "IN_APP_PURCHASE",
  "status": "PAYMENT_WAITING_FOR_USER_VALIDATION",
  "providerInfo": {
    "id": 454,
    "phoneNumber": "+22997672407",
    "userCountry": null,
    "paymentMethod": {
    "serviceCode": "CG_AIRTEL_MM",
    "telecom": "AIRTEL",
    "type": "MOBILE_MONEY",
    "isCashOut": true,
    "iconUrl": "https://d35dakp7lbtcub.cloudfront.net/mobile-money-icons/airtel.png",
    "isOtpRequired": false,
    "isPrimary": true
  }
}

attention

When the response contains paymentUrl with an url in it, please redirect the user to this url automatically by opening the browser so he can validate the payment

Callback

Webhook is not yet available. You have to get the status of the transaction to make sure it have been updated after validation

Request in curl
curl --location 'https://75272b11ec.execute-api.eu-west-3.amazonaws.com/api/mpayment/appuser/game/{transactionId}' \
--header 'Authorization: <TOKEN>'

You will get a transaction response. You should check the status at regular intervals. By default is PAYMENT_WAITING_FOR_USER_VALIDATION. When SUCCESSFUL, your transaction is validated successfully.
If, after 3 min, the status is still at PAYMENT_WAITING_FOR_USER_VALIDATION , you must trigger a time out.

Prerequisites​

Process summary​

Process with API​

Get the user country code and get the list of payment gateway of the user​

Retrieves the list of mobile money providers available in a country​

Start the transaction​

Transaction response​

Callback​