Integration Flow

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 has a redirectUrl parameter attached to it which you can use to either redirect the customer to the Ivy hosted payment page or to show the Ivy Widget.

​

High Level Flow

1. Create a Checkout Session to get a unique redirectUrl

2. Redirect your customer to this URL. The payment journey is handled within the Ivy Checkout Page.

3. Receive the customer back at your application after payment completion or cancellation

4. Listen to webhooks to track the status of the payment

​

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:

​

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:

​

Payment Flow

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

​

Redirect

Redirect your customer to the redirectUrl provided in the API response. 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:

​

iFrame

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

​

React SDK

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

​

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

​

Settlement

Ivy holds and creates a collection account for you. You can use this for multiple purposes such as customer payouts, refunds, onramping.

Learn more in our Accounts.

​

Advanced Configuration

​

Payment Scheme Selection

Ivy is connected to all instant payment rails in each country, e.g. SEPA Instant for EUR, Faster Payments for GBP, Elixir Express for PLN, RIX Instant for SEK.

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