# Welcome The official API documentation for Settle Africa. ## Coverage The API documentation applies and covers all African countries. {% hint style="info" %} The API does not applies to Personal Accounts. {% endhint %} ## Authentication The API authenticates in a very simple straightforward manner: {% content-ref url="/pages/JEfK9PZWrMisOzfOAkH7" %} [Authentication](/authentication) {% endcontent-ref %} ## Transfers (In & Out) {% hint style="info" %} **Note :** Settle does not have any wallets/holding of funds capability. Funds are debited from payment instrument and credited to the receiving end instantly. {% endhint %} {% content-ref url="/pages/rkmzAu4xeBDyLCPSkv27" %} [Transfers](/transfers/sending) {% endcontent-ref %} ## Data & Details Before processing transactions, certain data needs to be queried and appended to the requests. * Banks & Mobile Money Providers * ID verification (National ID, Driver's License) * Countries and Regions * Rates {% content-ref url="/pages/qaz4LtrTOGoUbkIHemJN" %} [Data & Details](/data-and-details/banks-and-mobile-money) {% endcontent-ref %} # Authentication {% hint style="info" %} **Good to know:** All requests require authentication. {% endhint %} ## Get your API keys Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. You can generate an API key from your Dashboard at any time. ## Make the Authentication request Send an authentication request to the login endpoint. This will create a `token, id and expiry` which will form the headers of any request for the time until the expiry time passed. {% hint style="info" %} **Endpoint:** {% endhint %} Take a look at how you might call this method using `Http`: {% tabs %} {% tab title="Request" %} ```json POST http://settle.africa/login HTTP/1.1 Content-Type: application/json { "id":"1234567890", "password":"jumairah" } ``` {% endtab %} {% tab title="Success" %} ```json { "status": "success", "data": { "token":"tegdghh66353l", "id":"5563678883", "expiry":"29/11/2024 12:23:23" }, "message": "Login Successfully", "code": 0 } ``` {% endtab %} {% tab title="Failed" %} ```json { "status": "failed", "data": {}, "message": "User does not exist", "code": 1 } ``` {% endtab %} {% endtabs %} Subsequent requests to the API will contain the Authenticated headers as follows: ``` id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` Authenticated Requests will look like: ``` GET http://settle.africa/profile HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 Content-Type: application/json { } ``` # Sending This explains how to send transfers using the API {% hint style="warning" %} Before initiating transfer request, ensure the payment instrument to be debited is already configured on the dashboard. {% endhint %} Settle enables near instant sending of funds to anywhere in Africa. Both to Banks and Mobile Money. {% hint style="info" %} **Endpoint:** {% endhint %} {% tabs %} {% tab title="Request" %} ``` POST https://settle.africa/transfer HTTP/1.1 Content-Type: application/json id: salem token: pXVCJ9.eyJzdWIiOiJVZ2xpZnkzNjUiLCJzaWQiOiJ1Z2 expiry: 29/01/2024 06:12:12 { "Source":"308", //The originating country id. Get Country Id from /countries "Destination":"102", //The destination country id "Amount":200, //In Destination Currency "Fi":"302", //The id of the receiving bank/mobile money "Note":"Buy Ice Cream", //Narration "AccountNo":"1212", //The account number of the receiver "Name":"Agaba", //The full name of the receiver if account validation absent "Phone":"070982882", //The receiver's phone number } ``` {% endtab %} {% tab title="Response" %} ``` { "status": "success", "data": { "id": "61A69" }, "code": 0, "fetched": "13/11/2023 02:38:44", "message": "Transfer posted successfully." } ``` {% endtab %} {% endtabs %} # Receiving Settle can be used for collection by Businesses anywhere within Africa. {% hint style="info" %} Settle does not have wallets or any means of holding funds. All payments are reconciled immediately they become available. {% endhint %} # Verification/Single Transfer A Transaction can be fetched to validate/verify its status or recall their details. {% hint style="info" %} **Endpoint:** {% endhint %} All that is required is a request with the transfer/transaction Id. {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/transaction/{id} HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "Success", "code": "0", "message": "Transaction Fetched", "data": { "id": "65", "amount": 299, "receiver": "Adil Karo", "Date": "29/11/2029 08:00pm", "Status":"Finished", "Bank":"Maghrib Bank", "destination": "Egypt" } } ``` {% endtab %} {% endtabs %} # Transactions History Transactions can be fetched to validate/verify their status or recall their details. {% hint style="info" %} **Endpoint:** {% endhint %} All that is required is a request with the transfer/transaction Id. {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/transaction/{id} HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "Success", "code": "0", "message": "Transaction Fetched", "data": { "id": "65", "amount": 299, "receiver": "Adil Karo", "Date": "29/11/2029 08:00pm", "Status":"Finished", "Bank":"Maghrib Bank", "destination": "Egypt" } } ``` {% endtab %} {% endtabs %} # Fees & Speed Estimate Estimates Discover the charges and time a transaction can take to be completed before it happens. {% hint style="info" %} **Endpoint:** {% endhint %} * Source: Id of Sending Country * Destination: Id of Receiver's country * Amount: The amount to be sent {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/rates/{Source}/{Destination}/{Amount} HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "success", "data": { "rate": 195.85088724172127, //In destination currency "speed":2000, //In seconds "fees":2300 //In source currency }, "code": 0, "fetched": "13/11/2023 02:24:50", "message": "The rates is in the destination currency." } ``` {% endtab %} {% endtabs %} # Banks & Mobile Money List of Financial Institutions This API fetches the list of financial institutions Settle is capable of transacting to in all the countries. {% hint style="info" %} **Endpoint:** {% endhint %} * CountryId: The Id of the receiving Country. {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/fis/{countryId} HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "Success", "code": "0", "message": "Banks/MoMo Fetched", "data": [ { "id": "65", "name": "Langata MFB", "Logo": "https://settle.africa/65.png", "Charges": 250, "Currency": "NGN" }, ... ] } ``` {% endtab %} {% endtabs %} # Countries List of countries This API fetches all the countries Settle is available for sending and receiving of transfers. {% hint style="info" %} **Endpoint:** {% endhint %} {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/countries HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "Success", "code": 0, "message": "Countries List", "data": [ { "id": "65", "name": "Egypt", "phone": "20", "iso": "EG", "rate": 3.6783763469230766 }, ... ] } ``` {% endtab %} {% endtabs %} # Resolve Account Names Get Receiver Name This API tries to fetch the receiver's account name by simply supplying their account number. {% hint style="info" %} **Endpoint:** {% endhint %} Where: * **fi:** The financial institution(Bank/Mobile money) id of the receiver. * **accountnumber:** The account number/username of the receiver on the Financial institution. {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/fisit/{fi}/{accountnumber} HTTP/1.1 id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "Success", "code": "0", "message": "Name found", "data": { "name": "Thembeka Emeka", } } ``` {% endtab %} {% endtabs %} # Exchange Rates Near Real-time Rates This endpoint fetches the most recent exchange rates between two currencies of countries within Africa. {% hint style="info" %} **Endpoint:** {% endhint %} * Source: Id of Sending Country * Destination: Id of Receiver's country {% tabs %} {% tab title="Request" %} ``` GET https://settle.africa/rates/{Source}/{Destination} id: 5563678883 token: tegdghh66353l expiry: 29/11/2024 12:23:23 ``` {% endtab %} {% tab title="Response" %} ``` { "status": "success", "data": { "rate": 195.85088724172127 }, "code": 0, "fetched": "13/11/2023 02:24:50", "message": "The rates is in the destination currency." } ``` {% endtab %} {% endtabs %}