Developer Checklist
Coming soon
Credit card and direct debit transactions within the UK are not yet available.
Technical considerations
Object identifiers
Zai can track your User Identifiers (IDs) and Item IDs to identify objects.
This is a default feature that makes it easier to track these objects within Zai. By doing this, you do not need to store any Zai generated User or Item identifiers. Instead, you can pass your IDs on creation.
Users and Items are the primary objects of Zai and through these, you can access every piece of data stored in the system.
There are multiple formats that can be used when sending us a User or Item ID:
| Type | Description | Example |
|---|---|---|
| Existing ID | You may already be tracking an ID for a User or Item. You can pass us this when you create the User or Item object. | item001 |
| UUID | A universally unique identifier which can ensure a unique index. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 |
| Combined Item ID with Buyer ID | This combination is often used when creating Items that have buyerâs bidding for the same goods/services on your platform. This method avoids having duplicate Item Identifiers created in Zai. | item001_buyer001 does not conflict with item001_buyer002. |
| Generated UUID | A UUID generated by Zai that you will need to store within your system. Contact Zai if you wish to have this enabled. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 |
Storing Data
There are certain data elements produced and processed in Zai that may need to be stored within your database for future reference. These are commonly related to identifiers, statuses and API responses. Some examples of these are:
| Type | Description | Example |
|---|---|---|
| User/Item IDs | If you opt for Zai generated IDs, they will need to be stored against the relative User/Item object in your platform. | 59188265-9f38-4f1f-b9b0-8541a7905ea1 stored against a row in your âcustomersâ or âusersâ table. |
| Item Status | The most important piece of data for an Item is the âstateâ. This state represents whether an Item is pending, in progress or completed. | This can be stored to ensure that once an interaction on your platform is complete, no further calls are made to Zai. |
| User KYC State | The Userâs KYC state changes when Zai verifies the Userâs data. | The KYC state can be stored and used to restrict certain functions available for your users. For example, you may wish to restrict Transaction amounts depending on a Userâs status. |
| API Responses | Storing API responses from a third party is common practice in software development. It involves storing the response (including headers) received from a Zai API request. | This can be used to track whether payment calls were successful and to track the reason why a card may have been declined. |
To reduce the number of API calls required throughout a complex payment workflow, we suggest storing a map of IDs on your platform. For example:
| Your platform customer ID | Zai user ID | Zai bank account ID | Zai digital wallet ID |
|---|---|---|---|
| 10001001 | 5b8f59b6-32c1-44a3-8f5b-b9e2c77bc265 | fb35b028-76fb-44df-86ac-822dccf1cd7d | dcdfdb78-27e7-485d-90c0-11ffbf950d72 |
| 10001002 | efe6f8c1-0a30-484a-b085-9d9d0539dbfc | 4355de7b-18c2-4892-b800-b7bbb6f0a9b3 | 054cd04e-19f1-4938-908b-8e9e5c212f4d |
Email Addresses
Emails are a required piece of data for a user to be onboarded in Zai. By default, an email address is unique in Zai. This restriction is designed for a platform that has both registered buyers and sellers, with unique email addresses.
Your platform may not need to know the identity of users, which means you may not have an email address to pass to Zai until during the payment process. If this is the case, then you will need to contact Zai to disable the unique email feature.
Monitoring
There are a number of ways to monitor the uptime and status of the Zai service. You can visit status.hellozai.com to see any incident reports that have occurred. Furthermore, there is an endpoint available to check the status of the API service.
Authentication
Interacting with Zai primarily occurs via the APIs, however, there are some front-end features that are provided to help with PCI compliance, fraud & risk and user experience. Providing trust on a platform which handles payments results in dealing with a large amount of sensitive information.
When providing sensitive information to Zai, you must ensure authentication is provided appropriately. Your API credentials should only be exposed within the back-end of your system and not on the front-end. Making your API credentials publicly available potentially enables an unauthorized person to interact with the accounts and information of your users.
When using the Hosted Forms and Hosted Fields packages and authenticating on the front-end, an expirable token will always need to be generated on the back-end first, ensuring that the API key is never exposed.
For more information relating to authentication please refer to Authentication
Tokens
| Token | Description |
|---|---|
| API credentials | A combination of client code, secret and scope that is generated for your platform. Contact Zai if you need new credentials generated. |
| Card token | This token is used with the the Hosted Forms and Hosted Fields packages to pass credit card details securely to Zai for a certain User. |
Callbacks
Many statuses and actions occur within Zai through several batch processes that run throughout each day. Because of this, callbacks are essential to closing the loop of an Zai integration and are helpful to present back to users so that they understand where theyâre currently at within a transaction.
Callbacks can be sent from a number of IPs that will need to be whitelisted, different for each environment .
Updated about 2 years ago