Checkout API

POST/rest/checkouts

Production URL

https://api.betterpayment.de/rest/checkouts

Test URL

https://testapi.betterpayment.de/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"
}
}