Payin API Steps

A walk through for bank-to-bank transfers in the UK.

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}
  1. (Once off) Set up a webhook on the transactions object to be notified of incoming funds.
    POST /webhook
"object_type": "transactions",
  1. Create an item​ (use Type=2) to pay the payin account from the user’s account.
    POST /items
  2. 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.

your_customer_id

zai_user_id

zai_bank_account_id

zai_digital_wallet_id

zai_user_crn

10001001

5b8f59b6-32c1-44a3-8f5b-b9e2c77bc265

fb35b028-76fb-44df-86ac-822dccf1cd7d

dcdfdb78-27e7-485d-90c0-11ffbf950d72

ZPP1234567890123

10001002

efe6f8c1-0a30-484a-b085-9d9d0539dbfc

4355de7b-18c2-4892-b800-b7bbb6f0a9b3

054cd04e-19f1-4938-908b-8e9e5c212f4d

ZPP1234567890123

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

your_payin_id

zai_item_id

30001001

1563db1c-add2-4dcd-ae20-5 ad3802bf1c4

30001002

f827dbb5-ba17-4241-a282-1 4336351faff


What’s Next

Set up payout disbursements to send funds to your user's bank account.

Did this page help you?