Customer Payouts
Overview
This feature enables you to trigger closed- and open-loop payouts to your customers using instant bank rails.
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.
Creating a Customer 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"
}
}
'
Statuses:
Status | Description |
---|---|
paid | The money has successfully arrived in the customer's bank account. |
failed | The money has not arrived in the customer's bank account within 6 days and will not arrive anymore. |
canceled | The payout flow has not been completed and the session expired. |
Listing and Retrieving a Customer Payout
Dashboard
You can view all customer 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 customer payouts.
API
To list or retrieve customer payouts programmatically, use the following endpoints:
List customer 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 Customer Payout
To retrieve a specific customer 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 customer payouts, ensuring transparency and control over your payout processes. To optimise the customer experience, please look into our UX guidance on Withdrawals.
Conclusion
The customer Payouts API allows for seamless fund transfers to customer 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 10 days ago