Skip to main content

Checkout API

POST/rest/checkouts

Checkout API is used to create checkout sessions where merchants don't have their own checkout page. This way, merchants can easily share payment links with their customers, where they can select one of the available payment methods and fill in their information to pay for a product or a service.

Checkout API is a low-code solution for merchants to accept payments from their customers. When creating a checkout link, configured payment methods in your merchant account will be available for the customers to choose from — including Google Pay, Apple Pay, and Click to Pay if enabled.

The hosted checkout page is available in multiple languages. See Locales for the full list.

Checkout API Request​

merchant_nameStringrequired
Name of the merchant displayed on the checkout page
order_idStringrequired
Any alphanumeric string to identify the Merchant's order
referenceString
Reference for the checkout session
descriptionString
Description about the product or service
currencyStringrequired
3 letter currency code
recurringInteger
Enable recurring context for the checkout (0 or 1). See Recurring payments below
recurring_optionalInteger
Let the payer choose whether to save payment details for future recurring charges (0 or 1). Requires recurring: 1. See Recurring payments below
amountFloatrequired
Amount of the transaction
amount_taxesFloat
Tax amount
amount_shippingFloat
Shipping amount
amount_feesFloat
Fee amount included in the total
total_amountFloatrequired
Total amount including taxes and shipping
copyright_textString
Copyright text displayed on the checkout page footer
copyright_linkString
URL linked from the copyright text
imprint_urlString
URL to the merchant imprint page
data_privacy_urlString
URL to the merchant data privacy policy
terms_and_conditions_urlString
URL to the merchant terms and conditions
collect_dobInteger
Whether to collect date of birth (0 or 1)
collect_phoneInteger
Whether to collect phone number (0 or 1)
collect_genderInteger
Whether to collect gender (0 or 1)
collect_shipping_addressInteger
Whether to collect shipping address (0 or 1)
collect_billing_addressInteger
Whether to collect billing address (0 or 1)
display_transaction_detailsInteger
Whether to display transaction details (0 or 1)
display_manual_payment_instruction_to_customerInteger
Whether to display manual payment instructions (0 or 1)
payment_instruction_merchant_account_holderString
Merchant account holder name for manual payment instructions
payment_instruction_merchant_ibanString
Merchant IBAN for manual payment instructions
payment_instruction_merchant_bicString
Merchant BIC for manual payment instructions
success_urlStringrequired
Where to redirect the user after a successful transaction
error_urlStringrequired
Where to redirect the user after a failed transaction
postback_urlStringrequired
The URL for updates about transaction status are posted
Example Request
POST /rest/checkouts
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"merchant_name": "Merchant Name",
"order_id": "ORD001",
"reference": "Some reference",
"description": "Description about the product or service",
"currency": "EUR",
"recurring": 0,
"recurring_optional": 0,
"amount": 10,
"amount_taxes": 2,
"amount_shipping": 1,
"amount_fees": 0,
"total_amount": 13,
"copyright_text": "Merchant Name",
"copyright_link": "https://merchant.example.com",
"imprint_url": "https://merchant.example.com/imprint",
"data_privacy_url": "https://merchant.example.com/privacy",
"terms_and_conditions_url": "https://merchant.example.com/terms",
"collect_dob": 0,
"collect_phone": 1,
"collect_gender": 0,
"collect_shipping_address": 0,
"collect_billing_address": 1,
"display_transaction_details": 1,
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com",
"postback_url": "https://your-postback.url.com"
}

Prefill Customer Info Parameters​

You can optionally prefill customer information by including a prefill_customer_info object:

prefill_customer_info.emailString
Customer email
prefill_customer_info.phoneString
Customer phone number
prefill_customer_info.companyString
Company name
prefill_customer_info.first_nameString
Customer first name
prefill_customer_info.last_nameString
Customer last name
prefill_customer_info.addressString
Street address
prefill_customer_info.address2String
Complementary address
prefill_customer_info.cityString
City
prefill_customer_info.stateString
State
prefill_customer_info.postal_codeString
Postal code
prefill_customer_info.countryString
Country code (ISO 3166-1 alpha-2)
prefill_customer_info.ibanString
Customer IBAN (for bank account prefill)
prefill_customer_info.bicString
Customer BIC (for bank account prefill)
prefill_customer_info.account_holderString
Bank account holder name
prefill_customer_info.sepa_mandateString
Mandate reference for bank-based payments
Prefill Customer Info Fields
{
"prefill_customer_info": {
  "email": "john.doe@email.com",
  "phone": "+49 30 1234567",
  "company": "My Company",
  "first_name": "John",
  "last_name": "Doe",
  "address": "Rosenthalerstr. 8",
  "address2": "Apt 3",
  "city": "Berlin",
  "state": "Berlin",
  "postal_code": "10178",
  "country": "DE",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "account_holder": "John Doe",
  "sepa_mandate": "mandate-reference"
}
}

Recurring payments​

Use recurring and recurring_optional to control how recurring billing works on the hosted checkout page.

Forced recurring mode​

Set recurring: 1 and recurring_optional: 0:

  • Only payment methods that support recurring payments are shown.
  • Every completed payment is created as a recurring transaction.
  • Use this when the checkout is always for a subscription or when you will trigger follow-up charges via the Payment API using original_transaction_id.

Optional recurring (payer opt-in)​

Set both recurring: 1 and recurring_optional: 1:

  • All payment methods configured for your merchant account are shown.
  • Recurring-capable methods display a recurring badge.
  • The payer can opt in on the review step to save payment details for future recurring charges.
  • If the payer does not opt in, the payment is processed as a one-time transaction.

recurring_optional: 1 alone is not sufficient — you must also pass recurring: 1.

Checkout API Response​

checkout_idString
ID of the created checkout session
error_codeInteger
Error code for the response
statusString
Status of the checkout session (e.g. open)
client_actionString
Indicates the required client-side action. Value: redirect — redirect the customer to the url in action_data
action_dataObject
Contains: url — the checkout page URL to redirect the customer to
Example Response
{
"checkout_id": "7a87a507-91e8-4882-9b2d-19f35434d946",
"error_code": 0,
"status": "open",
"client_action": "redirect",
"action_data": {
  "url": "https://testapi.betterpayment.de/rest/checkouts/7a87a507-91e8-4882-9b2d-19f35434d946"
}
}
Last updated on