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	Direct Debit	POS
Card ECOM	Required	Required	Required	Required	-	-
Card POS	Required	Optional	-	-	-	Required
iDEAL	Required	Optional	Required	-	-	-
Pay by Bank	Required	Optional	Required	-	-	-
PayPal	Required	Optional	Required	-	-	-
SEPA Direct Debit	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 for card e-commerce payments and optional for most other payment methods. See the table above for the requirement per payment method. When provided, the fields marked as required below must be included.

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

wero_checkout_urlStringrequired

Where the user is coming from before making a Wero payment. Required only for Wero payments.

Redirection URL Fields

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

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`

Direct Debit Parameters

For SEPA Direct Debit, the following additional parameters describe the bank account and the SEPA mandate for both supported schemes: dd (B2C) and dd_b2b (B2B). If the optional sepa_mandate parameter is supplied, the mandate reference does not need to be created beforehand. Otherwise, you can create it upfront with the Mandate Reference API.

account_holderStringrequired

Bank account holder's name

ibanStringrequired

IBAN of the bank account (up to 31 characters)

bicString

BIC of the bank account (up to 11 characters). Optional for SEPA IBANs

sepa_mandateString

Mandate reference number (up to 35 characters). When omitted, a mandate reference is generated automatically

Direct Debit Fields

{
"account_holder": "Max Mustermann",
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX",
"sepa_mandate": "a7678918bfbbfa449cf9ff78446b60a4"
}

note

SEPA collections are submitted to the customer's bank on the same or the next business day. The transaction stays in the started status until submission, and its final status is delivered via postback. See SEPA Direct Debit for the full flow.

POS Parameters

For the Card POS payment method (payment_type: "cardpos"), card-present data is sent in the pos_data object. It groups the terminal entry mode (type), the card data read at the terminal (card), the terminal configuration (terminal), and — when online PIN verification is required — the encrypted pin_block. See Card POS for end-to-end flow examples.

pos_data.type

terminal_entry_modeStringrequired

How the card was read: chip, contactless, magstripe, magstripe-fallback, or manual-entry

sequenceString

subsequent for a retry after a terminal action (e.g. after request_pin in the Mastercard Single Tap flow)

clearing_modeString

Controls how clearing is handled. Possible values: auto (cleared instantly), manual (cleared when the Capture API is called — used to add gratuity after the cardholder has tapped). Defaults to auto for payments and manual for authorizations.

pos_data.type

{
"pos_data": {
  "type": {
    "terminal_entry_mode": "contactless"
  }
}
}

pos_data.card

numberStringrequired

Primary Account Number (PAN). For chip/contactless transactions, the PAN extracted from EMV / Track2 must still be sent here.

expiry_monthIntegerrequired

Card expiry month (1–12)

expiry_yearIntegerrequired

Card expiry year (4 digits)

track2_dataString

Track2 data from the card. Required when terminal_entry_mode is chip, contactless, magstripe, or magstripe-fallback.

emv_dataString

EMV data from the chip; submit unaltered as received from the terminal. Required for chip transactions.

card_sequence_numberString

Card sequence number if EMV tag 5F34 is personalized on the chip (1–3 digits).

pos_data.card

{
"pos_data": {
  "card": {
    "number": "4761739001010010",
    "expiry_month": 12,
    "expiry_year": 2027,
    "track2_data": "4761739001010010D27121200000000000F",
    "emv_data": "9F26081234567890ABCDEF9F100706010A03A000009F3602000195050000000000"
  }
}
}

pos_data.terminal

idStringrequired

Terminal identifier, alphanumeric, 1–8 characters (e.g. 87654321, AAFF). Issued during terminal onboarding.

typeStringrequired

Terminal type: pos or softpos.

attendedBooleanrequired

true for attended terminals, false for unattended. For softpos, must be true.

capabilitiesArray of Stringrequired

Entry / verification modes the terminal supports. The allowed values depend on terminal.type; see Terminal Capabilities below.

pos_data.terminal

{
"pos_data": {
  "terminal": {
    "id": "87654321",
    "type": "softpos",
    "attended": true,
    "capabilities": ["contactlessChip", "onlinePin", "noCvm"]
  }
}
}

Terminal Capabilities

The capabilities array lists every entry / verification mode the terminal is capable of. Multiple values are allowed and indicate the terminal can perform all of those things.

For type: "pos" — one or more of:

Value	Description
`contactChip`	Reads EMV chip via insertion
`contactlessChip`	Reads EMV chip via NFC tap
`contactMagStripe`	Reads magnetic stripe via swipe
`contactlessMagStripe`	Reads magnetic stripe via NFC (legacy MSD)
`offlineEncipheredPin`	Verifies PIN offline using encrypted PIN block
`offlinePlaintextPin`	Verifies PIN offline using plaintext PIN (legacy)
`onlinePin`	Captures online PIN, sent to the issuer for verification
`signature`	Captures cardholder signature
`keyEntry`	Accepts manual PAN entry
`noCvm`	No cardholder verification (e.g. low-value contactless)
`oneTap`	Supports Single Tap (combined PIN entry + transaction)

caution

If capabilities includes keyEntry or signature, then attended must be true.

For type: "softpos" — one or more of:

Value	Description
`contactlessChip`	Reads EMV chip via NFC tap
`onlinePin`	Captures online PIN, sent to the issuer for verification
`signature`	Captures cardholder signature
`noCvm`	No cardholder verification
`oneTap`	Supports Single Tap

pos_data.pin_block

Required only when online PIN verification is needed (e.g., high-value contactless transactions). When supplied, all four sub-fields are required.

formatStringrequired

PIN block format. Supported values: ISO-0, ISO-1, ISO-4.

blockStringrequired

Encrypted PIN block received from the terminal. 16 hex chars for ISO-0/ISO-1; 32 hex chars for ISO-4.

zone_idStringrequired

Identifier of the encryption zone (assigned during terminal onboarding).

key_idStringrequired

Identifier of the encryption key within the zone (assigned during terminal onboarding).

pos_data.pin_block

{
"pos_data": {
  "pin_block": {
    "format": "ISO-0",
    "block": "D766AAA13ED5CA50",
    "zone_id": "pos-gateway",
    "key_id": "0001"
  }
}
}

pos_data.allow_partial_approval

allow_partial_approvalBoolean

Set to true to support partial approvals (common with prepaid cards). Visa and Mastercard only. Cannot be combined with cashback. See Card POS — Partial Approval.

pos_data.allow_partial_approval

{
"pos_data": {
  "allow_partial_approval": true
}
}

amount_breakdown

cashbackInteger

Cashback sub-amount of the total charge amount, expressed in minor units (cents). The full amount must include the cashback portion. Visa and Mastercard only. See Card POS — Cash Back for the full constraints.

amount_breakdown

{
"amount": "30.00",
"currency": "EUR",
"amount_breakdown": {
  "cashback": 1000
}
}

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​

Direct Debit Parameters​

POS Parameters​

pos_data.type​

pos_data.card​

pos_data.terminal​

Terminal Capabilities​

pos_data.pin_block​

pos_data.allow_partial_approval​

amount_breakdown​

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

Direct Debit Parameters

POS Parameters

pos_data.type

pos_data.card

pos_data.terminal

Terminal Capabilities

pos_data.pin_block

pos_data.allow_partial_approval

amount_breakdown

Recurring Payment Parameters

Payment API Response

Postbacks

Payment Postback — Completed

Payment Postback — Declined