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:

1. Log in to the Ivy Dashboard.
2. 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

To list all 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.