Card ECOM

Description

Card ECOM is a merchant's decision to take a specific type of payment card, like a credit or debit card, from a customer. A merchant can choose which brands and types of cards they accept, such as Visa, Mastercard, or American Express, and must display this information to customers. For merchants, accepting card payments is a way to increase sales, while for cardholders, it means they have the ability to use their card for payment.

Availability

Mastercard and Visa are accepted in over 200 countries and territories worldwide.

Transaction Types

The following transaction types are currently available:

• Payment
• Authorize
• Capture
• Refund (Full and partial refund)
• Reverse
• Register
• Recurring

Integration Types

The following integration types are currently available:

• Server-to-Server Processing
• Payment Page Redirect

Payment Flow

Payment Page Redirect

Server-to-Server

API Implementation

Required value for payment_type parameter: cardecom

Server-to-Server Processing

Send cardholder data directly in case you meet the necessary PCI DSS compliance requirements.

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.

info

If you have your own 3DS MPI (Merchant Plug-In), you can pass threeds_authentication_value and threeds_directory_server_trans_id directly in the payment request. In this case, the gateway will use your 3DS authentication results and return a direct response without triggering its own 3DS flow. See the Cardholder Data Parameters for details.

Payment API Request

payment_typeStringrequired

Value: 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)

This example includes only the minimum required parameters. See the Payment API Reference for the full list.

Example Request

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

Payment API Response

Direct (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.

3DS Required (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.

The merchant must build a form on their frontend and POST the fields to the provided url in action_data. This redirects the customer to the 3DS authentication page. Once completed, the customer returns to success_url or error_url.

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

amountFloat

Amount of the transaction

included_feesString

Included fees for the transaction

error_codeInteger

Error code for the response

client_actionString

Required client-side action. Values: postForm or redirect. When not returned, no action is required.

action_dataObject

Contains url (target URL) and, for postForm, fields (key/value pairs to post).

Response — Direct (with own MPI)

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

Payment Page Redirect

Redirect the customer to our PCI DSS compliant payment page.

Implementation flow:

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

Payment API Request

payment_typeStringrequired

Value: 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

This example includes only the minimum required parameters. See the Payment API Reference for the full list.

Example Request

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

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

error_codeInteger

Error code for the response

client_actionString

Required client-side action. Values: redirect or postForm. When not returned, no action is required.

action_dataObject

Contains url (target URL) and, for postForm, fields (key/value pairs to post).

Example Response

{
"transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"order_id": "12345678",
"error_code": 0,
"status_code": 1,
"status": "started",
"client_action": "redirect",
"action_data": {
  "url": "https://testapi.betterpayment.de/payment/d1bf9fdf-7268-406f-9e08-8d5a9540ab97"
}
}

Postbacks

transaction_idString

ID of the transaction

payment_typeString

Payment type of the transaction

status_codeString

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

card_last_fourString

Last four digits of the card number

card_expiry_yearString

Expiry year of the card

card_expiry_monthString

Expiry month of the card

card_brandString

Card brand (e.g. VISA, MASTERCARD)

card_typeString

Card type (e.g. CREDIT, DEBIT)

card_countryString

Issuing country of the card

included_feesString

Included fees for the transaction

external_transaction_idString

External transaction ID from the processor

checksumString

Checksum for postback signature verification

Example Postback

{
"transaction_id": "938834bc-769f-44e7-ab25-da9aeaad5346",
"payment_type": "cardecom",
"status_code": "3",
"status": "completed",
"order_id": "12345678",
"message": "",
"additional_transaction_data": "",
"card_last_four": "0509",
"card_expiry_year": "2026",
"card_expiry_month": "12",
"card_brand": "VISA",
"card_type": "",
"card_country": "",
"included_fees": "0.00",
"external_transaction_id": "0I66TOoXap2bNLZ2m89tm1",
"checksum": "73a93b8a2d5260f592d98e386c4e5784ee551d1c"
}

For refund postbacks, see the Refund API. For retry policy and signature verification, see Postbacks.

Test Data

Visa

Parameter	Test Value
card_number	4761070000000509
card_holder	any name
card_cvv	any 3 digit number
card_expiry_month	any month (e.g. 12)
card_expiry_year	any year in the future (e.g. 2026)

mastercard

Parameter	Test Value
card_number	5286940020000908
card_holder	any name
card_cvv	any 3 digit number
card_expiry_month	any month (e.g. 12)
card_expiry_year	any year in the future (e.g. 2026)

3DS Passthrough

For merchants using their own MPI for 3DS authentication, use the following test values alongside the Mastercard test card above:

Parameter	Test Value
threeds_authentication_value	AUTHENTICATION_VALUE
threeds_directory_server_trans_id	54c64c00-eef8-4a8b-af44-fee8cc57e530
card_number	5286940020000908
card_holder	Max Mustermann
card_cvv	196
card_expiry_month	12
card_expiry_year	2026