Payin API Steps

The API steps in this guide will walk you through how to fund a transaction between users on your platform. For an overview of how this works, refer to How payin payments are managed.

1. Check if a user​ exists in Zai already.
   GET /users/:id
2. Create a user​ for your customer (who you want to pay) if they don’t exist.
   POST /users
3. ​Update the user​ if they already exist (if needed).
   PATCH /users/:id
4. Get the ​wallet​ account ID for the user.
   GET /users/:id/wallet_accounts
5. Get the payin reference details for the user. This is just so you can add money to the account in our Pre-live environment.
   GET /wallet_accounts/:id/payin_details
6. (Pre-live only) Fund the user’s wallet account.
   PATCH /testing/wallet_accounts/process_payin

“wallet_accounts”: {
2  “id”: “5c1c6b10-4c56-0137-8cd7-0242ac110002”,
3  “payin_details”: {
4    “account_number”: “92191113“,
5    “sort_code”: “608382”
6    “iban”: “GB27SAPY60838292191113“,
7    “swift_code”: “SAPYGB2L”
8    “reference”: “<Customer Reference Number Value>“,
9    “amount”: “<wallet balance>”
10    “currency”: “GBP”
11  }
12}

7. (Once off) Set up a webhook on the transactions object to be notified of incoming funds.
   POST /webhook

"object_type": "transactions",

8. Create an item​ (use Type=2) to pay the payin account from the user’s account.
   POST /items
9. Fund the item​ with the user’s wallet​ account.
   PATCH /items/:id/make_payment

Design considerations

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

Payin data design

Once you’ve run through the API steps and implemented something like the above in your platform, the sequence of calls to run the payin workflow in production will be reduced to:

1. Create a user for your customer (who you want to pay) if they don’t exist.
   POST /users
2. Update the user​ if they already exist (if needed).
   PATCH /users/:id
3. Catch the webhook when the user’s wallet is funded through the bank.
4. Create an item to pay the payin account from the user’s account.
   POST /items
5. Fund the item with the user’s wallet account.
   PATCH /items/:id/make_payment