Payouts are the most flexible way to send money from your Ivy account to anyone — customers, partners, suppliers, or any external account. Common use cases include:
  • Trading: Instantly pay your supplier after a successful trade or delivery
  • Marketplaces: Payout to sellers, drivers, or freelancers
  • Finance: Move funds between treasury accounts or pay out interest/dividends
  • Consumer: Customer withdrawals, refunds, or loyalty rewards
  • Payroll: Pay out salaries, wages, or commissions
Payouts currently support fiat currencies. Stablecoin and virtual account payouts are coming soon.

​
How Payouts Work

1

Choose payout type

  • Closed-loop: Pay a customer who has previously paid in via Ivy (reference their order)
  • Open-loop: Pay any external account using their bank details (IBAN, sort code, etc.)
2

Create a payout

Use the API to specify the amount, currency, and destination (orderId or financial address).
3

Track status

Monitor payout status in the Dashboard or via webhooks. Funds usually arrive instantly, but can take up to 2 business days depending on the bank.
See API Reference for full details Customer payouts allow merchants to transfer funds directly to customers. This can be done using the customer’s financial address or referencing a previous order. The payouts can currently be initiated only through the API.

​
API Reference

To create a payout from a merchant account, use the endpoint. This endpoint lets you specify the payout- amount, currency, and destination. The destination can be a previous orderId for closed-loop payouts or a financialAddress for open-loop payouts. Set the orderId field in the destination object to send a closed-loop payout, i.e. a payout to a customer who has previously paid in money using Ivy Instant Bank Payments. 
curl --request POST \
     --url https://api.getivy.de/api/service/payout/create \
     --header 'X-Ivy-Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 100,
  "currency": "EUR",
  "destination": {
    "orderId": "abc123"
  },
  "metadata": {
    "purpose": "random"
  }
}
'

​
Statuses

StatusDescription
paidThe payout has been successfully initiated and funds have left the Ivy sending account.
failedThe payout could not be initiated. Can be caused by insufficient funds, a technical error, an invalid beneficiary, or bank rejection
canceledThe payout flow was cancelled before being attempted. Can be caused by invalid requests, account issues, or manual cancellation by merchant admins.

​
Listing and Retrieving a Payout

​
Dashboard

You can view all payouts in the Dashboard. To access your payouts:
  1. Log in to the Ivy Dashboard.
  2. Navigate to the Payouts section to see a table of all payouts.

​
API

To list all payouts: 
curl --request POST \
     --url https://api.getivy.de/api/service/payout/list \
     --header 'X-Ivy-Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
To retrieve a specific payout: 
curl --request POST \
     --url https://api.getivy.de/api/service/payout/retrieve \
     --header 'X-Ivy-Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "id": "payout_id"
}
'

​
Webhooks

To receive real-time updates about your payouts, set up webhook subscriptions. This allows you to automatically respond to payout status changes without polling the API.

​
Payout Webhook Events

EventDescription
payout.initiatedSent when a payout is created and processing begins
payout.paidSent when the status reaches paid. Initiation succeeded and funds have been sent
payout.failedSent when the status reaches failed

​
Setting Up Webhooks

  1. Create a webhook subscription using the webhook subscription API:
curl --request POST \
     --url https://api.getivy.de/api/service/webhook-subscription/create \
     --header 'X-Ivy-Api-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "url": "https://your-server.com/webhooks/ivy",
  "events": ["payout.initiated", "payout.paid", "payout.failed"]
}'
  1. Handle incoming webhooks on your server. Each webhook contains the payout data:
{
  "id": "payout_123",
  "type": "beneficiary",
  "currency": "EUR",
  "amount": 100,
  "status": "paid",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:35:00Z",
  "destination": {
    "type": "iban",
    "iban": {
      "iban": "DE89370400440532013000",
      "accountHolderName": "John Doe"
    }
  }
}
  1. Test your webhook integration using the webhook trigger endpoint