Introduction

You can integrate Ivy Payments with minimum integration effort by creating a Checkout Session. You receive a Checkout URL where you can send the user to pay. The whole user journey is handled within the Checkout. After a successful / unsuccessful Checkout, the user will be redirected back to your App.

Create a CheckoutSession with the Ivy API

To create a CheckoutSession, you need to send a POST request to the Create a CheckoutSession endpoint of the Ivy API. At a minimum, you can create a checkout with the following data:

Field	Type	Description
`price`	`object`	The price object including the amount to be paid and the currency.
`referenceId`	`string`	A unique reference ID, usually your internal transfer ID.
`successCallbackUrl`	`string`	The user will be redirected to this URL after they successfully finish the payment.
`errorCallbackUrl`	`string`	The user will be redirected to this URL when they close the Checkout.
`guest`	`boolean`	Actually optional. We recommend to set this to `true` . If set to `false`, users are required to submit their email before the payment. See below for more info.
`incentiveMode`	`string`	Actually optional. One of `white_label`, `sustainable`. On default `sustainable`. Set to `white_label` for a clean flow without any user incentives.

Example Payload

// Recommended Configuration
{
  "price": {
    "totalNet": 100,
    "vat": 19,
    "total": 119,
    "currency": "EUR"
  },
  "referenceId": "my-unique-reference-id",
  "successCallbackUrl": "https://my-website.com/success",
  "errorCallbackUrl": "https://my-website.com/try-again",
  "guest": true,
  "incentiveMode": "white_label"
}

The response will include the data below:

Field	Type	Description
`redirectUrl`	`string`	The URL to which you need to redirect the user.
`id`	`string`	The unique Ivy id for this checkoutSession.
`referenceId`	`string`	A unique reference Id, e.g. your internal transfer ID.
`...`	`...`	For all other response parameters, see https://docs.getivy.de/reference/checkoutsessioncreate

Redirect the User to the Checkout URL

After you receive the response from the Ivy API, you need to redirect the user to the redirectUrl that you received in the response.

They can complete the payment in the Checkout. If you want to enhance the look & feel of the Checkout, have a look at our Web SDK.

Retrieve the Payment Status

After a user successfully finished a payment, Ivy closes the checkoutSession and creates an order object with the exact same fields as the checkoutSession and an additional statusfield. An order is the Ivy equivalent for one payment.

The user will be redirected to the successCallbackUrl if they successfully completed the payment, and to the errorCallbackUrl if they closed the Checkout. The following data is attached as query parameters to both URLs.

Field	Type	Description
`referenceId`	`string`	The referenceId that you provided when creating the Checkout
`order-id`	`string`	Optional. The Ivy id of the newly created Ivy order in the case of successful payment.

In addition, you can set up Webhooks to receive status updates for the created order. Find more detailed info on this in the Payment Status section.

Settlement

Generally, there are two different ways to integrate Ivy Payments into your application:

Settlement with Ivy (e.g. e-commerce, marketplace)

With this integration, you can use our payment solution without having to worry about the settlement process. We will take care of the receiving money and transfer it to your bank account in batched payouts. Also, Ivy can handle all payouts to users such as refunds or player payouts. More information can be found in the Settlement Account section.

Direct Settlement (e.g. PSPs, top-up payments, P2P payments)

With this integration, you can use our payment solution and handle the settlement process yourself. This means that you will have control over the bank account where the money is transferred to and will handle payouts to users yourself. Typical Use cases for this are top-up payments for wallets, neobanks, or P2P payments.

Payment Scheme Selection

Specifies the payment scheme. instant_only restricts payments to instant rails, excluding banks that do not support it. instant_preferred prioritizes instant rails but will fall back to standard rails if the bank does not support instant payments. standard selects only cost-free but potentially slower bank rails for the transfer. If not specified, the default is taken from the merchant dashboard.

Guest Mode

When activating guest mode, users pay without entering their email during the payment flow. This is recommended if you mainly have non-recurring users. If turned off, recurring users will either stay logged in or can login again to skip the bank selection.

To activate Ivy Checkout with guest mode, set the parameter guest to true when creating a checkoutSession.