Payment Page Redirect

The Payment Page Redirect integration is the recommended starting point for most merchants. It works with all payment methods — including cards, Wero, iDEAL, Pay by Bank, Google Pay, and Apple Pay — by redirecting customers to a secure, hosted payment page where all sensitive information is processed safely.

The Payment API used in this guide performs authorization and capture in a single step. If you need to separate authorization from capture, use the Authorize API followed by the Capture API instead.

This guide gives you a step-by-step instruction to get started:

How to access your API credentials
How to authenticate to the API
How to create a Payment API request
How to receive postback notifications (webhooks)

1. Accessing your API credentials

Contact your onboarding manager to get access to the Dashboards, where you will find your API credentials for authentication.

After logging in, navigate to My Company to find your Integration Data and API Passwords.

Environment	Dashboard	API Base URL
Test	https://testdashboard.betterpayment.de	https://testapi.betterpayment.de
Production	https://dashboard.betterpayment.de	https://api.betterpayment.de

tip

Start your integration with the Test environment. Once validated, you will be granted access to Production.

2. Authentication

Before making any API requests, make sure you have your API Key and API Password from the API credentials above available.

Basic Authentication

The API uses Basic Authentication, a simple and widely supported authentication method built into the HTTP protocol. With Basic Auth, the system making the request sends an authorization header that includes the word Basic followed by a space and a Base64-encoded string in the format: username:password.

In this case:

username → your API key
password → your API Password

For example, to authorize as demo / p@55w0rd, then the encoded header would look like this:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

You don’t need to calculate the Base64 string manually — most HTTP libraries (such as curl, Postman, or your SDK) handle it automatically.

Content-Type Headers

All API requests use Basic Authentication and must include the following HTTP header:

Content-Type: application/json

Every request that sends data (for example, POST or PUT) must include a valid JSON body.

3. Idempotency

Our API supports idempotency to ensure safe retries of requests without unintended side effects. To use this feature, include a unique UUID in one of the following HTTP headers when making POST requests:

X-Idempotency-Key
Idempotency-Key

When a request is received with an idempotency key, the response is cached for 1 hour. Subsequent requests with the same idempotency key within this timeframe will return the cached response, preventing duplicate operations.

Best Practice: We recommend using RFC 4122 compliant UUIDs (version 4) for idempotency keys.

POST https://{testapi|api}.betterpayment.de/rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
Idempotency-Key: 9d8f5715-2e7c-4e64-8e34-35f510c12e66

{
  "payment_type": "wero",
  "order_id": "12345678",
  "amount": "15.90",
  "currency": "EUR",
  "merchant_reference": "12345678 - Test Shop",
  "additional_transaction_data": "customer_id=123ABC, billing_info=12345678",
  "postback_url": "https://your-postback.url.com",
  "success_url": "https://your-success.url.com",
  "error_url": "https://your-error.url.com"
}

4. Create a Payment API request

note

All requests must:

Use HTTPS
Include the Authorization header (with Basic Auth)
Include the Content-Type: application/json header if you are sending data
Use valid test or production URLs depending on your environment

The Payment Page Redirect integration can be used with any supported payment method. Simply change the payment_type parameter to match the desired method (see Payment Types for the full list).

Example: Wero

In this example, the customer is redirected to a secure hosted payment page where all sensitive information is processed safely. The same approach applies to all other payment methods — only the payment_type value changes.

Payment API Request

payment_typeStringrequired

Identifier for the payment method. See list of payment types

order_idStringrequired

Any alphanumeric string to identify the Merchant's order

amountFloatrequired

Amount of the transaction including all taxes and shipping fees

currencyStringrequired

3 letter currency code

merchant_referenceStringrequired

Maximum 35 characters. Will be shown in remittance information. Valid characters: a-zA-Z0-9/-?():.,'+ and space

additional_transaction_dataString

Additional payment information 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.

postback_urlStringrequired

The URL for updates about transaction status are posted

success_urlStringrequired

Where to redirect the user after a successful transaction

error_urlStringrequired

Where to redirect the user after a failed transaction

Example Request

POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "wero",
"order_id": "12345678",
"amount": "15.90",
"currency": "EUR",
"merchant_reference": "12345678 - Test Shop",
"additional_transaction_data": "customer_id=123ABC, billing_info=12345678",
"postback_url": "https://your-postback.url.com",
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com"
}

Implementation Flow

Make a Payment API request.
Receive API response with client_action.
Redirect your customer to the payment page URL in action_data.
Customer is redirected to success_url or error_url.
Receive asynchronous postback notifications to postback_url about transaction status.

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. When declined, this field contains the decline code (e.g. AC01)

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": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"payment_type": "wero",
"status_code": 1,
"status": "started",
"order_id": "12345678",
"message": null,
"additional_transaction_data": "customer_id=12345678, billing_info=12345678",
"amount": 15.9,
"included_fees": "0.00",
"error_code": 0,
"client_action": "redirect",
"action_data": {
  "url": "https://testapi.betterpayment.de/payment/d1bf9fdf-7268-406f-9e08-8d5a9540ab97"
}
}

tip

This example shows a minimal request. For the complete list of supported parameters (billing address, recurring payments, and more), see the Payment API Reference.

5. Receive postback notifications

After a transaction is processed, the API will send asynchronous HTTP POST notifications (postbacks) to the postback_url you provided in the payment request. This is how your system stays informed about the final result of each transaction — even if the customer does not return to your website.

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

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

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.

checksumString

Checksum of parameters. Use your webhook key 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

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)

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 retry policy and signature verification, see Postbacks.

1. Accessing your API credentials​

2. Authentication​

Basic Authentication​

Content-Type Headers​

3. Idempotency​

4. Create a Payment API request​

Example: Wero​

Payment API Request​

Implementation Flow​

Payment API Response​

5. Receive postback notifications​

Payment Postback — Completed​

Payment Postback — Declined​

1. Accessing your API credentials

2. Authentication

Basic Authentication

Content-Type Headers

3. Idempotency

4. Create a Payment API request

Example: Wero

Payment API Request

Implementation Flow

Payment API Response

5. Receive postback notifications

Payment Postback — Completed

Payment Postback — Declined