The main concept of instant bank transfers is the Checkout Session. Create a new Checkout Session for each payment attempt of your customer. Each Checkout Session returns a redirectUrl where users go to complete the payment.

​
High Level Flow

  1. Create a Checkout Session: Submit the relevant payment parameters to initiate a checkout session and receive a unique redirectUrl.
  2. Redirect the User to Ivy: Use the redirectUrl to send users to the Ivy-hosted bank selection and payment confirmation screen flow.
  3. Return to Your Environment: After the user completes the payment at their bank, they will be redirected back to your site/application to complete their journey.
  4. Status Tracking: Configure webhooks to receive real-time payment updates, including settlement of the payment to your Ivy collection account.

Ivy Instant Bank transfer Flow

​
1. Creating a Checkout Session

​
Basic Request Parameters

To create a CheckoutSession, send a POST request to the Create a CheckoutSession endpoint. Here are the essential parameters needed:
​
price
object
required
The price object containing the payment amount and currency.
​
referenceId
string
required
A unique reference ID, typically your internal payment ID.
​
successCallbackUrl
string
required
The URL where customers are redirected after successful payment completion.
​
errorCallbackUrl
string
required
The URL where customers are redirected if they close or cancel the Checkout.
Pass a customer email to enable the Remember Me feature. This usually boosts conversion rates by 2-5x.

​
Example Payload

{
  "price": {
    "total": 119,
    "currency": "EUR"
  },
  "referenceId": "my-unique-reference-id",
  "successCallbackUrl": "https://my-website.com/success",
  "errorCallbackUrl": "https://my-website.com/try-again",
}

​
Response Fields

The API response includes these key fields:
​
redirectUrl
string
required
The URL where you should redirect your user to complete payment.
​
id
string
required
A unique Ivy identifier for this checkout session.
​
referenceId
string
required
Your provided reference ID, useful for tracking the transaction in your system.
For a complete list of Parameters, please check out the API Reference

​
2. Redirect the User to Ivy

After receiving the API response, redirect your user to the redirectUrl. They’ll complete their payment in the Ivy Checkout interface.

​
iFrame

You can embed Ivy as an iFrame in your page. Check out the Client Integration guide for more.

​
React SDK

We offer a React SDK for your client integration. Check out the README for usage instructions.

​
3. Return to Your Environment

You will receive them back at the successCallbackUrl or errorCallbackUrl after the payment is completed or cancelled. Customers are redirected with these query parameters attached to the success or error callback URL you defined when creating the checkout session:
​
referenceId
string
required
Your original reference ID from checkout creation.
​
order-id
string
The Ivy order ID (only included for successful payments)
​
user_closed
boolean
Indicates whether the user explicitly closed the Ivy checkout using the ‘X’ -> ‘Yes, cancel’ flow.
When user_closed is true, you can optionally expire the checkout session using the Expire a Checkout Session endpoint. This triggers webhooks which can be used update your internal status accordingly.

​
4. Status Tracking

When a customer completes payment successfully:
  1. The checkoutSession status is set to closed
  2. A new order object is created containing:
    • All fields from the original checkoutSession
    • An additional status field tracking payment progress
Set up Webhooks to receive real-time status updates. See Payment Status for details on possible payment journeys and statuses.

​
Settlement

When Ivy holds a collection account for you, you will also be able to receive a paid status when payments have settled. Learn more in Accounts.
As the core concept of instant bank transfers your checkout session creation requests are key to optimise your users experience. Using the below configurations can help optimise the speed, available banks, and user journey.

​
Payment Scheme Selection

Ivy is connected to all instant payment rails in each country, e.g. SEPA Instant for EUR, Faster Payments for GBP. Some banks charge their customers fees for using instant bank transfers. Ivy always uses the instant payment rail available for each bank if there are no fees charged to customers. You can enforce to always use the instant payment rail via the API Control the speed vs. cost tradeoff of payments:
  • instant_only: Use only instant payment rails
  • instant_preferred: Prioritize instant payment rails but allow fallback to standard
  • standard: Use only standard (free but slower) rails
If not specified, the default scheme is determined by your application configuration. Speak to your account manager to change this.

​
Default Market Selection

Set the default market that will appear to users in the bank selection screen. Always pre-select the most relevant market for your customers.
​
market
string
required
ISO 3166-1 alpha-2 country code (e.g., “DE” for Germany, “GB” for United Kingdom). When provided, the checkout will display banks from this market first. If not provided, Ivy will automatically detect the market based on the user’s IP address.
The market parameter is not relevant if you’re using prefill.bankId to pre-select a specific bank for the customer.

​
Customer Object

Provide data to enable the Remember Me feature to give a smoother journey for returning users. Provide either the email address or the pre-defined customer id.
​
customer
object
required
Customer information to enable the Remember Me feature.
​
customer.email
string
Customer’s email address. Used for customer recognition and to enable the Remember Me feature.
​
customer.id
string
Pre-defined customer ID from Ivy. Use this if you’ve already created a customer via the Customer API.
Make sure to pass the email address in the customer.email field, not in the prefill section. This ensures proper customer recognition for the Remember Me feature.
Passing customer id or email can boost conversion rates by over 20%.
{
  "price": {
    "total": 119,
    "currency": "EUR"
  },
  "referenceId": "my-unique-reference-id",
  "successCallbackUrl": "https://my-website.com/success",
  "errorCallbackUrl": "https://my-website.com/try-again",
  "paymentSchemeSelection": "instant_preferred",
  "market": "DE",
  "customer": {
    "email": "customer@example.com"
  }
}