User Payouts
Overview
This feature enables you to trigger closed- and open-loop payouts to your users using instant bank rails.
User payouts allow merchants to transfer funds directly to users. This can be done using the user's financial address or referencing a previous order. The payouts can currently be initiated only through the API.
Creating a User Payout
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.
Closed Loop Payout
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"
}
}
'
Open Loop Payout
Set the financialAddress
field in the destination
object to send an open-loop payout, i.e. a payout to a customer who has not 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": {
"financialAddress": {
"type": "iban",
"iban": {
"iban": "DE93500105176719451585",
"accountHolderName": "Chris Simon"
}
}
},
"metadata": {
"purpose": "dividend",
"random": "field"
}
}
'
Listing and Retrieving a User Payout
Dashboard
You can view all user payouts in the Dashboard. To access your payouts:
- Log in to the Ivy Dashboard.
- Navigate to the Payouts section to see a table of all user payouts.
API
To list or retrieve user payouts programmatically, use the following endpoints:
List User 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'
Retrieve a User Payout
To retrieve a specific user 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"
}
'
These endpoints allow you to efficiently manage and track user payouts, ensuring transparency and control over your payout processes.
Conclusion
The User Payouts API allows for seamless fund transfers to users and provides flexibility with both closed-loop and open-loop payouts. Following this guide, you can easily integrate and manage payouts within your application.
Updated 4 months ago