API Reference

Overview

Zai is a powerful payments engine custom-built for marketplaces. Removing compliance, fraud, risk, staffing, and operational headaches; Zai helps online platforms focus on what matters most to their business.

Zai supports international payments and multiple transaction types in a wide range of currencies.

Marketplaces can offer their buyers/payers the ability to pay using:

  • Real time payments (Australian NPP / OSKO)
  • Credit & Debit Cards
  • ACH Direct Debit
  • BPAY
  • Wire Transfer

Sellers/payees can receive their funds by using:

  • Real time payments (Australian NPP / OSKO)
  • ACH Direct Credit
  • BPAY

Zai provides you with an API to easily and quickly start taking payments on your marketplace.

Zai's API environments

Both your Live (production) and Pre-live (sandbox) platforms can be managed by accessing the Zai Dashboard at: https://dashboard.hellozai.com/.
For more details, see our Environments guide.

🚧

Please note

When you go to the Zai Dashboard, you'll need to select either Live or Pre-live. The Live environment is for production use only. Use Pre-live to test your integration.

API endpoints

To access the Live (production) environment, use the following endpoint:
https://secure.api.promisepay.com

To access the Pre-live (sandbox) environment, use the following endpoint:
https://test.api.promisepay.com

Authentication

With the OAuth2 credential flow, you’ll acquire 60-minute Bearer Tokens from an issuing server before interacting with Zai API rather than sending your credentials with every request. These Bearer Tokens will be passed on subsequent requests in the Authorisation header to our API.

The URLs and credentials for authenticating using the OAuth2 credential flow are available from the Dashboard. From the Platform Profile menu, select Reveal to get your Client ID, Client Secret, and Scope.

Frequently Asked Questions

  • Does the generated token expire?
    Yes, tokens expire in 60 minutes.
  • Is this a one-time thing?
    A valid token is required for all API requests; therefore using credentials to acquire tokens is not a one-time thing and should be considered when integrating.
  • Is there an endpoint to refresh the expired tokens?
    No, but you can generate new tokens using the client credentials.
  • Should we save the token somewhere to use for the next 60 minutes, or can we call this endpoint more often? For example, for every API request on our server, would we also request a new token? That’s about 60–100 requests per minute.
    Yes, these tokens are meant to be stored and reused until they expire.
    At that request rate, you’ll hit our auth provider rate limit and will not be able to generate any more tokens.
  • How can we rotate the credentials if they’re compromised?
    We can rotate the credentials if they are compromised. Please contact us at [email protected] in this situation.

📘

Please note

Rotating credentials will remove the old credentials, creating downtime for you. The updated credentials can be fetched from the Dashboard.

Specifications

This section contains the API specification in JSON and Swagger formats.