Payment API

POST/rest/payment

Production URL

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

Test URL

https://testapi.betterpayment.de/rest/payment

Payment API is used to create new payment transactions. It performs authorization and capture in a single step — the funds are authorized and captured immediately when the transaction is successful.

If you need to separate authorization from capture, use the Authorize API to reserve funds first, and then the Capture API to capture them later.

Payment API Parameters

Payment request parameters are divided into the following blocks. Depending on the payment method, accepted parameters may differ.

Payment Method	Common	Billing Address	Redirection URLs	Cardholder Data
Card ECOM	Required	Required	Required	Required
Card POS	Required	Optional	-	Required
iDEAL	Required	Optional	Required	-
Pay by Bank	Required	Optional	Required	-
Wero	Required	Optional	Required	-

Payment API Request

Common Parameters

The following parameters are used with all payment methods:

payment_typeStringrequired

See possible payment types in Payment Types

order_idStringrequired

Any alphanumeric string to identify the Merchant's order

invoice_idString

Invoice number of a Merchant's order (up to 20 characters) for factoring or debt collection

invoice_dateDate

Invoice date of a Merchant's order for factoring or debt collection. Format: YYYY-MM-DD

customer_idString

Customer number of a Merchant's order (up to 40 characters) for factoring or debt collection

merchant_referenceString

Default value if not provided: merchant's order id & merchant name. String length different per payment method

amountFloatrequired

Including possible shipping costs and VAT

shipping_costsFloat

Should be set if the order includes any shipping costs

VATFloat

VAT amount if known

currencyStringrequired

3-letter currency code (ISO 4217). Defaults to EUR

postback_urlStringrequired

The URL where updates about transaction status are posted

localeString

Language code of payment forms for Card Acceptance in ISO 639-1

additional_transaction_dataString

Additional payment information. Shown in the dashboard, returned when querying transaction data, and sent back to your postback_url as part of the postback data

Example Request

POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "cardecom",
"order_id": "122",
"invoice_id": "INV-2025-001",
"invoice_date": "2025-02-19",
"customer_id": "CUST-12345",
"merchant_reference": "Order 122 - My Shop",
"amount": "15.90",
"shipping_costs": "3.90",
"VAT": "2.54",
"currency": "EUR",
"postback_url": "https://your-postback.url.com",
"locale": "en",
"additional_transaction_data": "customer_id=123ABC"
}

Billing Address Parameters

Billing information is required in all payment methods.

addressStringrequired

Street address

address2String

Second address line

cityStringrequired

The town, district or city of the billing address

postal_codeStringrequired

The postal code or zip code of the billing address

stateString

The county, state or region of the billing address

countryStringrequired

Country Code in ISO 3166-1 alpha-2 code

first_nameStringrequired

Customer's first name

last_nameStringrequired

Customer's last name

emailString

Customer's email address. We suggest to provide an email for Card Acceptance to avoid declines in 3DS2

phoneString

Customer's phone number

Billing Address Fields

{
"address": "Rosenthalerstr. 8",
"address2": "Apt 3",
"city": "Berlin",
"postal_code": "10178",
"state": "Berlin",
"country": "DE",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@email.com",
"phone": "+49 30 1234567"
}

Redirection URL Parameters

For payment methods that make use of payment page redirects such as Wero or Card Acceptance, these URLs are required.

success_urlStringrequired

Where to redirect the user after a successful transaction

error_urlStringrequired

Where to redirect the user after a failed transaction

Redirection URL Fields

{
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com"
}

The following data is appended to the redirect URL: order_id, transaction_id.

note

Postback URL works differently from the redirection URLs, since Postback does not use browser redirection.

Cardholder Data Parameters

There is an option to enable Server-to-Server Integration for merchants who use card payments. In that case, the API will not use redirection, but expects cardholder data as parameters in the payment or authorization request. This is a special feature that cannot incorporate 3DS verification, so its use is limited to special business cases. To use this feature, the merchant must have the appropriate level of PCI DSS compliance. Please contact Better Payment for further information about Server-to-Server Integration.

card_numberStringrequired

Full primary account number (PAN)

card_holderStringrequired

Full name printed on the card

card_cvvStringrequired

Card verification value (3 digits)

card_expiry_yearStringrequired

4 digits

card_expiry_monthStringrequired

1–12

card_entryString

Controls how the card entry is classified. Possible values: e-commerce, manual, card-on-file, token, token-on-file. See the default mapping table below.

charge_orderString

Controls the order classification. Possible values: checkout, unspecified, mail, phone, one-click, recurring, ucof, installment, standing-order. See the default mapping table below.

clearing_modeString

Controls how clearing is handled. Possible values: auto (the transaction is cleared instantly), manual (the transaction is cleared when the Capture API is called). Defaults to manual for authorizations and auto for payments.

clear_afterString

Specifies a date-time after which the transaction should be automatically cleared. Format: ISO 8601 date-time. No default value — when not provided, clearing follows the clearing_mode behavior.

sca_exemption_requestString

Requests an SCA (Strong Customer Authentication) exemption for the transaction. Possible values: tra (Transaction Risk Analysis), low-value (Low Value Payment), scp (Secure Corporate Payment). Exemption requests may or may not be honored by the issuer. Depending on the outcome, the acquirer will respond with the appropriate flow — skipping 3DS entirely, making it frictionless, etc.

threeds_authentication_valueString

The 3DS authentication value obtained by the merchant from their own 3DS authentication. When both threeds_authentication_value and threeds_directory_server_trans_id are provided, the gateway will skip its own 3DS verification and use the provided values instead.

threeds_directory_server_trans_idString

The Directory Server Transaction ID from the merchant's own 3DS authentication. Must be provided together with threeds_authentication_value.

Cardholder Data Fields

{
"card_number": "4761070000000509",
"card_holder": "John Doe",
"card_cvv": "196",
"card_expiry_year": "2026",
"card_expiry_month": "12"
}

Default values for card_entry and charge_order:

Payment Method	`card_entry`	`charge_order`
Apple Pay	`token`	`checkout`
Google Pay (with cryptogram)	`token`	`checkout`
Google Pay (PAN only, no cryptogram)	`e-commerce`	`checkout`
Card (one-time)	`e-commerce`	`checkout`
Card (recurring)	`card-on-file`	`ucof`
Click to Pay (with cryptogram)	`token`	`checkout`
Click to Pay (PAN only)	`e-commerce`	`checkout`

Recurring Payment Parameters

Some payment methods can use recurring payments. For card payments, authorizations can be recurring as well. Here is a summary of the recurring payment flow:

Create a regular payment with a special parameter: recurring = 1
Store the transaction_id parameter from the response of the first payment request
Create any number of repeat payments with the following parameters: recurring = 1 and original_transaction_id = transaction_id from the first transaction

recurringInteger

Set to 1 when making a recurring payment

original_transaction_idString

Required for subsequent recurring payments. The transaction_id returned from the initial payment or registration response

Recurring Payment Fields

{
"recurring": 1,
"original_transaction_id": "5e02903b-0fbf-4266-affd-dc58f2749cd1"
}

Payment API Response

transaction_idString

ID of the created transaction

payment_typeString

Payment type of the transaction

status_codeInteger

Status code of the transaction

statusString

Status of the transaction

order_idString

Order ID of the transaction

messageString

Optional additional information about the transaction result. This can contain decline codes or other relevant information. It differs depending on the payment method

additional_transaction_dataString

Additional transaction data provided by you. This will be shown in the dashboard as well as when you query for transaction data. It will also be sent back to your postback_url as part of the postback data.

amountFloat

Amount of the transaction

included_feesString

Included fees for the transaction

error_codeInteger

Error code for the response

client_actionString

Indicates the required client-side action after a payment request. Possible values: redirect (redirect to the url in action_data) or postform (build and submit a POST form using the data in action_data). When not returned, no client-side action is required.

action_dataObject

Present when client_action is specified. Contains: url (target URL of the action) and, in case of a postform, fields (key/value pairs of the data to be posted).

Example Response

{
"transaction_id": "88593bcc-d819-4347-84d1-ebfec3806a24",
"payment_type": "cardecom",
"status_code": 1,
"status": "started",
"order_id": "123000",
"message": null,
"additional_transaction_data": "customer_id=123ABC, billing_info=123",
"amount": 15.9,
"included_fees": "0.00",
"error_code": 0,
"client_action": "redirect",
"action_data": {
  "url": "https://some-target-url"
}
}

Postbacks

When a payment is completed or its status changes, the API sends an HTTP POST request to the postback_url provided in the payment request. This allows your system to receive real-time payment updates — even if the customer does not return to your website after checkout.

info

All postback URLs must use HTTPS and support TLS 1.2 or higher. Non-secure or HTTP URLs will be rejected.

Payment Postback — Completed

transaction_idString

ID of the transaction

payment_typeString

Payment type code

status_codeInteger

Numeric status code

statusString

Text representation of the transaction status (e.g. completed, pending, declined)

order_idString

Your internal order or invoice reference

messageString

Optional additional information about the transaction result

remittance_infoString

Remittance information associated with the payment. Sent when a Capture becomes settled. Specific to Wero.

wallet_activity_referenceString

Wallet activity reference. Specific to Wero. Only included when available.

wallet_account_referenceString

Wallet account reference. Specific to Wero. Only included when available.

payer_locationString

Payer location. Specific to Wero. Only included when available.

additional_transaction_dataString

Additional payment information provided by you. Shown in the dashboard, transaction queries, and postbacks.

amountFloat

Amount of the transaction including all taxes and shipping fees

included_feesString

Fees included in the amount

external_transaction_idString

A reference ID assigned by a payment processor or network. Not available for all payment methods.

network_token_idString

UUID of the network token record. Use with the Network Tokenization API to retrieve token details. Only present when a payment is processed using Network Tokenization.

network_token_statusString

Status of the network token: requested, active, suspended, failed, archive_pending, or archived. Only present when network_token_id is included.

checksumString

Checksum of parameters. Use your webhook key (instead of API password) to verify message integrity.

Example Postback Completed

{
"transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"payment_type": "wero",
"status_code": 3,
"status": "completed",
"order_id": "12345678",
"message": "CAPTURE SETTLED",
"remittance_info": "12345678 - Test Shop",
"wallet_activity_reference": "WARf47ac10b58cc",
"wallet_account_reference": "WAC50000aW12",
"payer_location": "DE",
"additional_transaction_data": "customer_id=123ABC, billing_info=12345678",
"amount": 15.90,
"included_fees": "0.00",
"external_transaction_id": "0I66TOoXap2bNLZ2m89tm1",
"checksum": "73a93b8a2d5260f592d98e386c4e5784ee551d1c"
}

Payment Postback — Declined

transaction_idString

ID of the transaction

payment_typeString

Payment type code

status_codeInteger

Numeric status code

statusString

Text representation of the transaction status (e.g. declined)

order_idString

Your internal order or invoice reference

messageString

Additional information about the transaction result

reason_codeString

Rejection reason code in ISO format (e.g. AC01). See EPC guidance

wallet_activity_referenceString

Wallet activity reference. Specific to Wero. Only included when available.

wallet_account_referenceString

Wallet account reference. Specific to Wero. Only included when available.

payer_locationString

Payer location. Specific to Wero. Only included when available.

additional_transaction_dataString

Additional payment information provided by you

amountFloat

Amount of the transaction including all taxes and shipping fees

included_feesString

Fees included in the amount

checksumString

Checksum of parameters. Use your webhook key to verify message integrity.

Example Postback Declined

{
"transaction_id": "bfe9cff7-8cd9-4976-9236-21253c1f40c1",
"payment_type": "wero",
"status_code": 6,
"status": "declined",
"order_id": "123010",
"message": "CAPTURE REJECTED",
"reason_code": "AC01",
"wallet_activity_reference": "WARf47ac10b58cc",
"wallet_account_reference": "WAC50000aW12",
"payer_location": "DE",
"additional_transaction_data": "customer_id=123ABC, billing_info=12345678",
"amount": 10.00,
"included_fees": "0.00",
"checksum": "d56fe31a1a38e06337672ca781e4cb6f3b83fd11"
}

For details on retry policy and signature verification, see Postbacks.

Payment API Parameters​

Payment API Request​

Common Parameters​

Billing Address Parameters​

Redirection URL Parameters​

Cardholder Data Parameters​

Recurring Payment Parameters​

Payment API Response​

Postbacks​

Payment Postback — Completed​

Payment Postback — Declined​

Payment API Parameters

Payment API Request

Common Parameters

Billing Address Parameters

Redirection URL Parameters

Cardholder Data Parameters

Recurring Payment Parameters

Payment API Response

Postbacks

Payment Postback — Completed

Payment Postback — Declined