Overview

The Transfers API sends money from one of your Vendy wallets to any supported bank account. You give the beneficiary's bank details directly in the request, so you don't need to add a payout account first.

Transfers run on the same engine as Payouts. A transfer is a payout, and it shows up in your payout history, fees and payout webhooks.

Authentication

Send your merchant keys as headers on every request:

Bash

--header 'AccessKey: YOUR_ACCESS_KEY' \
--header 'SecretKey: YOUR_SECRET_KEY'

The keys must belong to a team member with the right permission on the business:

Permission	Grants
transfers:read	Get Transfer, List Transfers
transfers:create	List Banks, Validate Account, Single Transfer
transfers:create_bulk	Bulk Transfer
transfers:manage	Everything above

🚧

Payout permissions are also required

Creating a transfer also checks the payout permissions payouts:create or payouts:manage. Make sure the team member has both the transfer and payout permissions, or the request returns 403.

Making a transfer

1. Find the bank. Call List Banks for the currency and pick the beneficiary's bank code.
2. Confirm the account. Call Validate Account to get the account name the bank has on record.
3. Send it. Call Single Transfer, or Bulk Transfer for several at once, with your own reference.
4. Track it. Listen for payout webhooks, or poll Get Transfer with your reference.

References

Every transfer needs a reference, which becomes the transfer's refid. Use it to look the transfer up later and to match webhooks to your records.

• It must be unique across Vendy, not just your business. Reusing a reference returns error 439.
• It may contain letters, numbers, -, _ and ., up to 50 characters.
• Prefix references with something specific to your business (for example ACME-INV-0042) to avoid collisions.

👍

Retry safely

If a request times out, retry it with the same reference. If the first attempt went through, the retry is rejected with 439 instead of sending the money twice. Then call Get Transfer to see the result.

Beneficiaries

The first time you send money to an account, Vendy saves it as a payout account on your business. Later transfers to the same account number and bank reuse it. Saved accounts appear in Get payout accounts.

Statuses

Status	Meaning
pending	Created and wallet debited; waiting to be processed
processing	Sent to the bank
completed	The bank confirmed the transfer
failed	The transfer did not go through; see reason. Final only once you receive payout_failed (see below)
cancelled	Cancelled before processing; the wallet was refunded

📘

failed is not always final

If a bank rejects a transfer, its status shows failed while Vendy retries it through another bank, so it can still become completed. A transfer has finally failed only when Vendy declines it, sends a payout_failed webhook and refunds your wallet. Don't refund or resend a transfer just because you see failed when polling.

Endpoints

Endpoint	Description
GET /transfers/banks	Supported banks for a currency
POST /transfers/validate/account	Resolve an account name
POST /transfers/{businessId}/single	Send one transfer
POST /transfers/{businessId}/bulk	Send many transfers in one request
GET /transfers/{businessId}/{refid}	Get a transfer by reference
GET /transfers/{businessId}	List transfers

Errors

Errors return HTTP 400 (or 403 for missing permissions) with status: false and a Vendy code:

JSON

{
  "status": false,
  "code": 204,
  "msg": "Input is invalid",
  "data": [{ "amount": "amount must be greater than zero" }]
}

Each endpoint page lists the codes it can return.