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:

Listing and Retrieving a Customer Payout

Dashboard

You can view all customer 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 customer payouts.

API

To list or retrieve customer payouts programmatically, use the following endpoints:

List customer Payouts

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