Introduction

Ivy Docs

What Ivy is, what you can do, and how to get up and running fast.

Welcome to Ivy

Understand the main building blocks of the Ivy API: Payin, Payout, FX, and Account.

Core Concepts

Dashboard

Receive event notifications from Ivy through POST requests to your webhook endpoint.

Webhooks

Use test mode to test your Ivy integration before going live with payments.

Test Mode

Introduction to payin flows and concepts.

Overview

Receive funds into your Ivy account at any time via IBAN or Wallet address.

Deposits (coming soon)

Introduction to payout flows and concepts.

Send money anywhere — customers, partners, suppliers, or external accounts.

Payouts

Refund all or part of an order quickly and reliably.

Refunds

How to settle your Ivy account balance to your external bank or wallet.

Beneficiary Payouts

Hold fiat and stablecoin funds in your Ivy account

Balances

Get a report of all payouts and settlements made to your account

Reporting

Virtual Accounts (Coming Soon)

How to settle your Ivy balance in a different currency.

FX Beneficiary Payouts

Use the FX API to swap any of your currency balances with Ivy - regardless stablecoin or fiat.

Standalone FX API (Coming Soon)

Access banking data securely through our Data API

Learn how to integrate the Data API into your application to retrieve account data from your customers' banks

Step by Step

The Data Session object and its endpoints

Data Sessions

Accounts

Transactions

The Ivy API uses API Keys to authenticate requests. You can view and manage your API Key in the Ivy Dashboard.

Authentication

Learn how to specify which Ivy API version to use whenever you make a request to the Ivy API.

Versioning

Most updatable Ivy objects have a Metadata parameter. You can use this parameter to attach arbitrary key-value data to these Ivy objects.

Metadata

Ivy's API utilizes standard HTTP response codes to provide information about the success or failure of API requests.

Errors

Retrieve a Subaccount

Create a Subaccount which can be used to reconcile orders, refunds and payouts more easily.

Create a Subaccount

Creates a Checkout Session for the merchant corresponding to the given API key. See [the guide](https://docs.getivy.de/docs/payment-integration) for more information.

Create a Checkout Session

Expire a Checkout Session by Ivy id. By expiring a Checkout Session, users will not be able to access this Checkout Session anymore.

Expire a Checkout Session

Retrieve a Checkout Session and its details by Ivy id.

Retrieve a Checkout Session

Create a new Customer representing your Customers. You can use the Customer to simplify the checkout process for returning journeys.

Create a Customer

Retrieve a Customer

Search for customers you have previously created using filters, e.g. by email.

Search Customers

You can retrieve a list of banks by a given search string. If the search string is empty (""), a default list of banks is returned. On top, you can filter results by group, capability and market.

Search a Bank

Get a list of banks. You can filter by group, capability and market.

List Banks

Retrieve a bank object by its id. The id is a unique identifier of the bank within Ivy.

Retrieve a Bank

Retrieve the current exchange rate for a given currency pair. The rate is not guaranteed for any following transactions.

Retrieve Exchange Rate

Retrieve the details of a past fx transfer using the fxId.

Retrieve FX details

Retrieve details of an order. You can retrieve the order by passing either the internal Ivy order id or the `referenceId` you specified when creating a Checkout Session to the `id` field.

Retrieve an Order

Create a new order. By creating a new order, you will create a new settlement destination which you can use to settle expected incoming payments efficiently. After creating the order, Ivy provides you with a destination for the expected incoming payment. As soon as a payment with the same details arrives, Ivy will update the status of the order.

Create an Order

Manually expire an order before its natural expiration time.

Expire an Order

Retrieve the capabilities of your Ivy account. The capabilities are broken down by market and by product.

Retrieve your Capabilities

Initiates a batch refund for all provided orders. The orders can be specified either by Ivy's internal id ("orderId") or by id provided by the merchant ("referenceId"). If only a partial amount should be refunded the desired amount can be set with the "amount" parameter. Additional information regarding the refund can be provided through the "description" parameter.

Create multiple Refunds

Initiates a refund for the specified order. The order can be specified either by Ivy's internal `orderId` or by the `referenceId` provided by the merchant during checkout creation. If the refund should only be partial, you can specifiy this with the `amount` parameter.

Create one Refund

Create a Payout Report for a given timerange. A Payout Report is generated async. Please follow [this guide](https://docs.getivy.de/docs/payout-report-1) to learn more in detail.

Create a Payout Report

Download the actual Payout Report once the creation succeeded with this endpoint.

Download a Payout Report

Retrieve the status of an existing Payout Report. Use this endpoint to poll for the status before downloading a Payout Report.

Retrieve a Payout Report status

Creates a Direct Debit Charge with a valid mandate.

Create a Charge

Returns a Direct Debit Mandate when a valid mandate referenceId is given.

Lookup a Mandate

Retrieves a direct debit mandate with mandate id.

Retrieve a Mandate

Revokes a Direct Debit Mandate with a valid mandate id.

Revoke a Mandate

Retrieve the balance of your Ivy account. The balance is the money currently available on your Ivy account. It is broken down by currency.

Retrieve Account Balance

Perform a payout. This endpoint will be deprecated in favor of the new payout endpoint that will support more payout types.

Performs a Merchant Payout on all supported currencies

Retrieve a payout

List payouts

Create a payout

This endpoint allows you to trigger a specific webhook by its ID.

Trigger a specific webhook

Can be triggered with `/merchant/app/send-test-webhook` to test the integration

Test

Order Created

Order Updated

Merchant Updated

A refund initiated with `/merchant/payment/refund` succeeded

Refund Succeeded

A refund initiated with `/merchant/payment/refund` failed

Refund Failed

User Payout Initiated

User Payout Paid

User Payout Failed

Payout Report Requested

Data Session Completed

Checkout Session Created

Checkout Session Updated

Checkout Session Expired

Checkout Session Completed

Merchant Payout Created

Merchant Payout Updated

Mandate Setup Started

Mandate Setup Succeeded

Mandate Setup Failed

Mandate Revoked

Payout Initiated

Payout Paid

Payout Failed

Sends a test ping to verify webhook subscription endpoint connectivity.

Ping a webhook subscription

Lists all webhook subscriptions that are registered for the merchant. The results are paginated and provided in chronological order.

List webhook subscriptions

Creates a webhook subscription that sends various events from Ivy to a specified url. There can be multiple subscriptions per app.

Create a webhook subscription

Delete a webhook subscription

Updates the url or subcribed to events for a webhook subscription. This can be used via the app or via the API by providing an API key.

Update a webhook subscription

Explore our guides and examples to integrate Ivy.

Ivy Dashboard

Get to know the core concepts of the Ivy API.

Concepts

Test Mode (Sandbox)

Everything you need to let customers pay in money with instant bank transfers

Understand the lifecycle of the Ivy payment status

Status Flow

Boost conversion by simplifying your customers' checkout experience

Remember Me

Setup and use Mandates to charge users multiple times

Recurring Payments

Test your integration

Customer Payouts

Customer Refunds

Settle your available balance into your external bank account or wallet

Settlements

Embed Ivy Checkout directly in your website with our iframe and modal integration

Widget Integration

Download bank logos for use in your checkout page

Bank logo assets

The Account Holder object and its endpoints

Account Holders

List banks

Retrieve a bank

This endpoint allows merchants to create a new customer with email

Create a new customer

This endpoint allows merchants to retrieve the customer info by id

Retrieve the customer by id

Search for customers you have previously created using filters, e.g. by email

Search customers

Retrieve an order

Update certain fields of the specified order.

Update an order

Initiates a batch refund for all provided orders. The orders can be specified either by Ivy\'s internal id ("orderId") or by id provided by the merchant ("referenceId"). If only a partial amount should be refunded the desired amount can be set with the "amount" parameter. Additional information regarding the refund can be provided through the "description" parameter.

Initiates a refund for the specified order. The order can be specified either by Ivy\'s internal `orderId` or by the `referenceId` provided by the merchant during checkout creation. If the refund should only be partial, you can specifiy this with the `amount` parameter.

Create a Customer Payout to a customer's bank account for withdrawals or similar purposes.

Create a Customer Payout

List all Customer Payouts made by this merchant account.

List Customer Payouts

Retrieve a Customer Payout

Trigger the webhook event "test" for the specified webhook subscription.

Trigger a Test Webhook

Merchant App Updated

The result of the payout report is sent once the fetching of the report is finished.

The requested payout report

The result of the completed data session is sent once the user completes the data session

Getting Started

Subaccount

Checkout

Customer

Bank

FX

Order

Capabilities

Refund

Payout Report

Charge

Mandate

Banking

Payout

Introduction