zendit employs an asynchronous methodology to accomplish transactions, ensuring efficient processing. This guide furnishes comprehensive instructions for initiating a transaction and obtaining the corresponding outcomes.
In zendit, a transaction serves as the fundamental process for satisfying a customer’s product purchase. At present, zendit offers support for two transaction types: top-ups and vouchers. For fulfilling mobile top-ups, mobile bundles, or mobile data plans, the API’s top-ups endpoints or the SDK’s top-ups methods are utilized. On the other hand, for fulfilling digital gift cards or utility payments, the API’s vouchers endpoints or the SDK’s vouchers methods are employed to complete the transaction successfully.
When dealing with transactions in zendit, it is crucial to understand that there are two pricing types available for offers: Fixed and Range. The pricing type associated with the offer you send in a transaction determines the minimum set of parameters required to fulfill the offer successfully.
Fixed Price Offers are characterized by a predetermined cost and value for delivery. When initiating a transaction with a Fixed Price Offer, only the offer ID is required to manage the offer segment of the transaction. The cost of the offer will be reserved from the wallet, and the offer will then proceed to fulfillment. In the event of a successful fulfillment, the reserved funds will be deducted from the balance. Conversely, if the fulfillment is unsuccessful, the reserved funds will be returned to the wallet.
For fulfilling Open Range offers, additional information is required. These offers encompass a range of values, starting from the minimum value and extending to the maximum value. When initiating a transaction, this value range must be provided in the transaction details. The specific value to be delivered depends on the foreign exchange (FX) rate associated with the offer.
Open Range offers introduce two FX rates: one for the cost and, optionally, another for pricing the offer. By employing Zendit, you can handle the pricing of the offer. There are three methods supported by Zendit to send these values: Cost, Price, or Zend.
When submitting the offer, it is essential to include the value information and specify the type of value to be used. Sending the value as “COST” informs Zendit to utilize the cost FX for determining the value to be delivered based on the cost FX rate. Sending the value as “PRICE” informs Zendit to utilize the FX rate set for the offer to determine the customer’s price and subsequently the value to be delivered. Lastly, sending the value as “ZEND” informs Zendit to deliver the specified value directly.
It’s worth noting that the wallet or destination does not need to be included in the transaction details, as “COST” and “PRICE” will use the currency set for the wallet, while “ZEND” will use the currency associated with the destination of the offer.
Please bear in mind that when utilizing the “ZEND” option, it is important to consider that the value to be delivered is an estimate. Due to currency fluctuations and conversion rates, it may not be feasible to deliver the exact specified value. For instance, let’s take the example of a Cubacel top-up where you specify an amount of 500 CUP to be delivered. In this case, sending a “ZEND” value of 500 will ensure the exact delivery of 500 CUP. However, if you send a value like 433.72 CUP, it may not be fulfilled with absolute precision due to the limitations of FX rate precision, resulting in a slightly different delivered value.
Zendit does not generate transaction IDs for transactions; instead, they must be provided by the client. This approach allows our clients to use their preferred form of IDs as long as a unique transaction ID is supplied for each transaction. Transaction IDs are treated as string values, enabling clients to use autonumber fields from their systems, UUIDs, or any other tracking method.
It’s important to note that the test mode environment and production environments utilize separate transaction IDs. Therefore, a transaction ID used in the test mode environment only needs to be unique within that specific environment. If the same transaction ID is used in the production environment, there will be no conflicts as the ID is unique to each environment.
To illustrate, let’s consider an example where an autonumber field is used for transaction IDs. If the transaction ID “1” is passed to the test mode environment and another transaction with the same ID “1” is passed to the production environment, these two transactions are treated as separate entities. However, if you attempt to pass two transactions with the same ID to any environment, it will result in an error indicating that the transaction is a duplicate. For instance, passing the ID “1” to the test environment and then again passing the same ID “1” to the test mode environment will trigger an error.
To process Mobile Top Up, Mobile Bundle, and Mobile Data offers, you can utilize the /topups endpoints on the API (or topups methods in the SDKs.) The simplest type of top-ups to execute are fixed price offers, which only require the offer ID, transaction ID, and the recipient’s phone number. Optionally, the sender’s phone number and country can be included in the transaction if there is a need to track this information within Zendit.
For open range products, additional information needs to be provided. This includes specifying the type of value (COST, PRICE, or ZEND) and the corresponding value to transfer. This ensures that the correct value is delivered based on the chosen pricing method and the desired amount.
To process Digital Gift Card and Utility Payment offers, you can utilize the /vouchers endpoints on the API (or vouchers methods in the SDKs.) Voucher-based products are slightly more complex than Top Ups, as each offer comes with a specific set of required fields that must be included in the transaction. The specific fields required may vary depending on the offer in order to successfully fulfill the product.
For fixed price offers, you need to provide the transaction ID, offer ID, and an array of fields and corresponding values from the required fields list specific to the offer. This ensures that all the necessary information is included to complete the transaction.
In the case of open range products, you need to include the value to be transferred, along with the type of value (COST, PRICE, or ZEND) to be used for the pricing calculation. This ensures that the appropriate value is delivered based on the chosen pricing method and the desired amount.
To process eSIM offers, you can utilize the /esim endpoints on the API (or eSIM methods in the SDKs.) eSIM based products are easy to fulfill but require a couple of extra steps to first fulfill the product and then generate the QR code for the user to install the product on their phone.
All eSIM plans are fixed price offers and you need only provide the transaction ID, offer ID and optionally the ICCID for a returning customer that wishes to add an additional plan to their eSIM.
There are no open range products for eSIM. For more information about the eSIM product, see the eSIM Guide.
Zendit handles all transactions asynchronously. When initiating a transaction, zendit performs an initial validation of the request. It then returns either the transaction ID provided with the transaction as a confirmation of acceptance or an error message if the initial validation fails. You can refer to the error messages guide to understand the possible errors that may be returned during the transaction submission process.
If the transaction is accepted, zendit proceeds to process it. This involves conducting an authorization check against the wallet associated with the transaction. If sufficient funds are available, Zendit proceeds to hand off the transaction to the provider responsible for fulfillment. After fulfillment, Zendit updates the transaction status as either complete or failed, reflecting the outcome of the transaction.
Zendit provides 2 methods to retrieve the results of a transaction: webhooks (preferred) or polling. Your integration requirements will often guide you to which strategy of retrieving results. This guide covers the polling method. To learn more about the webhooks and to make your system more efficient in integration, see the webhooks guide for more information.
After sending a transaction to Zendit and receiving acceptance confirmation, Zendit will process the transaction asynchronously. To track the progress of the transaction, the client can periodically poll Zendit for updates on its status. The transaction progresses through several states, including PENDING, AUTHORIZED, IN PROGRESS, and eventually either DONE or FAIL. This represents a typical flow for a transaction, as illustrated below:
By monitoring the status of the transaction through periodic polling, the client can stay informed about its progress and take any necessary follow-up actions based on the transaction’s final outcome.
Once zendit receives the transaction, the client can begin polling for its status.
A transaction is considered complete when it reaches either the DONE or FAIL status. To retrieve common transaction details, you can use the /transaction/{transaction Id} endpoint for transaction polling. Once a transaction is complete, you can obtain the details of its fulfillment by accessing the /topups/transaction/{transaction Id} or /voucher/transaction/{transaction Id} endpoints, depending on the product type that was included in the transaction.
Alternatively, if you need to poll multiple transactions simultaneously, you can utilize the /transactions endpoint with various filters such as created date, product type, or status. Refer to the API Documentation for specific instructions on how to apply the created date filter. Note that the endpoint is paginated to prevent the retrieval of a large volume of results at once. If the transaction volume is high and you choose this polling strategy, you may need to send multiple requests to retrieve each page of transactions.
It is recommended to set the polling pace at a minimum of once per second. On average, fulfillment of transactions takes between 1 and 4 seconds. However, during periods of high traffic or heavier loads, the fulfillment time may be longer. In cases where there is significant traffic for a specific product, the time to fulfill a transaction could exceed 1 minute. Polling the status of transactions will provide a quick response with the current status, allowing you to continue polling for incomplete transactions. It’s important to adhere to the minimum 1-second delay between polls to avoid flagging your integration for excessive usage. Failure to comply with this guideline may result in rate limits being imposed on your access to the API.
