HTTP Status Code Summary

Error Attributes

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

Errors

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

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

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

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

Metadata

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

List banks

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.

Retrieve a bank

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

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

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.

Trigger a specific webhook

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

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

List webhook subscriptions

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.

Update a webhook subscription

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

Test

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 requested payout report

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

Data Session Completed

Guides

Data API

API Reference

Dashboard

Contact Us

Best practices on how to integrate Ivy’s one-time payments into your e-commerce checkout or financial service deposit screen.

One-time payments

Best practices on how to integrate Ivy’s recurring payments into your e-commerce checkout or financial service deposit screen

Status Code	Description
200 - OK	The request was successful, and everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to a missing required parameter.
401 - Unauthenticated	The request was not authorized due to an invalid or missing API Key.
403 - Authorization	The provided API Key doesn’t have the necessary permissions to perform the request.
404 - Not Found	The requested resource does not exist.
409 - Conflict	The request conflicts with another request, often due to using the same idempotent key.
423 - Locked	The requested resource is temporarily locked due to an ongoing operation. Please wait for the resource to become available again before retrying.
429 - Too Many Requests	Too many requests were made to the API in a short period. We recommend implementing exponential backoff for your requests.
500 - Internal Server Error	This code indicates a rare issue on Ivy’s servers: something went wrong on our end.

Getting Started

Bank

Checkout

Customer

Order

Charge

Mandate

Capabilities

Subaccount

Refund

Payout Report

Balance

Customer Payout

​HTTP Status Code Summary

​Error Attributes

HTTP Status Code Summary

Error Attributes