Overview

The main concept of customer payins with Ivy is the Checkout Session. Create a new Checkout Session for each of your customer payins. 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 embed Ivy as an iFrame.

The Flow of Integration is the following:

1. Create a Checkout Session to get a unique redirectUrl

2. Redirect your customer to this URL to complete the payment

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

The entire payment journey is handled within the Ivy Checkout Page.

​

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

​

Customer Redirection

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

​

Alternative Client Integrations

iframe

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

Client-side SDKS

We are currently working on a React SDK. If you have any wishes for other SDKs, please reach out to us!

​

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

Customers are redirected with these query parameters attached to the success or error callback URL you defined when creating the checkout session.

​

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 Collection Guides.

​

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

​

Guest Mode

Guest mode simplifies the payment process for non-recurring users by removing the email requirement.

To enable guest mode, set guest: true when creating your checkout session.

​

Next Steps

• Learn about Status Overview