Cards Payin Workflow

📘

Australia only

This guide is for platforms operating in Australia.

Overview

This integration guide will run you through how to use cards to fund an item through a user's wallet account.
You will need to capture a user's card details into a card account and then create an item between buyer/payer and seller/payee. Afterwards you perform a make payment action on that item specifying the card account of the buyer/payer.

Getting Started

Before you can run your cards workflow there are a few setup steps that need be completed so that all of the pieces are available.

Terminology used
The following terminology is used throughout this guide:

  • Platform​ refers to you as a Zai customer, or your website, application, marketplace etc.
  • User​ refers to your customer who has a User record in Zai.
  • Item​ is the mechanism for moving funds between users in the API.
  • Payin​ is money being paid into the Zai ecosystem from a bank account.
  • Payout​ is money being paid out of the Zai ecosystem to a bank account.
  • Card account is an account attached to a user that contains encrypted card details.

API steps

  1. Create a buyer ​user​ in Zai.
    POST /users
  2. Create a card account for the buyer Card Accounts. Please make sure you store the card account id as you will need that later on when making the payment.
    POST /users/:id/card_accounts
  3. Create a seller ​user​ in Zai.
    POST /users
  4. [Create an Item] (ref:createitem) between the buyer and the seller.
    POST /items
  5. (Once off) Set up ​Callback​ (webhook) on the ​items object to be notified of when the item status changes.
    POST /callbacks
"object_type": "items",
  1. (Once off) Set up ​Callback​ (webhook) on the ​transactions object to be notified of when the card transaction is authorised on the buyers card
    POST /callbacks
"object_type": "transactions",
  1. (Once off) Set up ​Callback (webhook) on the Batch Transactions object to be notified of when the card transaction is settled and the funds are moved to the seller's wallet.
    POST /callbacks
"object_type": "batch_transactions",
  1. Call Make Payment on the item and specify the card account id (obtained from step 2)
    PATCH /items/:id/make_payment

Once the the make_payment API has been called, Zai will attempt to authorise the payment against the card account. This will result in the card being debited and if successful, the following steps will occur:

  1. The item status will move to completed and you will receive an items callback indicating the item is completed and the item will have the value of released_amount equal to 0 initially.

  2. You will also receive a transactions callback indicating that the transaction of type: payment and type_method: credit_card is successful.

  3. Only after the card transaction settles (this could vary between 1-2 business days based on your settings) the funds will be applied to the seller/payee's wallet account. As part of that you will receive a batch_transactions callback of type: payment_funding and type_method: credit_card with a status of successful. Additionally, you will also receive another callback for items with the value of released_amount equal to the value of the item amount.

In Pre-live you can:

  1. (Pre-live only) Call the GET /batch_transactions/export_transactions API which moves all pending batch_transactions into batched state. As a result, this API will return all the batch_transactions that have moved from pending to batched. Please store the id in order to progress it in Pre-live.

📘

Note

When you simulate a payment journey in Pre-live, the response including the transaction id will be cleared after a day. If you need to retrieve this id, you can call the List Transactions API, input a limited number of results depending on how much time has passed, and then find it from that list of transactions.

{
    "transactions": [
        {
            "id": "439970a2-e0a1-418e-aecf-6b519c115c55",
            "batch_id": null,
            "status": "batched",
            "type": "payment_funding",
            "type_method": "credit_card"
        }
    ]
}
  1. (Pre-live only) You can call the following API which moves one or more batch_transactions into bank_processing state 12700. You will need to pass in the id from step 12.
    PATCH /batches/:id/transaction_states
{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12700
}
{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}
  1. (Pre-live only) You can call the same API from the step above to move one or more batch_transactions to the final state of processing being successful state 12000 . This will simulate the step of the flow where we complete the processing of the card funding for the payment and will result in you receiving a batch_transactions webhook
    PATCH /batches/:id/transaction_states
{
	"exported_ids" : ["439970a2-e0a1-418e-aecf-6b519c115c55"],
	"state": 12000
}
{
    "aggregated_jobs_uuid": "c1cbc502-9754-42fd-9731-2330ddd7a41f",
    "msg": "1 jobs have been sent to the queue.",
    "errors": []
}

If you are after more information on the item, transactions or batch_transaction you can query them using their ids

/batch_transactions/dabcfd50-bf5a-0138-7b40-0a58a9feac03

Design considerations

When designing how this workflow will interface with your platform, we suggest storing a map of specific object IDs on your side in order to reduce the number of API calls required throughout the API workflow.

User data design

your_customer_idzai_user_idzai_card_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

Payin data design

your_payin_idzai_item_idzai_transaction_idzai_batch_transaction_id
300010011563db1c-add2-4dcd-ae20-5ad3802bf1c41ddb9cbb-90a7-41c6-bbbe-05e44f3134f154504fea-68cf-4154-b16b-ac7b747c4e20
30001002f827dbb5-ba17-4241-a282-14336351faff445bbaf3-c9bc-41aa-aec4-c9a99944941dd43ad47d-fb2d-46b2-bc3d-a623a290cdac

General Information

For capturing card details securely while reducing your PCI obligations please refer to:
Integrating Drop-in UI for Capturing a Credit Card

For the different set of details you would receive in callbacks and some sample callbacks please refer to: Callbacks

For test data to use when creating a card please refer to: Test data