Telecoms Airtime

Endpoint: $GATEWAY_URL/ext/airtime

Tuti Tech Investment offers unique access to Sudan's airtime services. We are integrated to:

• Sudani (Sudatel)
• Zain
• MTN

Our integration includes the following:

• Airtime purchases via direct depositing to the beneficiaries' phone number
• Bill payments services

We also offer Utility services, CUSTOMS clearance, government payments and other services as well.

How it works

• Our API is RESTful and we follow very simple semantics that you can extend on other scenarios
• We process transactions in a queue, as we rely on external providers to telecoms
• Each business will hold a deposit account and will be able to make payments to their customers
• An API key will be given to the customer to be included in all transactions (will be shown in an example)
• The request fields will only include the phone number and the telecom type (e.g. MTN, Zain, Sudani).
• A customer will provide a webhook url for us so that we can notify the customer when the transaction is completed

Request parameters

Request headers: API-KEY

field	type
phone	string
type	string
amount	number
customer_name	string
customer_email	string

Request sample

{
  "phone": "0925343834",
  "type": "MTN",
  "amount": "100",
  "customer_name": "Mohamed Ahmed",
  "customer_email": ""
}```


### Response

#### Response samples

##### Success

Status code: 200

```json
{
  "result": "ok",
  "transaction_id": "123456789",
  "amount": "100",
  "status": "pending",
  "phone": "0925343834",
  "type": "MTN",
  "customer_name": "",
  "customer_email": ""}

Status code: 400

{
  "result": "error",
  "message": "Invalid phone number",
  "code": "invalid_phone_number"}

Status code: 401

{
  "result": "error",
  "message": "Invalid API key",
  "code": "invalid_api_key"}

Status code: 403

{
  "result": "error",
  "status": "declined",
  "transaction_id": "12345678",
  "message": "Insufficient funds",
  "code": "insufficient_funds"}

Gateway errors: 502

Gateway errors are special class of errors that we get from our gateway providers. These include the following: - Wrong phone number - Wrong amount - Disabled SIM card - and others

{
  "result": "error",
  "status": "gateway_error",
  "transaction_id": "12345678",
  "message": "Maximum amount exceeded",
  "code": "maximum_amount_exceeded"}

Transaction completion

Transaction completion API is used to inquire about the status of the transaction. Remember we are processing transactions in a queue, so each transation (initiation step) will almost always be pending. To further inquire about the status of a pending transactions, we will use the transaction_id that we provided to the customer.

You can also supplement us with a web hook url, and we will notify you when the transaction is completed.

URL: /ext/airtime/transaction/{transaction_id}

Request example

{
  "transaction_id": "12345678"
}

Response

The response will always be 200. The response will include the following:

1. Successful cases

{
  "result": "ok",
  "transaction_id": "12345678",
  "amount": "100",
  "status": "successful",
  "phone": "0925343834",
  "message": "Approved",
  "code": "approved",
  "type": "MTN",
  "customer_name": "",
  "customer_email": ""}

1. Failed transactions

{
  "result": "error",
  "transaction_id": "12345678",
  "amount": "100",
  "status": "failed",
  "phone": "0925343834",
  "type": "MTN",
  "message": "Maximum amount exceeded",
  "code": "maximum_amount_exceeded",
  "customer_name": "",
  "customer_email": ""}

Usage limitations

NB. usage limitations may subject to changes.

service	limit per day per phone number
MTN	10,000
Zain	10,000
Sudani	10,000