Introduction
Basic concepts about integrating Ivy into your application
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 status
field. 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.
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 transfered to and will handle payouts to users yourself. Typical Use cases for this are top-up payments for wallets, neobanks, or P2P payments.
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
.
Updated 9 months ago