Ivy Docs

Explore our guides and examples to integrate Ivy.

Overview

Ivy Dashboard

Get to know the core concepts of the Ivy API.

Concepts

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 (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

Allow your customers to transfer money from their bank account manually

Manual Bank Transfer

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

Access banking data securely through our Data API

Introduction

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

The Account Holder object and its endpoints

Account Holders

Balances

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

List banks

Search a bank

Retrieve a bank

Create a checkout session

Retrieve a checkout session

Expire a checkout session

Create a customer

Retrieve a customer

Search customers

Retrieve an order

Create an order

Expire an order

Create a charge

Revoke a mandate

Retrieve a mandate

Lookup a mandate

Retrieve your capabilities

Create a subaccount

Retrieve a subaccount

Create multiple refunds

Create one refund

Create a payout report

Download a payout report

Retrieve a payout report status

Retrieve account balance

Create a customer payout

List customer payouts

Retrieve a customer payout

Retrieve exchange rate

Trigger a specific webhook

Create a webhook subscription

Delete a webhook subscription

List webhook subscriptions

Trigger a test webhook

Update a webhook subscription

Test

Merchant updated

Merchant app updated

Order created

Order updated

Refund succeeded

Refund failed

The requested payout report

Data session completed

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

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

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

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

Retrieve a Checkout Session and its details by Ivy id.

Retrieve 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

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

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.

Update certain fields of the specified order.

Update an order

Creates a Direct Debit Charge with a valid mandate.

Create a Charge

Revokes a Direct Debit Mandate with a valid mandate id.

Revoke a Mandate

Retrieves a direct debit mandate with mandate id.

Retrieve a Mandate

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

Lookup a Mandate

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

Retrieve your Capabilities

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

Create a Subaccount

Retrieve a Subaccount

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

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

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

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

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

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

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

Trigger a Test Webhook

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.

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

Merchant Updated

Merchant App Updated

Order Created

Order Updated

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

Refund Succeeded

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

Refund Failed

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

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

Getting Started

Bank

Checkout

Customer

Order

Charge

Mandate

Capabilities

Subaccount

Refund

Payout Report

Banking

Customer Payout

FX

Get payout details for a exsiting payout