Server-to-Server Processing

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:

1. How to access your API credentials
2. How to authenticate to the API
3. How to create a Payment API request
4. 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": "cardecom",
  "order_id": "12345678",
  "amount": "15.90",
  "currency": "EUR",
  "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",
  "card_number": "4761070000000509",
  "card_holder": "John Doe",
  "card_cvv": "196",
  "card_expiry_month": "12",
  "card_expiry_year": "2026"
}

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 Server-to-Server Processing integration allows merchants or processors to send payment data directly to the Payment API without redirection to a payment page.

Example: Card ECOM

In the following example your system receives cardholder data (PAN, CVV, expiry date, cardholder name) and sends it directly to our API.

caution

This integration requires that you have the required PCI DSS compliance, since cardholder data is handled directly by your infrastructure.

Payment API Request

payment_typeStringrequired

cardecom

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

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

card_numberStringrequired

Full card number (PAN) of the cardholder

card_holderStringrequired

Name of the cardholder as printed on the card

card_cvvStringrequired

Card verification value (3 digits on back of card)

card_expiry_monthStringrequired

Expiry month of the card (2 digits, e.g. 01–12)

card_expiry_yearStringrequired

Expiry year of the card (4 digits, e.g. 2026)

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.

Example Request

POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "cardecom",
"order_id": "12345678",
"amount": "15.90",
"currency": "EUR",
"postback_url": "https://your-postback.url.com",
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com",
"card_number": "4761070000000509",
"card_holder": "John Doe",
"card_cvv": "196",
"card_expiry_month": "12",
"card_expiry_year": "2026"
}

Implementation Flow

1. Make a Payment API request with card data.
2. Receive API response.
3. If the response contains a client_action, handle it accordingly:
   • postForm: Build a form on your frontend and POST the fields from action_data to the provided url. This redirects the customer to the 3DS authentication page.
   • redirect: Redirect the customer to the url in action_data.
4. After 3DS is completed, the customer is returned to your success_url or error_url.
5. Receive asynchronous postback notification to postback_url with the final transaction status.

Payment API Response

Direct Response (with own MPI)

When threeds_authentication_value and threeds_directory_server_trans_id are provided in the request, the gateway uses the merchant's 3DS results and returns a direct 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

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

Example Response — Direct

{
"transaction_id": "938834bc-769f-44e7-ab25-da9aeaad5346",
"payment_type": "cardecom",
"status_code": 3,
"status": "completed",
"order_id": "12345678",
"message": null,
"additional_transaction_data": "",
"amount": 15.90,
"included_fees": "0.00",
"error_code": 0
}

3DS Required Response (without own MPI)

When no 3DS authentication values are provided, the gateway triggers its own 3DS flow. The response will have status: "pending" and a client_action that the merchant must handle:

client_actionString

Indicates the required client-side action after a payment request. Possible values: postForm (build and submit a POST form using the data in action_data) or redirect (redirect to the url 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).

In this case, the merchant must build a form on their frontend and POST the fields to the provided url in action_data. This will redirect the customer to the 3DS authentication page. Once 3DS is completed, the customer is returned to the merchant's success_url or error_url.

Example Response — 3DS Required

{
"transaction_id": "25634b4d-c3dd-4242-afe3-e7962c33138c",
"payment_type": "cardecom",
"status_code": 2,
"status": "pending",
"order_id": "12345678",
"message": null,
"additional_transaction_data": null,
"amount": 15.90,
"included_fees": "0.00",
"error_code": 0,
"client_action": "postForm",
"action_data": {
  "url": "https://3ds-acs-url.example.com/v1/acs/challenge-initiate",
  "fields": {
    "creq": "eyJ0aHJlZURTU2VydmVyVHJ..."
  }
}
}

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. For integration details on other payment methods, see Payment Methods.

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.