Create a Checkout Session
Creates a Checkout Session for the merchant corresponding to the given API key. See the guide for more information.
Authorizations
Body
The price to be paid by the user. All amounts are in decimals, i.e. 10.23 represents EUR 10.23. Any amount of decimal places can be provided on initialization, but the actual transfer amount is rounded to 2 decimal places, as this is the format accepted by most banks.
An internal reference id which will be stored with the checkout & corresponding order. Needs to be unique per shop per order and can be up to 200 characters. We recommend to use your internal order id here.
200The billing address of the user. Required when handshake=true.
Only applicable for express Checkouts. Complete Callback requests will be sent to this URL.
The Epoch time in seconds at which the Checkout Session was created. By default, time of Checkout creation at Ivy.
The customer of the merchant.
False by default. If set to true, customers cannot modify the pre-selected bank from prefill.bankId.
Relevant for e-commerce only. The already applied discounts of the Checkout. Discounts will be shown in the lineItems after Checkout Session creation.
The customer facing id. This id is displayed to the user during the checkout and in the merchant dashboard.
200Required if not set in the dashboard. Users will be redirected here after an unsuccessful Payment attempt.
The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 1 hour from creation.
Relevant for e-commerce only. If true, the checkout session will be an express checkout session.
False by default. Set to true to allow customers skip email input and jump directly to their bank login. For express Checkout Sessions this is always false.
Deprecated. If true, the order must be confirmed through the merchant with an additional complete callback endpoint. Always true for express sessions.
The incentive mode of the checkout session. For any use-case apart from e-commerce, please use white_label as the value. If set to white_label, the checkout session will be white labeled. If set to sustainable, the checkout session will contain sustainable incentives for users.
white_label, sustainable Relevant for e-commerce only. The line items of the Checkout.
The locale of the Checkout. If provided, the Checkout will be displayed in the given language. Users can change the language in the Checkout. If not provided, the language of the Checkout is determined by the browser's language.
de, nl, en, fr, es, it, pt, sv, pl, sk The mandate setup for the payment. Relevant for Ivy on File
ISO 3166-1 alpha-2 country code. The market where the user of the Checkout is located. If provided, the Checkout will display the market's banks first. Not relevant if prefill.bankId is provided.
AF, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, MK, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AX, BQ, CW, GG, IM, JE, ME, BL, MF, RS, SX, SS, XK Any data which will be stored and returned for this checkout session and corresponding order. See here for more info.
settlement: The payment is initially settled into a virtual account. The funds are then disbursed in batches to the merchant. Refunds are instantly processed from the virtual account.direct: The payment will be settled to the specifiedsettlementDestinationaccount.settlementDestinationis required ifpaymentModeisdirect.
settlement, direct The scheme selection for the payment. instant_only enforces instant payments, meaning no banks that do not support it can be selected. instant_preferred means that the payment is done via instant rails. It will fallback to standard rails, if not supported by the bank. Standard means that only cost-free, but potentially slower bank rails are used for the transfer. Defaults to value set on merchant dashboard if not provided.
instant_preferred, standard, instant_only The shop-plugin integration version e.g. shopware-6.4.0.
Use this to prefill data of the user in the Checkout.
Only applicable for express Checkouts. Quote Callback requests will be sent to this URL.
Only applicable for express Checkout Sessions. The given fields will be required input within the Ivy express Checkout.
If set to true, a risk check will be performed. This is currently in beta and defaults to true.
The settlement destination of the payment. If not provided, the financial address of the merchant's direct payout destination will be used with a randomly generated payment reference.
The shipping methods of the Checkout.
The logo of the shop provided as a URL.
Relevant for PSPs only. The subaccount id of the relevant subaccount who owns the payment. You can create new subaccounts here
Required if not set in the dashboard. Users will be redirected here after a successful Payment attempt.
Deprecated in favor of metadata. A token which is returned as a query parameter of the success callback url.
Response
The markets where the user of the Checkout can select banks from.
AF, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, MK, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AX, BQ, CW, GG, IM, JE, ME, BL, MF, RS, SX, SS, XK The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 1 hour from creation.
The unique identifier of the Checkout within Ivy.
Use merchant.appId instead
settlement: The payment is initially settled into a virtual account. The funds are then disbursed in batches to the merchant. Refunds are instantly processed from the virtual account.direct: The payment will be settled to the specifiedsettlementDestinationaccount.settlementDestinationis required ifpaymentModeisdirect.
settlement, direct The price to be paid by the user. All amounts are in decimals, i.e. 10.23 represents EUR 10.23. Any amount of decimal places can be provided on initialization, but the actual transfer amount is rounded to 2 decimal places, as this is the format accepted by most banks.
Only applicable for express Checkout Sessions. The given fields will be required input within the Ivy express Checkout.
open, closed, expired The billing address of the customer. Required when handshake=true.
Only applicable for express Checkouts. Complete Callback requests will be sent to this URL.
The Epoch time in seconds at which the Checkout Session was created. By default, time of Checkout creation at Ivy.
False by default. If set to true, customers cannot modify the pre-selected bank from prefill.bankId.
The customer facing id. This id is displayed to the user during the checkout and in the merchant dashboard.
200Required if not set in the dashboard. Users will be redirected here after an unsuccessful Payment attempt.
False by default. If set to true, the Checkout is displayed in express mode.
False by default. If set to true, customers skip email input and jump directly to their bank login. For express Checkout Sessions this is always false.
If true, the order must be confirmed through the merchant with an additional complete callback endpoint. Always true for express sessions.
The incentive mode of the checkout session. For any use-case apart from e-commerce, please use white_label as the value. If set to white_label, the checkout session will be white labeled. If set to sustainable, the checkout session will contain sustainable incentives for users.
white_label, sustainable The locale of the Checkout. If provided, the Checkout will be displayed in the given language. Users can change the language in the Checkout. If not provided, the language of the Checkout is determined by the browser's language.
de, nl, en, fr, es, it, pt, sv, pl, sk ISO 3166-1 alpha-2 country code. The market where the user of the Checkout is located. If provided, the Checkout will display the market's banks first. Not relevant if prefill.bankId is provided.
AF, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, MK, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AX, BQ, CW, GG, IM, JE, ME, BL, MF, RS, SX, SS, XK Any data which will be stored and returned for this checkout session and corresponding order. See here for more info.
The shop-plugin version.
Use this to prefill data of the user in the Checkout.
Only applicable for express Checkouts. Quote Callback requests will be sent to this URL.
An internal reference id which will be stored with the checkout & corresponding order. Needs to be unique per shop per order and can be up to 200 characters. We recommend to use your internal order id here.
200The logo of the shop provided as a URL.
Required if not set in the dashboard. Users will be redirected here after a successful Payment attempt.