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

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:
​
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 2x-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

​
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:
​
referenceId
string
required
Your original reference ID from checkout creation.
​
order-id
string
The Ivy order ID (only included for successful payments)

​
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
Set up Webhooks to receive real-time status updates. See Payment Status for detailed tracking information.

​
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. 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 merchant dashboard settings.