Payout API Steps

The API steps in this guide will walk you through setting up payout disbursements to send funds to your user’s bank account once a payout request is completed. For an overview of how this works, refer to How payout payments are managed.

(Pre-live only) Inbound payments (topping up your float)

The following steps allow you to add funds to a user’s wallet account in our Pre-live environment. In the real world, you'd send us a payment and we'd match it to the wallet. For the purposes of testing, you can add funds to wallets as needed.

1. Create a user​ for your float user.
   POST /users
2. Get the ​wallet​ account ID for your float user.
   GET /users/:id/wallet_accounts
3. Get the payin reference details for the user (this is just so you can add money to the account in Pre-live).
   GET /wallet_accounts/:id/payin_details
4. (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}

5. Get the wallet account ID and balance for your float user.
   GET /users/:id/wallet_accounts

Outbound payments (paying your users)

The following steps provide the end-to-end flow that includes how to fund your user’s wallet account.

1. Create a user for your customer (who you want to pay) if they don’t exist already.
   POST /users
2. Update the user for your customer if they already exist (if needed).
   PATCH /users/:id
3. ​Add a bank account​ for your customer (you’ll need the bank account ID in step 7).
   POST /bank_accounts
4. Create an item​ (use Type=2) to move money from your float user to your customer.
   POST /items
5. Fund the item with your float user’s wallet (use the ID you got from Inbound payments, step 2)
   PATCH /items/:id/make_payment
6. Check the webhook payload to see how your user’s wallet was funded.
   GET /webhooks/:id/responses
7. Create a withdraw request​ on the wallet to pay to your user’s nominated bank account (use the bank account ID from step 3)
   POST /wallet_accounts/:id/withdraw

{
    "account_id": abc 123456789,
  "custom_descriptor": "See Design Considerations - Custom Descriptors",
  "amount": 10000 // Amount in cents 
}

8. Check the webhook payload to see that the payout has been completed.
   GET /webhooks/:id/responses
9. Check the wallet balance of your user to confirm funds have been sent.
   GET /wallet_accounts/:id

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 in order to reduce the number of API calls required throughout the API workflow.

Custom descriptors

For real time payouts, you have the option of customising the payment description seen by your customers.
It's an extra parameter on the ​withdraw call​ named ​custom_descriptor​. You can have a string of up to 200 alphanumeric characters. It'll then be prefixed by the word "Payment ", for example, "Payment {for transaction ID 1234567812345678}".

/wallet_accounts/:id/withdraw?account_id=&amount=&custom_descriptor

Workflow summary

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

This flow assumes that you have a webhook service running, that your user exists, and that a bank account has been added and set as a disbursement/payout account.

1. Create an item to move money from your float user to your customer.
   POST /items
2. Fund the item with your float user’s wallet (use the ID you got from the inbound payments, step 2)
   PATCH /items/:id/make_payment
3. Create a withdraw request on the wallet to pay to your user’s nominated bank account (use the bank account ID from step 3).
   POST /wallet_accounts/:id/withdraw