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:

TypeDescriptionExample
Existing IDYou 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
UUIDA universally unique identifier which can ensure a unique index.59188265-9f38-4f1f-b9b0-8541a7905ea1
Combined Item ID with Buyer IDThis 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 UUIDA 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:

TypeDescriptionExample
User/Item IDsIf 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 StatusThe 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 StateThe 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 ResponsesStoring 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 IDZai user IDZai bank account IDZai digital wallet ID
100010015b8f59b6-32c1-44a3-8f5b-b9e2c77bc265fb35b028-76fb-44df-86ac-822dccf1cd7ddcdfdb78-27e7-485d-90c0-11ffbf950d72
10001002efe6f8c1-0a30-484a-b085-9d9d0539dbfc4355de7b-18c2-4892-b800-b7bbb6f0a9b3054cd04e-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

TokenDescription
API credentialsA combination of client code, secret and scope that is generated for your platform. Contact Zai if you need new credentials generated.
Card tokenThis 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 .