Overview
Basic concepts about integrating Ivy into your application
Integration Overview
You can integrate Ivy Payments with minimum effort by creating a Checkout Session. The process provides a seamless user experience:
- Create a Checkout Session to get a unique URL
- Redirect your user to this URL to complete payment
- Receive the user back at your application after payment completion
The entire payment journey is handled within the Ivy Checkout interface.
Creating a Checkout Session
Basic Requirements
To create a CheckoutSession, send a POST request to the Create a CheckoutSession endpoint. Here are the essential parameters needed:
The price object containing the payment amount and currency.
A unique reference ID, typically your internal transfer ID.
The URL where users are redirected after successful payment completion.
The URL where users are redirected if they close or cancel the Checkout.
Optional but recommended to set as true. When false, users must provide
their email before payment. See Guest Mode below for details.
Optional. Choose between white_label or sustainable. Defaults to
sustainable. Set to white_label for a clean flow without user incentives.
Example Implementation
Response Fields
The API response includes these key fields:
The URL where you should redirect your user to complete payment.
A unique Ivy identifier for this checkout session.
Your provided reference ID, useful for tracking the transaction in your system.
For a complete list of response parameters, see the API Reference.
Payment Flow
User Redirection
After receiving the API response, redirect your user to the provided redirectUrl. They’ll complete their payment in the Ivy Checkout interface.
Status Tracking
When a user completes payment successfully:
- The
checkoutSessionstatus is closed - A new
orderobject is created containing:- All fields from the original
checkoutSession - An additional
statusfield tracking payment progress
- All fields from the original
Users are redirected with these query parameters:
Your original reference ID from checkout creation
The Ivy order ID (only included for successful payments)
Set up Webhooks to receive real-time status updates. See Payment Status for detailed tracking information.
Settlement Options
Settlement with Ivy
Ideal for e-commerce and marketplace applications. Ivy handles:
- Receiving incoming payments
- Batched transfers to your bank account
- User payouts and refunds
Learn more in our Settlement Account section.
Direct Settlement
Suited for PSPs, top-up payments, and P2P transfers. You maintain control over:
- Destination bank account for incoming funds
- User payout process
- Settlement timing and batching
Advanced Configuration
Payment Scheme Selection
Control the speed vs. cost tradeoff of transfers:
instant_only: Use only instant payment railsinstant_preferred: Prioritize instant rails but allow fallbackstandard: Use only standard (free but slower) rails
If not specified, the default scheme is determined by your merchant dashboard settings.
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.
With guest mode off, returning users can either: - Stay logged in between sessions - Log in again to skip bank selection
Next Steps
- Learn about Status Overview