Settlements

​

Fiat Settlements

Settlements will be made to the bank account you specified during onboarding. Settlements usually arrive instantly, but can take up to 2 business days.

We always settle the available balance to you. You can also define a minimum balance for your account which should never be paid out in order to have sufficient funds for refunds or customer payouts.

Your balance will be paid out periodically at intervals you control or using the merchant dashboard where you can also initiate a payout manually at any time.

​

Stablecoin Settlements

Ivy provides you with the option to settle your available fiat balance directly on chain with Stablecoins.

​

Flow of Funds

Customers pay in funds to collection accounts which Ivy holds in your name with instant bank transfers in fiat currencies, e.g. EUR, GBP, SEK, DKK. At intervals you control (weekly, daily, hourly), the currently available balance of each fiat currency is being paid out to your beneficiary wallet in Stablecoins.

The conversion of fiat funds to Stablecoins happens at the exact moment of the payout at market rates. Ivy is connected with Stablecoin issuers directly to provide you with the best possible rate at any given time.

​

Setup

In order to activate Stablecoin Settlements, you have to define a fixed beneficiary wallet and the settlement interval you prefer. Funds will be sent according to the interval to the fixed beneficiary wallet by Ivy.

We are working on supporting settlements to dynamic wallet addresses you can define for each payout.

We currently support the following currencies

• EURC

• USDC

and the following intervals

• Monthly

• Weekly

• Daily

• Twice per day

​

Reporting

You can use the Payout Report API to get a list of all settlements made to your beneficiary account in a certain period. Settlements are paid out regularly, and the payout report will show you all transactions included in one settlement payout.

​

Create a Payout Report

To create a payout report, request the Create Payout Report endpoint. You must provide the intervalStart and intervalEnd fields in the request body as UNIX timestamps.

​

Example Request Payload

{ 
  "intervalStart": 1638886400, 
  "intervalEnd": 1638972800 
}

In the response, you receive the id and the initial status of the payout report. You can use this id to retrieve the status later and download the payout report.

​

Example Response Payload

{
    "id": "5f9b5f9b-5f9b-5f9b-5f9b-5f9b5f9b5f9b",
    "status": "pending"
}

​

Poll for the report status

After you have created the payout report, the report is gathered asynchronously and usually takes around 30 seconds to be ready. You can poll the Retrieve Payout Report endpoint to get the current status of the payout report. You must provide the reportId of the payout report in the request body.

​

Example Request Payload

{ 
	"reportId": "5f9b5f9b-5f9b-5f9b-5f9b-5f9b5f9b5f9b" 
}

As a response, you will receive the payout report’s current status.

​

Example Response Payload

{
    "status": "pending"
}

​

Download the report

The status will switch to ’ succeeded ’ as soon as the payout report is ready. Use the Download Payout Report endpoint to download the payout report. You need to provide the reportId of the payout report in the request path and specify the format of the Download. You can receive the report in JSON format or as a CSV file.

​

Example Request Payload

{ 
  "reportId": "5f9b5f9b-5f9b-5f9b-5f9b-5f9b5f9b5f9b", 
 	"format": "json"
}

You will receive the report in the JSON response if you specify JSON as the format. The report will contain a list of all payouts made to your bank account. Each payout will have the id of the payout, the availableAt date, the amount, and a list of all orders included in the payout.

​

Example Response Payload

{
    "payouts": [
        {
            "id": "po_123456789",
            "availableAt": 1638972800,
            "amount": 1000.00,
            "transactions": [
                {
                    "orderId": "Shop-99999",
                    "gross": 1000.00,
                    "net": 900.00,
                    "fee": 100.00,
                    "currency": "EUR",
                    "reportingCategory": "charge",
                    "description": ""
                }
            ]
        }
    ]
}

If the report is not ready, you will receive a status400 response.