Concepts
This concepts document will walk you through the features of zendit and how to use them. These concepts include:
Wallets
Wallets are where funds for purchasing offers in zendit are stored. As transactions are processed the wallet balance will be reduced. Wallets can be replenished with funds from a credit or debit card with a one time recharge or can be set to automatically replenish funds by a selected amount when the balance falls below a selected limit. If a wallet is not replenished with funds, purchases that exceed the balance of the wallet will fail due to insufficient funds.
Wallets in zendit
Wallets in zendit are prepaid using a credit or debit card. Once a wallet has funding, funds can be used for purchasing offers in zendit.
During the purchase of an offer, the funds required to pay for the transaction will be put in a temporary authorization state until fulfillment completes. Upon successful completion of the transaction, the funds will be deducted from the wallet balance. If the transaction is not successful, the authorization will be released and the funds are returned to the wallet.
Each zendit account has 2 wallets, 1 for the sandbox testing environment and one for production. Because transactions are simulated in the test environment, the balance of the wallet can be set by the user to run test purchases without need of a credit or debit card.
Test Mode Wallets
When using test mode, the wallet balance can be set to a specific amount by the user. This allows the user to test their application against zendit without needing a credit or debit card in a variety of operations. The balance can be set to a high value for testing many transactions and offer types, or set to 0 to test handling purchase errors due to a depleted balance.
Production Wallets
When an account is processing a transaction in production mode, the zendit production wallet must have sufficient funds to make the purchase of an offer. When an account is first moved to production, a credit or debit card must be added to the account and the initial balance of the wallet can be purchased. Once the account is funded, purchases of offers can be made. The production wallet can be set to automatically recharge when the balance is low to avoid interruption in sales of products. For higher volume accounts, when using automatic recharge it is advised to set the low balance to a higher amount to allow up to 60 seconds for a credit or debit card transaction to complete when automatically replenishing funds in the account.
For users that don’t opt in to automatic recharge, it is advised to monitor your wallet balance regularly and recharge it when funds are running low to avoid an interruption in service.
Funding Wallets
Wallets are funded using a payment instrument. Currently debit and credit cards are allowed instruments for payment. Future versions of zendit will support additional payment instruments.
Checking the balance of Wallets in integrations
The current balance of the wallet may be viewed from the user console, or through the API to get the current balance. The balance can also be retrieved via the API and SDKs for app developers who may want to periodically monitor the account balance and set an alert outside of zendit when the balance is low.
Catalog
The zendit Catalog
The zendit catalog contains all products available to sell along with the cost for each product. The catalog is currently divided into 2 sections: 1 for International Mobile Top Up products including International Mobile Bundles and a section for Digital Gift Cards inclusive of Utility Payments. There are several features of the catalog to explore and keep in mind that when you make changes to your catalog, the changes will be reflected both in test mode and your production environment.
Offers
Each product in the catalog is represented by an offer. The offer has a sub type, a brand and a cost for offering it. You can filter your view by destination country, brand and subtype and can export your catalog to as a CSV file to view in spreadsheet applications like Excel. Offers come in 2 varieties: Fixed and Range.
Fixed offers
A fixed offer contains a specific value sent to the destination and cost to your account when selling it. Using the API, fulfilling the offer is as simple as sending through the product ID.
Ranged offers
A ranged offer has a minimum and maximum value for the destination currency as well as a for the cost. The cost is based on an FX value applied to the offer based on the value.
When using the API with a ranged offer, you have 3 options for sending the value through: Price, Cost or Zend. Price is based on the catalog FX price for selling the offer (more on this in the pricing section), Cost is based on the FX rate set as your cost. Zend is based on the destination value desired.
Note that due to currency fluctuations the value sent to the destination is an estimation and can’t be guaranteed. Values sent are rounded to the lowest unit of currency in the destination and fractional units of currency are not supported.
Offer costs
For each product in the catalog, there is a cost associated. This is how much money will be deducted from your wallet based on a successful sale.
Pricing Offers
In the catalog view, you can open the pricing suggestions to see our recommended pricing to sell the product. If you don’t have a catalog system for your integration, or plan to use zendit’s catalog to expose to your users through our API, you also have the option to click on the product and edit the price.
For fixed price offers, you can edit the price by setting a specific price to sell, or set the desired margin for the product and the price to sell will be set for you.
For open range offers, you can edit the FX rate you give users for purchasing, or set the desired margin and the FX rate will be computed for you.
All prices set in the catalog are exposed through the zendit API with no requirement for you to maintain a separate catalog system.
Using the zendit Catalog in integration
Through the zendit API, there are 2 options to integrate the catalog. You can either pull the products and costs into a separate catalog and handle pricing in your separate system or you can set up your prices and select which products you wish to sell in zendit and use the zendit API to pull the catalog to serve your customers.
Security
Every zendit account starts with an API key for the test environment. This API key must be sent in the Authentication header of a request to the API. When upgrading your account to production, you will receive a production API key in addition to your test mode key for accessing the API. Use the test mode key for testing and your production key for your production environment.
Do not share this key outside your organization. When contacting support, we will use your email address to look up your account and will never ask you for your API key.
API keys are the first level of security to identify your account and bill correctly. Keep the key secure and if you suspect your account has been compromised contact support@zendit.io to get a new API key. As a temporary measure you can also disable all products in your catalog.
As we continue to improve the product, we will be adding the ability for users to generate new API keys in the zendit console.
IP Whitelisting
To make your environment more secure, zendit allows you to setup IP whitelists though the user console. You can setup IP whitelists for both your test mode and production environments. We recommend that IP whitelists always be setup for the production environment before upgrading your account to production.
To setup whitelists, head to the API settings section of the user console and you can add them. You can setup multiple whitelist entries for each environment and each entry can contain up to 20 IP rules.
IP Rules
When creating a whitelist, you may enter individual IP addresses (1 per line) or you may enter a range of sequential IP addresses (e.g . 62.159.33.1 through 62.159.33.100) by adding the address to start and the address to end with a ~ between the 2 as such: 62.159.33.1 ~ 62.159.33.100. This will allow all addresses between 62.159.33.1 and 62.159.33.100 to access the API for the environment selected.
Warning about not using IP Whitelist in production environments
If you don’t have a fixed IP to whitelist, or elect not to whitelist your environment, your account can be accessed from any internet location. This is high risk and we recommend that you obtain a public IP and whitelist it for your integration. If your account is compromised and you elected not to setup a whitelist for access, zendit will not assume responsibility for misuse of your account.
