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
- Create a buyer user in Zai.
POST /users
- 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
- Create a seller user in Zai.
POST /users
- [Create an Item] (ref:createitem) between the buyer and the seller.
POST /items
- (Once off) Set up Callback (webhook) on the
items
object to be notified of when the item status changes.
POST /callbacks
"object_type": "items",
- (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",
- (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",
- 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:
-
The item status will move to completed and you will receive an
items
callback indicating the item iscompleted
and the item will have the value ofreleased_amount
equal to 0 initially. -
You will also receive a
transactions
callback indicating that the transaction oftype: payment
andtype_method: credit_card
issuccessful
. -
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 oftype: payment_funding
andtype_method: credit_card
with a status ofsuccessful
. Additionally, you will also receive another callback foritems
with the value ofreleased_amount
equal to the value of the item amount.
In Pre-live you can:
- (Pre-live only) Call the
GET /batch_transactions/export_transactions
API which moves all pendingbatch_transactions
intobatched
state. As a result, this API will return all thebatch_transactions
that have moved frompending
tobatched
. Please store theid
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 thisid
, 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"
}
]
}
- (Pre-live only) You can call the following API which moves one or more
batch_transactions
intobank_processing
state12700
. You will need to pass in theid
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": []
}
- (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 beingsuccessful
state12000
. 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 abatch_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_id | zai_user_id | zai_card_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 |
Payin data design
your_payin_id | zai_item_id | zai_transaction_id | zai_batch_transaction_id |
---|---|---|---|
30001001 | 1563db1c-add2-4dcd-ae20-5ad3802bf1c4 | 1ddb9cbb-90a7-41c6-bbbe-05e44f3134f1 | 54504fea-68cf-4154-b16b-ac7b747c4e20 |
30001002 | f827dbb5-ba17-4241-a282-14336351faff | 445bbaf3-c9bc-41aa-aec4-c9a99944941d | d43ad47d-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
Updated about 2 years ago