DB Merchant Solutions REST API V2.1 Documentation

DB Merchant Solutions REST API assigns a unique identification number to each transaction which is called transaction ID (tx_id in Services API).

When a customer of a merchant’s web shop starts a payment for some goods or a service, the merchant has to associate their own business processes with the transactions in DB Merchant Solutions REST API.

This is handled using event IDs. The event ID is assigned by the merchant’s backend systems and is subject to their own naming conventions as long as it satisfies the rules specified in Services API.

Event is considered as a payment event and therefore has to be unique for each payment process. Several transactions may be associated with an event, but only one successful initial payment (see Transactions kind details). There may be several attempts to pay with different means of payment, one of which is successful. The unsuccessful and the successful payments each relate to a transaction.

Also, a transaction may have subsequent transactions (refunds, reversals, or captures).

All those transactions are associated with the same event.

The event_id is used for most endpoints in Services API.

A (payment) transaction is initialized by the merchant, or the merchant’s backend, respectively. In many cases a transaction requires the customer’s interaction, for example to confirm a payment in the payment method’s system.

The merchant needs to be informed on the outcome of the transaction, or, more generally, its status. The way this status is transferred to the merchant depends on the integration type, or the merchant’s preference (for example Callback and diagnosis request for Form service).

In any case, the status information is contained in the response code which is denoted rc in all API responses in Services API and API requests in Callback API.

As described in Response codes, rc = 0 means success and other response code indicate that either the transaction is still pending or not successful. The value of rc gives further information about the status.

In some situations, a backend response code is given which contains status information on the transaction in the nomenclature of the involved payment backend.

DB Merchant Solutions REST API supports several types of financial transactions which are called transaction kinds in the following. The transaction kind is coded as tx_action in Services API.

The different payment methods each support a subset of the following transaction kinds:

When captures, refunds, and reversals are supported by a payment method, one or more following three variants are possible:

See transaction kind details for a detailed explanation of these transaction kinds.

The following table shows which payment methods support which transaction kinds.

Payment transactions underlie regulations and policies to prevent money laundering and other financial crimes.

Within DB Merchant Solutions REST API payment transactions may therefore be blocked due to Anti Financial Crime (AFC) checks.

This results in specific response codes which are listed in Response codes.

Within DB Merchant Solutions REST API an alias is a reference to a means of payment. A means of payment is an instance of a payment method which contains a legal contract for processing money transactions, for example a credit card, bank account, or a PayPal account.

While modern means of payment (made for ecommerce) prevent misuse by requiring customer authentication, the traditional means of payment credit card and SEPA bank account can be subject to fraud, if their data (PAN or IBAN) falls into the wrong hands. Therefore, this sensitive data must be handled with special care. For credit card this manifests in the PCI DSS regulation.

For traditional means of payment, an alias is a way to reduce the due dilligence effort for a merchant who wants to store a customer’s credit card or bank account for later usage (for example, to offer a "pay with" link for checkout).

The alias for the means of payment is created on a website hosted by DB Merchant Solutions REST API. The customer enters the sensitive data there, and only the alias is provided to the merchant. Therefore, the due diligence, as demanded by PCI DSS, lies with DB Merchant Solutions.

The alias is used in several endpoints of DB Merchant Solutions REST API to initialize payments.

For credit card and SEPA direct debit (bank account), a merchant can withdraw money from the customer using the payment API without further customer interaction or permission. For credit card, this is legally possible for Mail Order/Telephone Order (MOTO) transactions (where the customer permission has been given but not technically proven).

In all other situations, the merchant has to provide a billing agreement of the customer to initialize merchant initiated transactions (MIT). These billing agreements must be authorized by the customer.

Billing agreements are used to authorize recurring payments. These may be withdrawn periodically by the merchant for a magazine subscription or a periodical service, or on an unscheduled basis with a varying amount.

For SEPA direct debit the billing agreement is called SEPA mandate. The merchant is responsible for getting it from the customer and to comply with regulation.

For credit card, the billing agreement is accomplished by an initial transaction authorized by the customer. A reference to the initial transaction is used in (subsequent) MIT transactions, together with the corresponding credit card alias.

The initial transaction may involve a money transfer (authorization or pre-authorization) itself, or may consist of the authorization for the billing agreement alone.

The latter case is associated with the transaction kind verify means of payment (verify MOP).

Modern payment methods, like PayPal or Klarna, don’t require an alias as a reference to sensitive data: Customers simply have to log in to their account and authorize the payment there.

Here, aliases are referencing billing agreements:

For the payment methods PayPal and Klarna the customers authorize the payment method to withdraw payments from their account. The technical reference to the authorization is stored within DB Merchant Solutions REST API and is referenced by the alias. The alias is used in the payment API to initialize MIT.

As for credit card, the authorization for a billing agreement may be contained in an initial money transaction (authorization or pre-authorization) or not. The latter case is also associated with the transaction kind verify MOP (verify-mop).

For Google Pay and Apple Pay are wallets which contain customers' credit cards. Here, the customers authorize access to their credit card which then are used to create the initial transaction which authorizes recurring payments (see Recurring payments).

The customization which payment methods shall be displayed is done in the field checkout_page_configuration of the checkout endpoint:

When using the checkout page, the transaction currency must be supported by all payment methods the merchant wants to be displayed so that the user experience during checkout is not negatively affected.

For example, DB Merchant Solutions REST API will return an error message if a merchant submits a transaction in USD and one of the offered payment methods supports only transactions in EUR.

DB Merchant Solutions REST API supports the payment methods shown in Supported transaction kinds. Via the Form service, the initial transaction kinds authorization, pre-authorization, and verify MOP are supported. The transaction kinds pre-authorization and verify MOP are supported in the checkout page only if all offered payment methods support this transaction kind.

For subsequent transactions, that is capture, reversal, and refund, use the general subsequent transaction endpoint.

Note that the transaction kind credit is only supported via the Payments API.

Since the forms in which a customer enters their credit card details are hosted by DB Merchant Solutions REST API and not the merchant, the merchant does not need to store the credit card details. This allows to save time and costs by not having to participate in the “Payment Card Industry Data Security Standard” (PCI DSS) program by Visa and Mastercard as the participation in the PCI program happens centrally via DB Merchant Solutions.

The Form service uses session cookies to support navigation through the different forms. These session cookies are first-party cookies and are strictly necessary in the sense of the General Data Protection Regulation (GDPR), which is applicable in the European Union and the UK. As the cookies do not gather personal information, a user consent therefore is not required.

The display of the payment method selection and the payment method specific forms are customizable:

The course of transaction for the different payment methods or services is similar but not quite identical.

You transfer the transaction data without the data of the payment method and receive a link (Form service URL) to DB Merchant Solutions as response (see an example below and Forms for details). Then you send a redirect to the Form service URL to your customer. This may be via HTTP redirect header, an HTML page with a meta tag, or a JavaScript form. The payment is made once DB Merchant Solutions has displayed for the customer the form to enter the credit card details and bank details respectively, and the completed form has been returned to DB Merchant Solutions.

Already when initializing the payment your application transmits up to 3 URLs to DB Merchant Solutions, which DB Merchant Solutions directs the customer to after concluding the payment. Which one of the supplied URLs is used depends on the outcome of the payment.

With Form service, a transaction is initialized by a merchant, but the necessary customer interaction is handled by a hosted page of DB Merchant Solutions.

After the transaction, two things have to be done:

Mind, that 2. should not depend on 1. to make sure that the merchant is informed even if (for example) the browser is closed.

All requests in Forms API contain the fields form_customer_continuation referring to 1. and callback referring to 2.

The following diagram shows an example of a payment transaction in the form of a sequence diagram.

The transaction proceeds as follows:

For credit card or Maestro payments with 3D Secure, additional steps take place which are not shown in the diagram. You do not have to consider these additional steps during integration.

To integrate the iFrame Service, your shop has to send requests to the DB Merchant Solutions REST API (step 2 and step 12).

Moreover you have to implement HTML and JavaScript code to enable DB Merchant Solutions to display the iframes with the input fields and to enable DB Merchant Solutions to create a token with the customer’s means of payment data.

The details are described in the following sections.

The iFrame Service uses session cookies, which are first-party cookies and are strictly necessary in the sense of the General Data Protection Regulation (GDPR), which is applicable in the European Union and the UK. As the cookies do not gather personal information, a user consent therefore is not required.

See Services API for details about the request and response entities to initialize an iFrame Service interaction. See iFrame Service initialization example for an example request.

The response will contain the fields client_session, client_configuration, rc, and message.

The values of the response parameters client_session and client_configuration are required for the JavaScript code of the payment form.

Provide an HTML element for every input field that has to be replaced by an iframe, for example a div with an ID. With the ID you can reference the element in the JavaScript code in the options object (see Options).

If you accept both credit card and direct debit payments, you can either create separate forms for credit card and bank account details or a combined form for both transaction kinds. In the latter case the customer decides if they want to pay by credit card or direct debit by filling out the credit card or bank account details in the form.

The following example shows an excerpt from an HTML form for credit card details. In the div elements with the IDs iframeHolder, iframePan, iframeExpiry, and iframeCvc, DB Merchant Solutions will inject iframes later.

Your HTML page to enter the means of payment details has to load the JavaScript file integration.js from DB Merchant Solutions. You can implement this for example by means of a script tag:

The script is also available on the test system under the following URL:

https://testmerch.directpos.de/web-ifs/assets/1.2/integration.js

You can initialize this script for example like this:

The options object mentioned in the example is described below in Options.

You can use instead jQuery to integrate integration.js as follows:

After receiving the token you can carry out the payment using the Payments API. Depending on whether the token was generated for a credit card or a bank account, carry out the payment as a credit card or direct debit payment. You can choose between the transaction kinds authorization or pre-authorization and capture. These transaction kinds are described in Transactions kind details.

The subsequent example contains HTML and JavaScript code for a page with two forms to enter credit card and bank account details.

Via the Widget Solution, a merchant can integrate widgets for the supported payment methods directly into their checkout page.

This has the following advantages:

Widget Solution supports the following payment methods:

To integrate Widget Solution, a merchant needs a business account for each payment method they integrate. See Merchant integration and onboarding requirements (Google Pay), Onboarding (Apple Pay), and Prerequisites (PayPal).

The following diagram shows the course of a Widget Solution transaction.

Merchants using Widget Solution have to take a number of decisions how it is integrated into their business processes and their website.

The technical implementation as well as the behavior may differ for the available payment methods.

Use the Widget Solution create session endpoint to create a session as follows:

Widget Solution is based on JavaScript. To integrate it with the merchant’s specific logic, one has to implement up to six event handlers. If these are not implemented, the merchant might not react to user’s changes like an update of the shipping address.

These events are:

For Google Pay, the merchant may specify the allowed countries for the shipping address in the googlepay section of the initialization data (see Google Pay). Nevertheless, the country should be checked to prevent fraud (by manipulating the browser session). For PayPal, there is no such configuration.

For details see JavaScript reference.

The following JavaScript snippet shows a client-side sample implementation of the event handlers. Mind that the same code is used for all payment methods.

Use the Widget solution create payment endpoint to finalize the payment as follows:

See Subsequent transaction as well as Capture, Refund, and Reversal for general information about capture, refund, and reversal.

Use the general subsequent transaction endpoint to conduct a capture, refund, or reversal.

See Diagnosis request for general information about retrieving information about a previous transaction.

Use the general endpoints Get information for an event ID or Get information for a transaction ID.

The Payment Card Industry Data Security Standard (PCI DSS) is an information security standard for organizations that handle credit cards from the major credit card schemes (MasterCard, Visa, American Express, Diners, China UnionPay, and JCB). The technical and organizational requirements of PCI DSS help to protect cardholder data, reduce fraud, and minimize the chances of a data breach.

See PCI DSS Quick Reference Guide for a more detailed introduction.

As mandated by the card schemes, every e-commerce merchant that accepts credit cards as a payment method must annually demonstrate their compliance to the standard by completing a self-assessment questionnaire (SAQ).

There are nine different types of SAQs, three of which are relevant for e-commerce merchants:

For a detailed comparison of the SAQs, see PCI DSS - Understanding the SAQs for PCI DSS version 3 and PCI DSS - SAQ Instructions and Guidelines.

For the purposes of checking eligibility criteria, note the following:

The following table shows which type of SAQ to use depending on the integration type.

PCI DSS Version 3.2.1 has been retired at 2024-03-31.

This means that from 2024-04-01 on, a merchant has to demonstrate their compliance to PCI DSS Version 4.0.

Up to 2024-03-31, a merchant could still demonstrate their compliance to PCI DSS Version 3.2.1. Assessment results from before 2024-03-31 remain valid (for a period depending on the merchant’s specific situation).

See

When handling more than 6 million credit card transactions per year, a merchant has to additionally provide an Attestation of Compliance (AOC) as well as a Report on Compliance (ROC). Consult with your credit card acquirer or a PCI DSS Qualified Security Assessor (QSA) for more information. See PCI DSS QSA companies to find a QSA.

To become acquainted with DB Merchant Solutions REST API, download the OpenAPI 3.0 specification of DB Merchant Solutions REST API as .yaml file and import it in a tool like Swagger Editor or Postman.

These tools allow to try out the API functionality. For authentication, generate a bearer token as described in Authentication.

The interface is implemented as a REST API. The data transfer is via HTTPS with bearer authentication. Your application acts as REST client, DB Merchant Solutions acts as REST server. As a rule, you will send a REST request to DB Merchant Solutions and you will receive the result of the transaction as JSON response. 3-D Secure credit card payments and payments via the Form service require a more complex interaction between the client, your application and DB Merchant Solutions.

You may access more information in the description of the individual payment procedures and transaction kinds.

In the case of form service payments your application acts as REST server upon the callback regarding the outgoing payment, DB Merchant Solutions as REST client.

For the realization of the connection you have a test system available, where payment transactions are only simulated.

There are numerous REST implementations for various programming languages and hardware platforms, which you may use for the connection of your application.

The specification for the DB Merchant Solutions REST API in the OpenAPI 3.0 format is available as a .yaml file. Based on this file your chosen REST implementation can generate a large part of the code required for the connection.

The field descriptions in the OpenAPI specification state the general purpose of the fields. For further information how to use the fields depending on the use case, and in particular which fields may be required for a certain use case, refer to the User guide.

The examples provided in the OpenAPI specification are a good starting point to get acquainted with the API. In particular, they can serve as minimal examples for which fields are required.

The examples use www.example.com as an example for a domain name. When implementing the API, replace this domain name by the corresponding shop domain.

Precautions have been taken to prevent inadvertent processing of duplicate transactions. See Using idempotency keys for details.

The current API version is 2.1.

Users of DB Merchant Solutions REST API use different environments for test and production. The test environment is used for test and integration (of a whole application or new features), and to get acquainted with DB Merchant Solutions REST API, while the production environment is used for productive merchant’s applications (with real payment).

Test and production have different base URLs but the same rest endpoints.

The following information is important to be known:

As base URL, use the following:

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

Any additive (non-breaking) changes will be available in all supported API versions. Additive changes are changes that should not break an integration. Additive changes include:

When a new REST API version is released, the previous API version will be supported for at least 24 more months following the release of the new API version.

Contact Deutsche Bank customer support for which API versions are currently supported.

See the Open API specification for an explanation of the primitive data types used.

For example, the complex type Basket is used for many different payment methods to model the shopping basket of a customer. It contains a subfield extensions which in turn contains a subfield paypal_data for PayPal specific information. The field basket.extensions.paypal_data appears in all requests which contain a basket, but it should be set (and will be processed) only for PayPal transactions.

The client_secret is determined by calculating an HMAC-256 signature over the following values:

All three values are concatenated and an HMAC-256 signature is calculated using the client_key as the secret. The client_secret is then built by Base64 encoding the resulting value prepended by the version-prefix V1 and the delimiter :.

The following code fragment shows a sample Kotlin implementation of calculating the client secret.

The following code fragment shows a sample JavaScript (ES6) implementation of calculating the client secret.

The CryptoJS library used can be included as follows.

DB Merchant Solutions REST API supports idempotent HTTP requests through the use of idempotency keys. This is useful when a request should time out: You can safely retry the same request, for example to create a payment, with the guarantee that the payment is created only once.

More specifically, DB Merchant Solutions REST API supports for each request the header parameters Idempotency-Key and Idempotency-Key-TTL where TTL stands for time to live. When processing a request with these header parameters, DB Merchant Solutions REST API will ensure that during the TTL of the key each request with this key will be idempotent.

An idempotency key may be any alphanumeric character sequence between 1 and 64 characters length. To create an idempotency key, it is highly encouraged to use the UUID v4 algorithm. This makes sure that each new request gets a new key and no key is reused accidentally.

The idempotency key needs to be placed in the HTTP header named Idempotency-Key. If this header is present then an idempotency key of the defined format is expected, that is this header must not be empty.

Idempotency keys are stored in a cache. You can control for how long an idempotency key will be stored in the cache with the optional header Idempotency-Key-TTL. This header needs to contain an integer value between 1 and 8760 (= 365 * 24, that is one year) indicating the time to live in hours. Values outside this range will be treated as client errors.

When the parameter is not present, the TTL is set by default to 720, that is 30 days.

When idempotency keys are used five different responses may be observed:

DB Merchant Solutions REST API calculates a signature as follows.

The signature can be validated by recalculating it and comparing it to the value sent, for example as follows.

Carry out an authorization to initiate the payment of a concluded business operation. Compared to a pre-authorization and subsequent capture, an authorization requires only one step.

A payment system may support recurring transactions. These are transactions that are authorized once by the customer and then subsequently initiated by the merchant without further customer interaction, for example for magazine subscriptions.

Carry out a pre-authorization to reserve the customer’s funds for an order that will take place at a later point in time.

A pre-authorization only reserves the customer’s funds for a certain time, the so-called reservation period, which depends on the payment method. To actually initiate clearing and settlement, a merchant has to carry out a capture.

If no capture is carried out during the reservation period, the customer’s funds will be freed again, in which case a capture is no longer possible. The customer’s funds can also be (partially) freed before the expiry of the reservation period by carrying out a (partial) reversal of the pre-authorization.

A credit is a transaction which provides a reimbursement to the customer and does not relate to a preceding capture or authorization.

A subsequent transaction (capture, refund, or reversal) follows an initial transaction (pre-authorization, authorization, or credit) or another subsequent transaction.

A subsequent transaction is connected to its related transaction: Using the diagnosis request for the event_id, subsequent transactions are given as children of their related transaction (see Diagnosis request).

A capture initiates the booking of the funds reserved by a pre-authorization. For a capture, the business operation needs to be concluded, thus for example that a shopping basket was offered, ordered, and delivered to the customer.

In general, the amount to be booked has to be the same as or less than the pre-authorized amount. These cases are called full capture and partial capture, respectively. Certain payment methods such as credit card and PayPal support an overcapture, that is a capture whose amount exceeds the pre-authorized amount up to certain percentage. See the corresponding sections for the payment systems for details.

Upon capture, the customer’s account is charged with the requested amount and the merchant’s account is similarly credited.

Depending on the payment system, for a pre-authorization and a partial capture one of the following is applicable:

A refund is a transaction which provides a reimbursement to the customer which relates to a preceding capture or authorization. The amount refunded may be less than or equal to the amount paid.

Depending on the payment system, for a capture or authorization either only one refund is possible or several (partial) refunds are possible.

The process for the submission and the clearing of refunds on your customers' current accounts may need to be coordinated with your account-holding institution.

Depending on the payment system, pre-authorizations, authorizations, captures, credits, and refunds may be reversed, that is, cancelled.

See Supported transaction kinds for which payment systems support reversals in general. See the sections on the individual payment methods for particular restrictions.

For all payment systems, the reversal of a pre-authorization is possible as long as no booking notification has been sent and as long as the reservation period has not expired.

For SDD, the reversal of an authorization, capture, credit, or refund is possible until the end of the day of the transaction (Central European Time (CET) or Central European Summer Time (CEST)).

For other payment systems, contact the payment system support for how long a reversal for an authorization, capture, credit, or refund is possible.

For the payment methods credit card and SDD, carry out the transaction kind 'verify means of payment' (tx_action: verfiy-mop) to check whether the supplied credit card or bank account actually exists. For credit card, in the context of EMVCo 3-D Secure, it is also checked whether the card is owned by the customer (see Credit card transactions). Therefore, verfiy-mop is used to authorize future recurring payments (which are then initiated by the merchant), see Tutorial: recurring credit card transactions.

Within Widget Solution, verfiy-mop is also used to authorize recurring payments for PayPal.

Diagnosis requests are used to retrieve information on previous transactions from DB Merchant Solutions REST API. They don’t have an explicit tx_action, but tx_action appears as a field in their response and is needed to interpret this.

The following transaction flows occur frequently:

The following transaction flows occur less frequently:

If you already have access to a 3DS Server, you can use it for 3-D Secure transactions for the initialization, method and challenge flow and only use DB Merchant Solutions REST API for the authorization. The transaction then is as follows:

See Credit for general information about issuing a credit.

For credit cards, use the payment credit card endpoint with tx_action = credit for all integration types.

The following table shows the most common response codes for credit card transactions. See Response codes for a complete list of possible response codes.

For tests of credit card payments the card numbers listed in the following tables are available. Use an expiry date in the future for successful test payments. The card verification code is not verified on the test system. You can enter any three-digit number.

The columns have the following meaning:

To carry out a 3-D Secure 2.1 or 2.2 simulation you can use the test card numbers given in the following table.

For authorization and pre-authorization, use the following endpoints depending on the integration type:

The fields basket.shipping_costs and for each basket_item, name, unit_price.net` and unit_price.gross, are required as they are displayed to the customer when using Google Pay. For each basket item, the basket item gross amount is calculated as quantity.quantity_amount * unit_price.gross - item_discount.gross. It is required that amount_total.amount equals the sum over each basket item gross amount plus the shipping costs minus the basket discount.

For captures, reversals, and refunds, for all integration types use the general subsequent transaction endpoint, setting kind = CREDITCARD (as a Google Pay transaction is a credit card transaction).

For retrieving information about a previous transaction, use the general endpoints for diagnosis for an event and diagnosis for a single transaction.

Google Pay provides a test card suite for testing (see Test card suite).

This test card suite is used in TEST mode if the customer’s Google account is not assigned to the real data group.

For the integration types Form service and Widget Solution, TEST mode is used automatically in the test environment DB Merchant Solutions REST API (see test and production). For Direct integration, the environment must be set to TEST.

In this case, the cards of the test cards suite are offered as means of payment. The test card numbers and test data (names, addresses, and telephone numbers) are transferred to the test gateway.

The test card suite only supports the authentication method PAN_ONLY and can therefore be used to test 3DS integration (see Supported cards, transaction kinds, and authorization methods).

The following card are supported by the test backends of DB Merchant Solutions REST API. Other cards lead to errors in the 3DS flow.

If the customer’s Google account is assigned to the real data group, the cards of the Google web wallet are offered if available. If the customer uses the Chrome Browser on an Android device and has a tokenized card in his Google Wallet app, this credit card is also offered as means of payment.

In this case, sample tokens are transferred to the payment backends (see Test with sample tokens). Especially, no real credit card data is transferred. If further customer data (like names, telephone numbers, or addresses) are transferred, the real data from the Google account are taken.

Important: If a card from the Google Wallet app is chosen, the sample token also uses the authentication method CRYPTOGRAM_3DS (see Supported cards, transaction kinds, and authorization methods). In this case, 3D Secure is not required. Transaction always succeed in TEST mode.