zendit API Specification v1.0.0

Overview

Our cloud-based Prepaid as a Service platform is now even more accessible with our reliable and efficient REST API. Our API provides seamless access to catalogs, balance information, and transactions for our:

International Mobile Top Up Products
International Mobile Bundles
Digital Gift Cards
Utility Payments
eSIM

Our platform is built with industry-standard security protocols and is designed to integrate seamlessly with your existing systems. We are committed to providing top-notch support, so please don’t hesitate to reach out to our experienced zendit support team with any questions or support needs..

Zendit University

As a supplement to this API guide, head over to Zendit University to understand the features of the system, how transaction flows work and how to get details from the catalog for your integration.

Environments

Testing and development before going live with your product or service is crucial. That’s why we provide easy access to both our test bed and production environments through our gateway.

When you register for zendit, you’ll be provided with a test mode API key to use for simulated transactions. These transactions will not transfer real value, but will deduct from your test bed wallet. No credit card is required for this environment, and you can manage your wallet balance through our administration console.

When you’re ready to switch to production mode and start processing real transactions, you’ll need to fund your prepay wallet with real value. This will allow you to process transactions using your production key.

For more information on using our testbed environment to simulate different responses, refer to our comprehensive test mode environment documentation.

Please don’t hesitate to contact our support team if you have any questions or need assistance.

API Security

When you sign up for our platform, you’ll be given access to your test mode key for testing your integration with our API. To send requests to an API endpoint, please use the Authentication header and include your API key as follows:

Authentication: Bearer YOUR_API_KEY

This will authenticate your requests and allow our API to process them securely. If you’re ready to switch to production mode and start processing real transactions, you’ll need to use your production key instead.

For more information about our security, refer to our security guide.

Transactions

Transparency and visibility are most important when it comes to processing transactions. That’s why we process transactions asynchronously and provide detailed status updates throughout the process.

When you send a transaction through our platform, we first validate the parameters of the transaction and then return the transaction ID in the response, along with any error messages if the transaction cannot be processed. From there, the transaction enters the zendit ecosystem and begins to move through our system.

To check on the status of your transaction, you can periodically poll the transaction using the transaction ID. Our system provides detailed updates on the transaction’s status as it moves through the system, including updates on receipt, wallet authorization, offer fulfillment, and completion.

Once the transaction is complete, you’ll receive a final status update that reports whether it was successful or encountered any errors during processing. Additionally, each transaction contains a history log that shows all status updates throughout the transaction process, providing you with a comprehensive view of the transaction’s journey through our platform.

To understand more about how to work with transactions, refer to our transaction guide.

Transaction ID

Providing our users with maximum flexibility when it comes to tracking their transactions is important. That’s why we don’t automatically generate transaction IDs – instead, you can supply any alphanumeric string of your choosing (such as an autonumber or a GUID) to track your transaction in our system.

To ensure that your transaction is processed correctly, you must supply the ID you will use to track the transaction status with each transaction request. Please note that transaction IDs are unique per zendit account and environment, so you can use the same transaction ID in both your test environment and production environment (once per environment).

If you’re using an autonumber scheme and have test and production environments, there’s no need to worry about collisions of IDs between the two environments. We understand the importance of keeping your test and production environments separate, and our system is designed to handle this seamlessly.

Queue and Retry

We strive to ensure that your transactions are processed reliably and efficiently. While most transactions are processed in real time, occasional recoverable errors can occur when a product provider in the ecosystem encounters an issue.

To address this, our API automatically sets a 15-minute timeout on the transaction and then retries it. If there is an extended problem with a product provider, the system will continue to retry the transaction every 15 minutes until it either completes successfully or fails after 24 hours.

If you would prefer not to use the queue and retry feature, you may turn the feature off in the client console on the API settings page.

For more information refer to the Queue and Retry guide.

Digital Gift Card and Utility Payment Required Felds

Digital Gift Cards and Utility Payments based on the brand requirements may require more information than just the recipient’s phone number. For the specific requirements of a Digital Gift Card or Utility Payment offer the list of fields required will be provided in the catalog. You can find all the possible fields that a these offers may require on the required fields page.

Error Messages

For a detailed list of possible error statuses, please see Error Message Guide

To understand the error structures in the API, please see Error Messages on API

Transaction Log Structure

zendit Transactions contain a log of activity as the transaction progresses through the system. You can find this on any transaction under the “log” structure. The log will give more detail about the transaction from when it was submitted, when it was authorized against the wallet, when it was submitted for fulfillment and any errors that were encountered while processing will be noted at the stage where the transaction failed.

Searching using createdAt date on transactions

When using the createdAt date on the transaction search endpoints (/topup/purchases, /transactions and /voucher/purchases) dates use the RFC 3339 format in UTC Timezone (e.g. 2023-02-15T03:15:22Z)

When searching with createdAt there are a few prefixes you can add to the time in order to search around the timestamp supplied. The search formats are as follows:

Format	Description	Example
No prefix	Search for an exact date/time	2023-02-15T03:15:22Z will search for transactions that match February 15, 2023 at 3:15 and 22 seconds in UTC timezone
lt	Search for a date/time that is earlier than the supplied value	lt2023-02-15T03:15:22Z will search for transactions that are before February 15, 2023 at 3:15 and 22 seconds in UTC timezone
lte	Search for a date/time that is equal to the supplied value and earlier	lte2023-02-15T03:15:22Z will search for transactions that are equal February 15, 2023 at 3:15 and 22 seconds in UTC timezone and transactions that are earlier
gt	Search for a date/time that is later than the supplied value	gt2023-02-15T03:15:22Z will search for transactions that are after February 15, 2023 at 3:15 and 22 seconds in UTC timezone
gte	Search for a date/time that is equal to the supplied value and later	gte2023-02-15T03:15:22Z will search for transactions that are equal to February 15, 2023 at 3:15 and 22 seconds in UTC timezone and transactions that are later

zendit – Website
Send email to zendit

Servers

https://api.zendit.io/v1/

Try it on swagger

https://test-api.zendit.io/v1/

Try it on swagger

SDKs are rolling out! Can’t wait?

Go to the Swagger for our API and download the API Spec in JSON to use Swagger to generate a client

Account Information

GET

/balance

Check your account balance

Query Parameters

None

Responses

Type: application/json

Status OK

{
  "availableBalance": 0,
  "currency": "string"
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

eSIM

GET
/esim/offers
Get the catalog of eSIM offers

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Required Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Required Minimum 0
brand	String Filter for a specific Brand – currently fixed as “eSIM”
country	String Filter for a specific Country (2 letter ISO code)
subType	String Subtype of offers to return Values: eSIM
regions	String Region of offers to return Values: Regions Values

Response

Status OK

 {
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "cost": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "country": "string",
      "createdAt": "string",
      "dataGB": 0,
      "durationDays": 0,
      "enabled": true,
      "notes": "string",
      "offerId": "string",
      "price": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "margin": 0,
        "max": 0,
        "min": 0,
        "suggestedFixed": 0,
        "suggestedFx": 0
      },
      "priceType": "string",
      "productType": "string",
      "regions": [
        "string"
      ],
      "shortNotes": "string",
      "subTypes": [
        "string"
      ],
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/esim/offers/{offerId}
Get a specific eSIM catalog offer

Query Parameters

Name	Description
offerId	String Offer ID to retreive from the catalog Required

Response

Status OK

 {
  "brand": "string",
  "cost": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "max": 0,
    "min": 0
  },
  "country": "string",
  "createdAt": "string",
  "dataGB": 0,
  "durationDays": 0,
  "enabled": true,
  "notes": "string",
  "offerId": "string",
  "price": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "margin": 0,
    "max": 0,
    "min": 0,
    "suggestedFixed": 0,
    "suggestedFx": 0
  },
  "priceType": "string",
  "productType": "string",
  "regions": [
    "string"
  ],
  "shortNotes": "string",
  "subTypes": [
    "string"
  ],
  "updatedAt": "string"
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/esim/purchases
Get a list of eSIM purchases

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Default 50 Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Default 0 Minimum 0
createdAt	String Filter for searching by date, see the date search information in the overview section
status	String Filter for searching the status of a transaction) Uses values from status enum.

Response

Status OK

 {
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "confirmation": {
        "activationCode": "string",
        "externalReferenceId": "string",
        "iccid": "string",
        "redemptionInstructions": "string",
        "smdpAddress": "string"
      },
      "cost": 0,
      "costCurrency": "string",
      "country": "string",
      "createdAt": "string",
      "dataGB": 0,
      "durationDays": 0,
      "error": {
        "code": "string",
        "description": "string",
        "message": "string"
      },
      "log": [
        {
          "dateTime": "string",
          "status": "string",
          "statusMessage": "string"
        }
      ],
      "notes": "string",
      "offerId": "string",
      "price": 0,
      "priceCurrency": "string",
      "priceType": "string",
      "productType": "string",
      "regions": [
        "string"
      ],
      "shortNotes": "string",
      "status": "string",
      "subTypes": [
        "string"
      ],
      "transactionId": "string",
      "updatedAt": "string",
      "value": {
        "type": "COST",
        "value": 0
      }
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

POST
/esim/purchases
Purchase an eSIM offer

Parameters

POST Data

{
  "offerId": "string",
  "transactionId": "string"
}

Name	Description
offerId	String Catalog Offer ID for a Mobile Top Up, Mobile Bundle or Mobile Data Required
transactionId	String Transaction ID for tracking the transaction in Zendit Required

Response

Status OK

 {
  "status": "string",
  "transactionId": "string"
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/esim/purchases/{transactionId}
Get a specific transaction for an eSIM purchase

Query Parameters

Name	Description
transactionId	String Transaction ID for tracking the transaction in Zendit Required

Response

Status OK

{
  "brand": "string",
  "confirmation": {
    "activationCode": "string",
    "externalReferenceId": "string",
    "iccid": "string",
    "redemptionInstructions": "string",
    "smdpAddress": "string"
  },
  "cost": 0,
  "costCurrency": "string",
  "country": "string",
  "createdAt": "string",
  "dataGB": 0,
  "durationDays": 0,
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "string",
      "statusMessage": "string"
    }
  ],
  "notes": "string",
  "offerId": "string",
  "price": 0,
  "priceCurrency": "string",
  "priceType": "string",
  "productType": "string",
  "regions": [
    "string"
  ],
  "shortNotes": "string",
  "status": "string",
  "subTypes": [
    "string"
  ],
  "transactionId": "string",
  "updatedAt": "string",
  "value": {
    "type": "COST",
    "value": 0
  }
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/esim/purchases/{transactionId}/qrcode
Get the QR Code for an eSIM purchase

Query Parameters

Name	Description
transactionId	String Transaction ID for tracking the transaction in Zendit Required

Response

Status OK

Response Type: image/png

string

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

International Mobile Top Up and International Mobile Bundles

GET
/topups/offers
Get the catalog of International Mobile Top Up and Mobile Bundle offer

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Required Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Required Minimum 0
brand	String Filter for a specific Brand
country	String Filter for a specific Country (2 letter ISO code)
subType	String Subtype of offers to return Values: Uses values from MTU Subtype.

Response

Status OK

 {
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "cost": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "country": "string",
      "createdAt": "string",
      "enabled": true,
      "notes": "string",
      "offerId": "string",
      "price": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "margin": 0,
        "max": 0,
        "min": 0,
        "suggestedFixed": 0,
        "suggestedFx": 0
      },
      "priceType": "string",
      "productType": "string",
      "send": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "shortNotes": "string",
      "subTypes": [
        "string"
      ],
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/topups/offers/{offerId}
Get a specific International Mobile Top Up or Mobile Bundle catalog offer

Query Parameters

Name	Description
offerId	String Offer ID to retreive from the catalog Required

Responses

Status OK

 {
  "brand": "string",
  "cost": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "max": 0,
    "min": 0
  },
  "country": "string",
  "createdAt": "string",
  "enabled": true,
  "notes": "string",
  "offerId": "string",
  "price": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "margin": 0,
    "max": 0,
    "min": 0,
    "suggestedFixed": 0,
    "suggestedFx": 0
  },
  "priceType": "string",
  "productType": "string",
  "send": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "max": 0,
    "min": 0
  },
  "shortNotes": "string",
  "subTypes": [
    "string"
  ],
  "updatedAt": "string"
}

Bad Request

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/topups/purchases
Get a list of International Mobile Top Up, Mobile Bundle and Mobile Data purchases

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Default 50 Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Default 0 Minimum 0
createdAt	String Filter for searching by date, see the date search information in the overview section
status	String Filter for searching the status of a transaction) Uses values from status enum.

Responses

Status OK

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "confirmation": {
        "confirmationNumber": "string",
        "externalReferenceId": "string",
        "transactionTime": "string"
      },
      "cost": 0,
      "costCurrency": "string",
      "country": "string",
      "createdAt": "string",
      "error": {
        "code": "string",
        "description": "string",
        "message": "string"
      },
      "log": [
        {
          "dateTime": "string",
          "status": "string",
          "statusMessage": "string"
        }
      ],
      "notes": "string",
      "offerId": "string",
      "price": 0,
      "priceCurrency": "string",
      "priceType": "string",
      "productType": "string",
      "recipientPhoneNumber": "string",
      "send": 0,
      "sendCurrency": "string",
      "sender": {
        "country": "string",
        "phoneNumber": "string"
      },
      "shortNotes": "string",
      "status": "string",
      "subTypes": [
        "string"
      ],
      "transactionId": "string",
      "updatedAt": "string",
      "value": {
        "type": "COST",
        "value": 0
      }
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

POST
/topups/purchases
Purchase an International Mobile Top Up or Mobile Bundle offer

Parameters

Post Data

{
  "offerId": "string",
  "recipientPhoneNumber": "string",
  "sender": {
    "country": "string",
    "phoneNumber": "string"
  },
  "transactionId": "string",
  "value": {
    "type": "COST",
    "value": 0
  }
}

Data Values

Field	Description
offerId	String Catalog Offer ID for a Mobile Top Up, Mobile Bundle or Mobile Data Required
recipientPhoneNumber	String Phone number for recipient in e.164 format (+[country code][phone number]) Required
sender.country	String 2 letter ISO country code of the sender Optional
sender.phoneNumber	String Phone number for the sender in e.164 format (+[country code][phone number]) Optional
transactionId	String Transaction ID for tracking the transaction in Zendit Required
value.type	String Type of value for calculating value delivered See Price Types Required – Open Range Offers Only, Omit for Fixed Offers
value.value	Number Value in cents to send for the top up (e.g. $1.00 = 100) Required – Open Range Offers Only, Omit for Fixed Offers

Responses

Status OK

 {
  "status": "string",
  "transactionId": "string"
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/topups/purchases/{transactionId}
Get an International Mobile Top Up or Mobile Bundle purchases transaction by Id

Query Parameters

Name	Description
transactionId	String Transaction Id for Transaction Required

Responses

Status OK

 {
  "brand": "string",
  "confirmation": {
    "confirmationNumber": "string",
    "externalReferenceId": "string",
    "transactionTime": "string"
  },
  "cost": 0,
  "costCurrency": "string",
  "country": "string",
  "createdAt": "string",
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "string",
      "statusMessage": "string"
    }
  ],
  "notes": "string",
  "offerId": "string",
  "price": 0,
  "priceCurrency": "string",
  "priceType": "string",
  "productType": "string",
  "recipientPhoneNumber": "string",
  "send": 0,
  "sendCurrency": "string",
  "sender": {
    "country": "string",
    "phoneNumber": "string"
  },
  "shortNotes": "string",
  "status": "string",
  "subTypes": [
    "string"
  ],
  "transactionId": "string",
  "updatedAt": "string",
  "value": {
    "type": "COST",
    "value": 0
  }
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Transaction Status Information

GET
/transactions
Get a list of transactions of all types with the common transaction model

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Default 50 Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Default 0 Minimum 0
createdAt	String Filter for searching by date, see the date search information in the overview section
productType	String Filter for searching the status of a transaction) Uses values from product type.
status	String Filter for searching the status of a transaction) Uses values from status enum.
type	String Filter for searching the status of a transaction) Uses values from transaction enum.

Responses

Status OK

 {
  "limit": 0,
  "list": [
    {
      "amount": 0,
      "createdAt": "string",
      "currency": "string",
      "error": {
        "code": "string",
        "description": "string",
        "message": "string"
      },
      "log": [
        {
          "dateTime": "string",
          "status": "string",
          "statusMessage": "string"
        }
      ],
      "productType": "string",
      "status": "string",
      "transactionId": "string",
      "type": "string",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/transactions/{transactionId}
Get a specitic transactions of any type with the common transaction model

Query Parameters

Name	Description
transactionId	String Transaction Id for Transaction Required

Responses

Status OK

 {
  "amount": 0,
  "createdAt": "string",
  "currency": "string",
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "string",
      "statusMessage": "string"
    }
  ],
  "productType": "string",
  "status": "string",
  "transactionId": "string",
  "type": "string",
  "updatedAt": "string"
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Digital Gift Cards and Utility Payments

GET
/vouchers/offers
Get the catalog of Digital Gift Card and Utility Payment offers

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Default 50 Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Default 0 Minimum 0
brand	String Filter for a specific Brand
country	String Filter for a specific Country (2 letter ISO code)
subType	String Subtype of offers to return Values: Subtypes vary for Digital Gift Cards and Utility Payments, check the catalog for subtypes

Responses

Status OK

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "cost": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "country": "string",
      "createdAt": "string",
      "enabled": true,
      "notes": "string",
      "offerId": "string",
      "price": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "margin": 0,
        "max": 0,
        "min": 0,
        "suggestedFixed": 0,
        "suggestedFx": 0
      },
      "priceType": "string",
      "productType": "string",
      "requiredFields": [
        "string"
      ],
      "send": {
        "currency": "string",
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "shortNotes": "string",
      "subTypes": [
        "string"
      ],
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/vouchers/offers/{offerId}
Get a specific Digital Gift Card or Utilty Payment catalog offer

Query Parameters

Name	Description
offerId	String Offer ID to retreive from the catalog Required

Responses

Status OK

{
  "brand": "string",
  "cost": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "max": 0,
    "min": 0
  },
  "country": "string",
  "createdAt": "string",
  "enabled": true,
  "notes": "string",
  "offerId": "string",
  "price": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "margin": 0,
    "max": 0,
    "min": 0,
    "suggestedFixed": 0,
    "suggestedFx": 0
  },
  "priceType": "string",
  "productType": "string",
  "requiredFields": [
    "string"
  ],
  "send": {
    "currency": "string",
    "fixed": 0,
    "fx": 0,
    "max": 0,
    "min": 0
  },
  "shortNotes": "string",
  "subTypes": [
    "string"
  ],
  "updatedAt": "string"
}

Bad Request

{
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

GET
/vouchers/purchases
Get a list of Digital Gift Card and Utility Payment purchases

Query Parameters

Name	Description
_limit	Integer Limit of the number of items to return for pagination Default 50 Minimum 1
_offset	Integer Number of items to skip in returned results for pagination Default 0 Minimum 0
createdAt	String Filter for searching by date, see the date search information in the overview section
status	String Filter for searching the status of a transaction) Uses values from status enum.

Responses

Status OK

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "confirmation": {
        "confirmationNumber": "string",
        "externalReferenceId": "string",
        "transactionTime": "string"
      },
      "cost": 0,
      "costCurrency": "string",
      "country": "string",
      "createdAt": "string",
      "error": {
        "code": "string",
        "description": "string",
        "message": "string"
      },
      "fields": [
        {
          "key": "string",
          "value": "string"
        }
      ],
      "log": [
        {
          "dateTime": "string",
          "status": "string",
          "statusMessage": "string"
        }
      ],
      "notes": "string",
      "offerId": "string",
      "price": 0,
      "priceCurrency": "string",
      "priceType": "string",
      "productType": "string",
      "receipt": {
        "currency": "string",
        "epin": "string",
        "expiresAt": "string",
        "instructions": "string",
        "notes": "string",
        "recipientCustomerServiceNumber": "string",
        "send": 0,
        "senderCustomerServiceNumber": "string",
        "terms": "string"
      },
      "send": 0,
      "sendCurrency": "string",
      "shortNotes": "string",
      "status": "string",
      "subTypes": [
        "string"
      ],
      "transactionId": "string",
      "updatedAt": "string",
      "value": {
        "type": "COST",
        "value": 0
      }
    }
  ],
  "offset": 0,
  "total": 0
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

POST
/vouchers/purchases
Purchase a Digital Gift Card or Utility Payment offer

Parameters

Post Data

{
  "fields": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "offerId": "string",
  "transactionId": "string",
  "value": {
    "type": "COST",
    "value": 0
  }
}

Post Data

Name	Description
offerId	String Offer ID from the catalog to purchase Required
transactionId	String Transaction ID from the integrating client Required
fields[]	Array Array of values for required fields as set on the product in the catalog Required for offers with Required Fields
fields[].key	String Field name that corresponds to the value
fields[].value	String Field value that corresponds to the key
value.type	String Type of value for calculating value delivered See Price Types Required – Open Range Offers Only, Omit for Fixed Offers
value.value	Number Value in cents to send for the top up (e.g. $1.00 = 100) Required – Open Range Offers Only, Omit for Fixed Offers

Responses

Status OK

{ 
     status:	string 
         Status of transaction acceptance 
     transactionId:	string 
         ID of transaction in post data sent to zendit 
 }

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

POST
/vouchers/purchases/{transactionId}
Get a specific voucher transaction

Query Parameters

Name	Description
transactionId	String Transaction Id for Transaction Required

Responses

Status OK

{
  "brand": "string",
  "confirmation": {
    "confirmationNumber": "string",
    "externalReferenceId": "string",
    "transactionTime": "string"
  },
  "cost": 0,
  "costCurrency": "string",
  "country": "string",
  "createdAt": "string",
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "fields": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "log": [
    {
      "dateTime": "string",
      "status": "string",
      "statusMessage": "string"
    }
  ],
  "notes": "string",
  "offerId": "string",
  "price": 0,
  "priceCurrency": "string",
  "priceType": "string",
  "productType": "string",
  "receipt": {
    "currency": "string",
    "epin": "string",
    "expiresAt": "string",
    "instructions": "string",
    "notes": "string",
    "recipientCustomerServiceNumber": "string",
    "send": 0,
    "senderCustomerServiceNumber": "string",
    "terms": "string"
  },
  "send": 0,
  "sendCurrency": "string",
  "shortNotes": "string",
  "status": "string",
  "subTypes": [
    "string"
  ],
  "transactionId": "string",
  "updatedAt": "string",
  "value": {
    "type": "COST",
    "value": 0
  }
}

Bad Request

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Unauthorized: API Token Missing or Unrecognized

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Forbidden: Request from unrecognized IP

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Internal Server Error

 {
  "errorCode": "string",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "message": "string"
}

Error Structure on API

Field	Description
errorCode	String Code to identify the type of error
fields	Array of additionalProp String values Additional information about problematic fields in an error
message	String Message describing the error

ENUM Values for Requests

Zendit uses several ENUM string values for searches and responses. Refer to the following values for parameter values and their use in Zendit.

Transaction Status

Status	Description
ACCEPTED	Transaction was accepted for processing
PENDING	Transaction is awaiting processing by Zendit
AUTHORIZED	Transaction has successfully been authorized against the Zendit Wallet
IN_PROGRESS	Transaction is in progress for fulfillment with the provider
DONE	Transaction has successfully completed
FAIL	The transaction has failed to be fulfilled. Check the error reason and the log within the transaction to understand which step it failed and why

Price Type

Value	Description
FIXED	Offer type uses a fixed cost, price, and value delivered
RANGE	Offer provides a range of value between the min and max values and cost, price, and value are based on the FX Rates for the offer

Product Type

Value	Description
TOPUP	Transaction is a Mobile Top Up, Mobile Bundle, or Mobile Data offer. Check the subtype for detail.
VOUCHER	Transaction is a Digital Gift Card or Utility Payment offer. Check the subtype for detail.
RECHARGE_SANDBOX	Transaction is a wallet recharge on the test mode environment.
RECHARGE_WITH_CREDIT_CARD	Transaction is a wallet recharge in the production environment using a credit card.

Transaction Type

Value	Description
CREDIT	Transaction added value to the wallet through a recharge or balance credit
DEBIT	Transaction subtracted value from the wallet through a product purchase or a balance adjustment

Value Type

Value	Description
COST	Customer Price and Value delivered calculated using the Zendit client’s cost FX
PRICE	Zendit client Cost and Value delivered calculated using the customer’s price FX
ZEND	Zendit client cost and customer’s price calculated using the cost FX and price FX for a specific value to be delivered in the destination currency

MTU Subtypes

Value	Description
Mobile Top Up	Mobile Airtime products
Mobile Bundle	Mobile Bundle products
Mobile Data	Mobile Data products

Regions – String Values

Global

Africa

Asia

Caribbean

Central America

Eastern Europe

Western Europe

North America

Oceania

South America

South Asia

Southeast Asia

Middle East and North Africa

Menu

zendit API Specification v1.0.0

Overview

Zendit University

Environments

API Security

Transactions

Transaction ID

Queue and Retry

Digital Gift Card and Utility Payment Required Felds

Error Messages

Transaction Log Structure

Searching using createdAt date on transactions

Servers

Account Information

GET

Query Parameters

Responses

eSIM

Query Parameters

Response

Query Parameters

Response

Query Parameters

Response

Parameters

Response

Query Parameters

Response

Query Parameters

Response

International Mobile Top Up and International Mobile Bundles

Query Parameters

Response

Query Parameters

Responses

Query Parameters

Responses

Parameters

Data Values

Responses

Query Parameters

Responses

Transaction Status Information

Query Parameters

Responses

Query Parameters

Responses

Digital Gift Cards and Utility Payments

Query Parameters

Responses

Query Parameters

Responses

Query Parameters

Responses

Parameters

Post Data

Responses

Query Parameters

Responses

Error Structure on API

ENUM Values for Requests

Transaction Status

Price Type

Product Type

Transaction Type

Value Type

MTU Subtypes

Regions – String Values