Integration Guide easyCredit-Ratenkauf API V3

Last updated: 23.03.2023

With the help of these instructions, you can integrate the payment method easyCredit-Ratenkauf into your online shop in just a few steps. In addition to general information about the product and the process, the document naturally also contains instructions and practical examples for the integration itself.

Changelog

Date	Change
02.03.23	Sequence diagram added
16.02.23	Chapter Prerequisites added Chapter Initialization changed
13.10.22	Authorization Callback-URL added Wording Schulungsumgebung -> Test-Ansicht changed
15.09.22	Brand changed to easyCredit-Ratenkauf
21.06.22	Checkbox for data transmission no longer needed Redirect-URL updated Ratenkauf Webcomponents added Changelog added

General Informationen For easyCredit-Ratenkauf

By means of easyCredit-Ratenkauf, a merchant can easily offer his customers the possibility of payment by instalments. The final transaction takes place immediately during the online ordering process on the basis of "real factoring": the bank handles the credit check for the merchant and, in the event of a successful transaction, the bank also receives the payment claim from the merchant against the customer – including the risk of the customer’s inability to pay.

Product Details:

• Purchase amount: 200 € to 10,000 €
• Terms: 2 to 60 months, freely selectable
• Suitable for use in german online shops

Merchant benefits:

• Easy and quick integration
• Secure payment, no risk
• Fair conditions and high flexibility for end customers

Customer benefits:

• Instant – Quick and convenient without proof of salary and without PostIdent procedure
• Fair – Transparent presentation of the instalment price without hidden costs or fees
• Secure – Maximum protection of payment data has the highest priority.
• Flexible – Early repayment and payment breaks possible for customers

Whats New In v3?

Our new Payment API V3 has been further simplified in terms of integration and brings the following new features:

1. Language change / Internationalization

   Our API and the corresponding openAPI specification are now provided in English by default. Based on the openAPI specification, you can have a client / library automatically generated in the programming language of your choice.
   Further information on this can be found at https://github.com/OpenAPITools/openapi-generator or https://swagger.io/tools/swagger-codegen/.

   [Details]

2. Workflow and status model

   The status model of the API has been greatly simplified in the new version and aligned with the rest of the payment systems.

   Status	Description
   open	Transaction has been initialized successfully
   preAuthorized	Credit check has been carried out, the customer can finance the shopping basket with easyCredit-Ratenkauf
   declined	Credit check has been carried out, the customer cannot be offered easyCredit-Ratenkauf. Thus, another payment method must be chosen.
   authorized	The completion of the order by the customer has been registered with us and the purchase has been authorized
   expired	The purchase cannot be processed further (e.g. expired). A new order must be initialized.

   The naming of the endpoints is also based on the new status model. Thus, a transaction is initialized using POST ./transaction and an authorization is created using POST ./transaction/{id}/authorization.

3. Authentication via Basic-Auth

   With our API v3, authentication is based on the BASIC-Auth algorithm, no longer via custom headers. This greatly simplifies integration and eliminates the need for additional third-party modules or libraries. At the same time, the doubling of the character length and the generation of the API passwords further strengthen the security of the endpoints.

   [Details]

4. 2-step-confirmation

   In order to reliably ensure that the order confirmation of an order with the payment method easyCredit-Ratenkauf only occurs when the installment purchase has been successfully authorized, the 2-step-confirmation was introduced.

   For this purpose, an authorization is created in the first step.
   This is acknowledged with the HTTP status 202 Accepted. This means that we have accepted the request but are still in the process of propagation. Once this is done, the confirmation page about the order can be displayed to the customer. The order/order confirmation email should not be sent until the status of the associated installment purchase is authorized. The status can be queried using GET ./transaction/{id}.

   [Details]

5. Body signature

   Another feature to increase security is the new body signature.
   This allows each request to be signed using a secret key. Like the API password, the secret key can be created in the partner portal. Each API response is then also signed with the secret key. This ensures that the request and response have not been modified by a man-in-middle attack.

   [Details]

Workflow Of easyCredit-Ratenkauf

Action	Data transmission notice	>	Initialization	>	Redirect Payment Page	>	Review credit check	>	Confirm order	>	Check confirmation
Status	–		open		–		preauthorized / declined		preauthorized		authorized
Endpoint	GET ./webshop		POST ./transaction		–		GET ./transaction/{id}		POST ./transaction/{id}/authorization		GET ./transaction/{id}

1. Display Data Transmission Notice

• During checkout, the customer selects the payment method easyCredit-Ratenkauf.
• The customer must be shown the data transmission notice before initialization and forwarding. Explicit consent via checkbox is no longer required. The text for the data transfer notice can and should be obtained dynamically from the API.

2. Initialization

• The initialization creates a new purchase transaction with a new, unique transaction identifier, the technicalTransactionId. This transaction is the basis for the exchange of information between the webshop and TeamBank or the payment API.
• An SSL-secured connection is created for the exchange between the webshop and the API to ensure that the data cannot be manipulated.
• Data collected by the webshop and relevant for the purchase (email, address, etc.) is transferred to the payment API.
• A unique and unambiguous token is generated for the Device Ident service to protect against fraud.

3. Redirect To Payment Page

• The customer is redirected to the so-called payment page. The URL is composed of [https://ratenkauf.easycredit.intern/app/payment/{id}/datenerfassen] and the technical transaction identifier.
• On the payment page, additional customer data is collected that is necessary for the purchase but was not entered in the webshop, including consent to data storage, credit check and SEPA direct debit mandate.
• By clicking on Ratenwunsch prüfen, the customer starts the credit check. This is done on the basis of the data entered, but also various mechanisms for checking identity and fraud.
• The customer is shown the decision result, including the corresponding information text.
• The decision result can be POSITIVE or NEGATIVE, or POSITIVE with adjustment of the desired term.
• In case of rejection (NEGATIVE), the customer will be offered to return to the checkout process.
• In the case of a positive decision (POSITIVE), the customer can adjust the term within the limits set by the credit decision and then accept the financing offer.

4. Return & Query Decision

• After the payment page, the customer is redirected back to the return URL (urlSuccess) that was passed during initialization.
• At this point, the shop must fetch and check the credit decision result to ensure that the return URL alone is not sufficient to place the order. The transaction must be in preauthorized status.
• On the order summary page, the amount of interest must be explicitly displayed to the customer both as a separate item and included in the cart total.

5. Confirmation / Authorization

• By clicking "Zahlungspflichtig bestellen" the confirmation/authorization is transferred to TeamBank with the installment plan previously selected by the customer.
• After the successful authorization, the "Thank-you-for-your-order" page can be displayed to the customer.

6. Callback

• To ensure that the authorization was successfully transferred to TeamBank, the status of the transaction must be verified once again at the end.
• If the transaction has the status authorized, the order confirmation email can be sent to the customer by the webshop system.

Sequence Diagram

[Click to enlarge]

Basic Parameters Of The API

The technical connection of the easyCredit-Ratenkauf takes place via web services in the form of REST resources. They can be called via JSON or XML. In the examples of this document, a connection of the web services with JSON is demonstrated.

OpenAPI-Specifications

The specification of the payment API is provided in the OpenAPI standard. Accordingly, you can automatically generate the client to connect to our API, according to the platform used (PHP, Java, JS/Node, Python).
The specification is available as a Swagger UI and as a JSON file at the following URLs.

Payment-API as Swagger-UI

Payment-API as JSON-File
Changelog

Payment-API on GitHub
Changelog

Versioning

Our API is versioned in the path with the major version. We ensure that we only make backward compatible changes/extensions in the context of a major version. Downward incompatible changes are only made in the context of a new major version with a new openAPI specification. However, the previous version will be preserved. A discontinuation of an obsolete version is done by e-mail with a correspondingly long transition period.

We are making the following changes as part of a major release:

• Addition of new attributes
• Adding new endpoints
• Adding new status codes and error messages
• Adding new authentication methods (e.g. API tokens)

In the OpenAPI specification, the version attribute contains a version number formatted according to Semantic-Versioning.
The backward compatible changes are additionally maintained in the Changelog.

Basic Information On Integration

Instructions

In addition to this Integration Guide, generated interface documentation and other documents are available. For more details, please refer to the chapter Basic Parameters Of The API).

While this Integration Guide looks at the business process and all steps of the integration including examples, the OpenAPI documentation is focused on a purely technical description of the interface, endpoints and attributes of the system.

Starting with the REST resources, you can look there at all the request/response objects (elements) with JSON examples. Here it is also recommended to look at the type descriptions of these elements, since only these contain the descriptions relevant to the fields.

Although the call of all relevant endpoints is also documented in the Integration) chapter, especially in the application examples, the actual interface documentation is definitive in case of doubt.

Demo Store

You can also take a look at the integration of the Payment API via Payment Page in the TeamBank demo store. This can be accessed via the following URL:

https://easycredit-demo.netzkollektiv.com/

Logos & Texts

easyCredit-Ratenkauf logos for advertising in your store can be found at https://www.easycredit-ratenkauf.de/service-integration/marketingmaterial-schulung/logos-und-werbebanner-fur-den-onlineshop/

You can obtain product & legal texts at https://www.easycredit-ratenkauf.de/service-integration/marketingmaterial-schulung/textvorlagen-produktinformationen/

Zugangsdaten

To use easyCredit-Ratenkauf, you need a webshop ID and an API password as credentials.

If you are already a registered merchant or partner, you will receive your credentials as part of the normal onboarding process. After onboarding has taken place, you can view and generate your credentials in the Partner Portal in Shop Administration.

If you are not registered yet or want to use demo credentials, please contact mailto:ratenkauf@easycredit.de.

Since the easyCredit-Ratenkauf system itself is identical for test and production, the parameters

• webshop ID
• API password and
• the base URL of the REST endpoints

are the only environment-dependent parameters of the integration variant "Payment-Page". These should be stored in a configurable way when integrating the payment method into a webshop.

Which credentials can i use for testing?

To make a test purchase without a credit check etc. you have two options:

1. Test view

   For every 1.de. webshop ID you receive from us, there is also a concurrent webshop ID that starts with "2.de.". If you use these credentials, all orders will be recognized as test orders – regardless of which customer data is used. Therefore, this option should not be used in productive operation, if possible. The 2.de. webshop ID is therefore more suitable for development environments where testing is done often and no real orders are placed.

   A separate API password must be generated for the 2.de. webshop ID via the "Test Ansicht" button at the top right in the Shop Administration.

2. Test mode

   Even if the 1.de. webshop ID is used, test orders can be carried out. To do this, you must activate the Test mode for this webshop ID in the Shop administration.

   If this is the case, test orders can be created with the customer data Ralf Ratenkauf, Beuthener Str. 25, 90471 Nürnberg. All orders with other customer data will still be processed as real orders incl. credit check.

   Therefore, this option is particularly suitable for testing in the productive environment, as it does not affect the rest of the business.

   

Prequisites

In addition to the technical level, the individual installment purchases are also subject to requirements or restrictions regarding customers and orders:

• Financing amount between 200 € and 10,000 €.
• Residence in Germany
• Invoice & delivery address must be identical
• Companies & self-employed persons excluded

Although TeamBank’s API can handle some of the potential discrepancies, it is still important and necessary that both the store and store operators push for compliance with the above criteria. This can be achieved, for example, through the correct transmission of order data or by making adjustments to the checkout workflow.

Example:
In some shop systems it is possible to change the delivery address again at the end of the order. Since easyCredit-Ratenkauf can not be used with different addresses, the store must either not allow the subsequent change of address or must change both addresses to the new one.

Integration Payment-API

Authenticaton

Unlike the previous versions, the Payment API is authenticated by means of BASIC Auth. For this purpose, the attribute authorization is expected in the header of each request. The value of the attribute is composed as follows:

Basic <token>

The token is composed of webshop id (e.g. 2.de.9999.9999) and API password. Both are concatenated using : and then encoded using Base64.

<token> => base64(1.de.9999.9999:RatenkaufByEasyCredit123!) => MS5kZS45OTk5Ljk5OTk6UmF0ZW5rYXVmQnlFYXN5Q3JlZGl0MTIzIQ==

The header will then look as follows:

Authorization: "Basic MS5kZS45OTk5Ljk5OTk6UmF0ZW5rYXVmQnlFYXN5Q3JlZGl0MTIzIQ=="

More overall details about BASIC Auth can be found here

Integration Check

To check the correctness of the configuration and credentials in the webshop system, the following endpoint can be called:

  POST ./webshop/integrationcheck

With the request body:

  {
    "message": "easyCredit-Ratenkauf"
  }

On the one hand, the authentication is checked, and on the other hand, the body signature is checked if this has been activated and configured for the web store. If the endpoint returns the HTTP status code 200 and the passed message in the body, the configuration of the credentials and the secret key is correct.

Integrate installment calculator

To draw customers’ attention to easyCredit-Ratenkauf, you can integrate an installment calculator at various points. Of course, this is optional, but it is a crucial component for the success of the installment purchase in the online store. It makes sense to place it on the product detail pages near the price, but the installment calculator can also be integrated on other pages such as the shopping cart page.

All installment plans for all possible terms and a representative example are returned. This can be requested for a single item or for multiple items at once, depending on how many items are passed in the request.

When displaying a single rate, we recommend always displaying the lowest rate first, i.e. the installment purchase with the longest term.

A call of the model calculation is possible without an order process and can be repeated as desired (e.g. after updating the shopping cart).

Currently there are two possibilities how the installment calculator can be technically integrated. On the one hand via a ready-made Web Component, which is provided by us, and on the other hand manually via the corresponding endpoints.

Integration Via Web Component

Example:

General instructions for integrating our web components

Examples and instructions for the widget

Integration Via Endpoint

Example:

POST https://ratenkauf.easycredit.de/api/ratenrechner/v3/webshop/2.de.9999.9999/installmentplans

JSON-Request:

{
    "articles": [
        {
            "identifier": "Washing Machine I",
            "price": 599.95
        },
        {
            "identifier": "Washing Machine II",
            "price": 599.95
        }
    ]
}

JSON-Response:

{
    "installmentPlans": [
        {                               ///Installment plan for article 1
            "example": "Repräsentatives Beispiel: Sollzinssatz <span class=\"nobr\">8,64 % p.a.</span> fest für die gesamte Laufzeit, effektiver Jahreszins <span class=\"nobr\">8,99 %</span>, Bestellwert <span class=\"nobr\">103,00 EUR</span>, Vertragslaufzeit <span class=\"nobr\">6 Monate</span>, Gesamtbetrag <span class=\"nobr\">615,11 EUR</span>, monatliche Rate <span class=\"nobr\">103,00 EUR</span>, letzte Rate <span class=\"nobr\">100,11 EUR.</span> Anbieter: Beispielhändler, Beispielstr. 1, 12345 Beispielstadt\n",
            "articleIdentifier": "Washing Machine I",
            "url": "https://ratenkauf.easycredit.de/widget/app/#/ratenwunsch?bestellwert=599.95&shopKennung=2.de.9999.9999",
            "plans": [
                {
                    "term": 6,
                    "installment": "103.00"
                },
                {
                    "term": 9,
                    "installment": "70.00"
                },
                {
                    "term": 12,
                    "installment": "53.00"
                },
                {
                    "term": 15,
                    "installment": "43.00"
                },
                {
                    "term": 18,
                    "installment": "36.00"
                },
                {
                    "term": 21,
                    "installment": "31.00"
                },
                {
                    "term": 24,
                    "installment": "28.00"
                },
                {
                    "term": 27,
                    "installment": "25.00"
                },
                {
                    "term": 30,
                    "installment": "22.50"
                },
                {
                    "term": 33,
                    "installment": "21.00"
                }
            ]
        },
        {                                       ///Installment plan for article 2
            "example": "Repräsentatives Beispiel: Sollzinssatz <span class=\"nobr\">8,64 % p.a.</span> fest für die gesamte Laufzeit, effektiver Jahreszins <span class=\"nobr\">8,99 %</span>, Bestellwert <span class=\"nobr\">103,00 EUR</span>, Vertragslaufzeit <span class=\"nobr\">6 Monate</span>, Gesamtbetrag <span class=\"nobr\">615,11 EUR</span>, monatliche Rate <span class=\"nobr\">103,00 EUR</span>, letzte Rate <span class=\"nobr\">100,11 EUR.</span> Anbieter: Anbieter: Beispielhändler, Beispielstr. 1, 12345 Beispielstadt\n",
            "articleIdentifier": "Washing Machine II",
            "url": "https://ratenkauf.easycredit.de/widget/app/#/ratenwunsch?bestellwert=599.95&shopKennung=2.de.9999.9999",
            "plans": [
                {
                    "term": 6,
                    "installment": "103.00"
                },
                {
                    "term": 9,
                    "installment": "70.00"
                },
                {
                    "term": 12,
                    "installment": "53.00"
                },
                {
                    "term": 15,
                    "installment": "43.00"
                },
                {
                    "term": 18,
                    "installment": "36.00"
                },
                {
                    "term": 21,
                    "installment": "31.00"
                },
                {
                    "term": 24,
                    "installment": "28.00"
                },
                {
                    "term": 27,
                    "installment": "25.00"
                },
                {
                    "term": 30,
                    "installment": "22.50"
                },
                {
                    "term": 33,
                    "installment": "21.00"
                }
            ]
        }
    ]
}

Check for availability

The availability of the easyCredit-Ratenkauf can be checked via the endpoint GET ./webshop. If this endpoint is accessible and returns the value true for the availability attribute, easyCredit-Ratenkauf is fully available and the payment method can be displayed and used in the web store.

Example:

GET ./webshop

JSON-Response:

{
    "maxFinancingAmount": 10000,
    "minFinancingAmount": 199,
    "interestRate": 8.99,
    "availability": false,
    "testMode": true,
    "privacyApprovalForm": "Ja, ich möchte per Ratenkauf zahlen. Ich habe zur Kenntnis genommen, dass Beispielhändler der TeamBank AG (Partner der Genossenschaftlichen FinanzGruppe Volksbanken Raiffeisenbanken), Beuthener Str. 25, 90471 Nürnberg zur Bonitätsprüfung personenbezogene Daten wie Anrede und Name, Geburtsdatum und -ort, Kontaktdaten (Adresse, Telefon, E-Mail) sowie Angaben zur aktuellen und zu früheren Bestellungen übermittelt und das Prüfungsergebnis zum Zweck des Ratenkaufabschlusses erhält." 
}

Display Data Transmission Notice

After the customer has selected the payment method easyCredit-Ratenkauf, the customer must be informed about the transmission of his data to TeamBank via a message text. The data transfer notice must be displayed before the transaction is initialized and the customer is forwarded to the payment page.

In contrast to previous versions, explicit consent via checkbox is no longer required.

Example:

The texts can be dynamically loaded and integrated via the ‘GET ./webshop’ endpoint. This ensures that legally relevant changes to the consent texts are adopted directly and no manual adjustments are required in the webshop.

Example:

GET ./webshop

JSON-Response:

{
    "maxFinancingAmount": 10000,
    "minFinancingAmount": 199,
    "interestRate": 8.99,
    "availability": true,
    "testMode": true,
    "privacyApprovalForm": "Ja, ich möchte per Ratenkauf zahlen. Ich habe zur Kenntnis genommen, dass TeamBank-Testshop der TeamBank AG (Partner der Genossenschaftlichen FinanzGruppe Volksbanken Raiffeisenbanken), Beuthener Str. 25, 90471 Nürnberg zur Bonitätsprüfung personenbezogene Daten wie Anrede und Name, Geburtsdatum und -ort, Kontaktdaten (Adresse, Telefon, E-Mail) sowie Angaben zur aktuellen und zu früheren Bestellungen übermittelt und das Prüfungsergebnis zum Zweck des Ratenkaufabschlusses erhält." // Text for data transmission notice
}

Initialization

The initialization creates a new installment purchase transaction and takes place when the customer, after selecting the payment method and agreeing to the data transfer, has clicked on "Next".

During initialization, the necessary information from the webshop is transferred to the payment API (customer data, billing & shipping address, technical data such as return URLs on success/rejection, etc.).

The data groups customer, customerRelationship and shoppingCartInformation are to be passed to the installment purchase as completely as possible! This includes the attributes customerSince, orderDoneWithLogin, numberOfOrders and logisticsServiceProvider from the group customerRelationship.
In addition, the attributes price, quantity, productName in the shoppingCartInformation group must be added to each item in the shopping cart.

If some of the required information cannot be provided, please contact us.

It is also important that the criteria from the chapter Prerequisites are followed. In particular, it is important to ensure that Invoice & Shipping Address are transferred to the respective fields provided. If only one of the addresses is transferred to both shippingAddress and invoiceAddress, there is a risk that this may result in orders being placed with different addresses. This must be prevented.

The API provides a transactionId (business transaction identifier) and a technicalTransactionId (technical transaction identifier) as a response.

The technicalTransactionId is only used in the communication between the webshop and the payment API, but is important there for all other endpoints, such as retrieving a decision or authorizing a transaction.

The transactionId (6-digit, alpha-numeric, e.g. TXQ7FG) is used in communication with customers and contact persons at TeamBank.

In addition to the other ReturnURLs, the urlAuthorizationCallback must also be passed. It will be needed later for the verification of the completed order.

Optionally, the web store can pass its own order ID during initialization. This will be additionally linked to the transaction and can be used in the communication between merchant and TeamBank (e.g. in the Transaction Management).

An installment purchase transaction expires 30 minutes after the last update by the user. If the webshop has its own session, this must be maintained for the duration of the customer’s stay on the payment page (again, at least 30 minutes is recommended).

Example:

POST https://ratenkauf.easycredit.de/api/payment/v3/transaction

JSON-Request:

{
    "orderDetails": {
        "orderValue": 2614.79,
        "invoiceAddress": {
            "address": "Beuthener Str. 25",
            "zip": "90471",
            "city": "Nürnberg",
            "country": "DE",
            "additionalAddressInformation": "3 OG"
        },
        "shippingAddress": {
            "address": "Beuthener Str. 25",
            "city": "Nürnberg",
            "country": "DE",
            "firstName": "Max",
            "lastName": "Müller",
            "zip": "90471",
            "additionalAddressInformation": "3 OG"
        },
        "orderId": "A1ZU560", // The shop's own OrderId
        "numberOfProductsInShoppingCart": 2,
        "shoppingCartInformation": [
            {
                "productName": "Washing Machine",
                "quantity": 1,
                "price": 599.95,
                "manufacturer": "Example vendor",
                "productCategory": "Household Appliances"
            }
        ]
    },
    "customer": {
        "firstName": "Max",
        "lastName": "Müller",
        "contact": {
            "email": "test@teambank.de",
            "mobilePhoneNumber": "01701234567",
            "skipMobilePhoneNumberCheck": false,
            "phoneNumber": "Ut velit aute occaecat minim"
        },
        "gender": "MR",
        "birthDate": "1949-10-17",
        "birthName": "   ",
        "birthPlace": "laboris dolore exercitation eu ipsum",
        "title": "DRDR",
        "bank": {
            "iban": "DE02120300000000202051"
        },
        "employment": {
            "employmentType": "WORKER",
            "monthlyNetIncome": 3000
        }
    },
    "redirectLinks": {
        "urlSuccess": "https://www.beispielwebshop.de/payment_easycredit/return",
        "urlCancellation": "https://www.beispielwebshop.de/module/easycreditratenkauf/canceled",
        "urlDenial": "https://www.beispielwebshop.de/module/easycreditratenkauf/denied",
        "urlAuthorizationCallback": "https://www.beispielwebshop.de/module/easycreditratenkauf/callback"
    },
    "financingTerm": 6,
    "shopsystem": {
        "shopSystemManufacturer": "Shopware 5.5.10",
        "shopSystemModuleVersion": "1.6.3"
    },
    "customerRelationship": {
        "orderDoneWithLogin": false,
        "customerStatus": "NEW_CUSTOMER",
        "customerSince": "2007-10-10",
        "numberOfOrders": 3,
        "negativePaymentInformation": "NO_INFORMATION",
        "riskyItemsInShoppingCart": false,
        "logisticsServiceProvider": "Hermes"
    }
}

JSON-Response:

{
    "technicalTransactionId": "1.de.4145.1-1020125121-545", // technical transaction id
    "transactionId": "V32N3T",                              // business transaction id
    "deviceIdentToken": "a28129b8-3f05-4311-89cf-5f35c44c12a3",
    "timestamp": "2021-10-20T12:51:21.552704+02:00",
    "transactionInformation": {
        "decision": {
            "orderValue": 2614.79,
            "interest": 66.27,
            "totalValue": 2681.06,
            "decisionOutcome": null,
            "numberOfInstallments": 6,
            "installment": 447.00,
            "lastInstallment": 446.06,
            "mtan": {
                "required": true,
                "successful": null,
                "mobilePhoneNumberInvalid": true,
                "skipMobilePhoneNumberValidation": true
            },
            "bankAccountCheck": {
                "required": null,
                "successful": null
            }
        },
        "transaction": {
            "financingTerm": 6,
            "orderDetails": {
                "orderValue": 2614.79,
                "orderId": "A1ZU560",
                "numberOfProductsInShoppingCart": 2,
                "invoiceAddress": {
                    "address": "Beuthener Str. 25",
                    "additionalAddressInformation": "3 OG",
                    "zip": "90471",
                    "city": "Nürnberg",
                    "country": "DE",
                    "firstName": null,
                    "lastName": null
                },
                "shippingAddress": {
                    "address": "Beuthener Str. 25",
                    "additionalAddressInformation": "3 OG",
                    "zip": "90471",
                    "city": "Nürnberg",
                    "country": "DE",
                    "firstName": "Max",
                    "lastName": "Müller"
                },
                "shoppingCartInformation": [
                    null
                ]
            },
            "shopsystem": {
                "shopSystemManufacturer": "Shopware 5.5.10",
                "shopSystemModuleVersion": "1.6.3"
            },
            "customer": {
                "gender": "MR",
                "firstName": "Max",
                "lastName": "Müller",
                "birthDate": "1949-10-17",
                "birthName": "   ",
                "birthPlace": "laboris dolore exercitation eu ipsum",
                "title": "DRDR",
                "contact": {
                    "email": "test@teambank.de",
                    "mobilePhoneNumber": "01701234567",
                    "phoneNumber": "Ut velit aute occaecat minim",
                    "phoneNumbersConfirmed": true
                },
                "bank": {
                    "iban": "DE02120300000000202051"
                },
                "employment": {
                    "employmentType": "WORKER",
                    "monthlyNetIncome": 3000
                }
            },
            "customerRelationship": {
                "customerStatus": "NEW_CUSTOMER",
                "customerSince": "2007-10-10",
                "orderDoneWithLogin": false,
                "numberOfOrders": 3,
                "negativePaymentInformation": "NO_INFORMATION",
                "riskyItemsInShoppingCart": false,
                "logisticsServiceProvider": "Hermes"
            },
            "redirectLinks": {
                "urlSuccess": "https://www.beispielwebshop.de/payment_easycredit/return",
                "urlCancellation": "https://www.beispielwebshop.de/module/easycreditratenkauf/canceled",
                "urlDenial": "https://www.beispielwebshop.de/module/easycreditratenkauf/denied",
                "urlAuthorizationCallback": null
            },
            "consent": {
                "sepaMandate": null,
                "advertisement": false,
                "dataProcessing": null
            }
        },
        "status": "OPEN"
    }
}

Redirect To Payment Page

After successful initialization, combine the URL below with the technicalTransactionId you receive in the response to redirect the customer to the payment page:

https://ratenkauf.easycredit.de/app/payment/{technicalTransactionId}/finanzierungsvorgaben

Important:

The button that triggers the redirection must not be named "Finish Order" or similar, since the ordering process is not yet completed at this point. Better is e.g. "Continue to easyCredit-Ratenkauf".

On the payment page, the customer can once again select the desired installment plan, add his personal data such as IBAN and mobile phone number, and finally run the credit check. Depending on the result, the customer is redirected to one of the three previously specified return URLs (urlSuccess, urlCancellation or urlDenial).

Payment page example:

Rejection Or Cancellation

In the event that the customer cannot be offered a easyCredit-Ratenkauf or has cancelled, the customer should be redirected back to the payment method selection.

Success & Return

Also in case of success, the customer is redirected back to the checkout via urlSuccess to be able to complete his order there. The redirection usually takes place to the last page of the checkout before the order is completed, on which all details and items are once again clearly presented to the customer.

The fact that the credit check has been positively decided does not mean at this point that the easyCredit-Ratenkauf has been completed, but rather that TeamBank guarantees the purchase of the receivables. Only when the customer has completed the order, easyCredit-Ratenkauf is also completed.

From the easyCredit-Ratenkauf point of view, there are still two steps to be completed on the order summary page:

• Retrieve the result of the credit check
• Display installment purchase interest

Retrieve credit check result:

For security reasons, it is necessary to retrieve the result of the credit decision from the store once again after returning to the checkout. This is done via the endpoint GET ./transaction/{id}.

Example:

GET ./transaction/{id}

JSON-Response:

{
    "decision": {
        "orderValue": 2614.79,
        "interest": 611.95,
        "totalValue": 3226.74,
        "decisionOutcome": "POSITIVE", // credit check result
        "numberOfInstallments": 60,
        "installment": 54,
        "lastInstallment": 40.74,
        "mtan": {
            "required": false,
            "successful": null,
            "mobilePhoneNumberInvalid": null,
            "skipMobilePhoneNumberValidation": null
        },
        "bankAccountCheck": {
            "required": false,
            "successful": null
        }
    },
    "transaction": {
        ...
        }
    },
    "status": "PREAUTHORIZED"
}

Only as long as the decisionOutcome is POSITIVE, the customer shall be able to order. In all other cases, the order shall not be able to proceed with the installment purchase.

Display of the installment purchase interest:.

Legally, it is necessary to show the customer all the costs associated with the purchase, including the installment purchase interest, before the order is completed.

For this purpose, the interest must be explicitly displayed as a separate item in the overview of items and simultaneously included in the total amount.

Example:

Just like the result of the credit check, the interest can be obtained through the GET ./transaction{id} endpoint:

Example:

GET ./transaction/{id}

JSON-Response:

{
    "decision": {
        "orderValue": 2614.79,
        "interest": 611.95,
        "totalValue": 3226.74,
        "decisionOutcome": "POSITIVE", 
        "numberOfInstallments": 60,
        "installment": 54,
        "lastInstallment": 40.74,
        "mtan": {
            "required": false,
            "successful": null,
            "mobilePhoneNumberInvalid": null,
            "skipMobilePhoneNumberValidation": null
        },
        "bankAccountCheck": {
            "required": false,
            "successful": null
        }
    },
    "transaction": {
        ...
        }
    },
    "status": "PREAUTHORIZED"
}

Confirmation & Callback

If the customer has clicked on "Complete order" / "Zahlungspflichtig bestellen", confirmation or authorization of the transaction now follows. For this purpose, the new 2-step confirmation has been introduced, which ensures that an order can only be successfully completed if the confirmation of the easyCredit-Ratenkauf has also worked beforehand.

The workflow for this is as follows:

Authorization:

After checking in the previous step that the transaction is pre-authorized (Status preAuthorized), the authorization must now take place for the completion.

This is done via the endpoint POST ./transaction/{id}/authorization.

The successful authorization is acknowledged with the HTTP status code 202. The customer can now be shown the "Thank-you-for-your-order" page.

Only if the response was checked and successful (202), the store is allowed to create the order. If this is not met, the order should not be allowed to be completed.

Example:

POST ./transaction/{id}/authorization

JSON-Request:

{
  "orderId": AGSX1232  // shop's own OrderId
}

JSON-Response:

Status 202 Accepted

As can be seen in the example above, a shop-specific order ID can optionally be transferred to TeamBank in this step ("orderId ").
Analogous to the initialization, this orderId is then linked to the transaction and displayed, for example, on billing documents or in the Partner Portal.

Check authorization:

To prevent goods from being mistakenly shipped even though easyCredit-Ratenkauf has not been completed, two mandatory options are available, the status check and the callback.

Status Check

Before the final order confirmation mail is sent by the store system or the payment status is set to "PAID", the endpoint GET ./transaction/{id} must be used to check whether the authorization was completed successfully.

To do this, the Status attribute in the body of the response must be checked. If the status is authorized, the authorization has been successfully processed, the installment purchase has been finally confirmed and the order confirmation can be sent to the end customer.

If this is not the case, the call should be repeated several times within the next few minutes. If the status is still not authorized, a new authorization can be executed.

Example:

  GET ./transaction/{id}

JSON-Response:

  {
    "decision": {
        ...
    },
    "transaction": {
        ...
    },
    "status": "AUTHORIZED"
}

This also completes the installment purchase process and the technicalTransactionId expires.

Callback

In addition, it is necessary that the callback URL (urlAuthorizationCallback) is successfully accepted by the webshop before the payment status is set to "PAID". This URL is transferred to us during the initialization of the installment purchase and is called by TeamBank’s servers as soon as the installment purchase is completely finished and available in our systems.

After the completed installment purchase, it is necessary to report the shipment / capture of the order to TeamBank. Only after that the payment to the merchant and the installment collection from the customer will take place. You can find more details about this here

Optional: Body Signature

The body signature can be used to sign the requests to us if required. This ensures that the requests have not been manipulated on the way to and from the payment API. By default, this function is disabled and optional for the integration.

If you would like to use the function, you must activate the body signature via the Partner Portal.

In the first step, you have to generate a secret key and store it in the webshop or plugin. Then, in the second step, you activate the feature in the partner portal. From this point on, only signed requests are accepted and processed by the API.

After successful activation, all requests must contain the header attribute Content-signature. The calculated signature for the JSON-formatted body of the request is entered in this attribute. The signature is generated as follows:

SHA256( yourJsonBody + signatureSecret )

In the first step the json body is normalized by removing all tabs (\t), new lines (\n) and carriage returns (\r). Afterwards the secret key is concatinated to the normalized body.

The hash value for this string is now calculated using the SHA-256 method and set as the value of the header attribute Content-signature.

Example:

Geheimschlüssel	Geh31m5chue5531

Body:

  {
    "message": "ratenkaufByEasyCredit"
  }

Computation:

  SHA256({    "message": "easyCredit-Ratenkauf"}Geh31m5chue5531)

Header attribute:

  Content-signature: sha256=0d17b9d8c6ad49aaced5cff8788550efe539905a59dc7e1550a85554a3208507

If the signature in the header matches the body, the request is processed by us. If it differs, this is acknowledged with the status code 400. No processing takes place.

In addition to the requests, the responses from our payment API are also signed by us when the body signature is activated in the partner portal. The store’s secret key is also used for this purpose. This enables the web store to check the body signature of our response and ensure that the response has not been manipulated. To do this, the signature of the response body must be calculated in the same way as for the request body. Afterwards the calculated signature can be compared with the signature from the header attribute Content-signature of the response. If the values match, the response can be processed by the store system. Otherwise, it should be discarded.

After The Order

If the order has been correctly received in your store system and the goods are ready for shipment, then it is necessary to notify TeamBank that the goods have been shipped (i.e. capture). Only after that, on the one hand, the collection of installments from the customer and, on the other hand, the payment to the merchant will start.

There is also a possibility to report partial or complete refunds to us, regardless of whether the goods have already been shipped or not yet.

Details on this can also be found in our Merchant Manual.

Both can be done either via the provided Partner Portal or via a separate API that you can integrate with your system, the Transaction API.

Integration Transaction API

In addition to the Payment API, which has been the main focus so far, there is also the Transaction API (formerly the Merchant Interface API), which can be used for reporting shipments and refunds.

If desired, you can integrate this into your store system or ERP in order to embed these processes into your existing workflow in as automated a manner as possible.

Unlike the Payment API or the former Merchant Interface API, the Transaction API is an asynchronous interface.

The documentation for the integration of the Transaction API can be found here and the Integration Guide here.

Go-Live & Acceptance Test

Checklist

You want to know if you have thought of everything and if your integration can be taken off? Then you can use our checklist to help you:

• Complete workflow incl. authorization

  All transaction relevant endpoints mentioned above have been called, the status of the transaction is authorized and the authorization has been checked again with GET ./transaction/{id}.

• Display data transmission notice

  The data transmission hint is displayed during the payment method selection screen.

• Display interest on order summary page

  On the order summary page (before completion), interest is displayed to the customer as a separate item and is included in the total amount.

• Display GTC Supplements

  (Only relevant for store operators) On the store page of the GTC, the GTC Supplements of TeamBank are displayed.

• Display installment calculator (optional)

  On the product pages, the easyCredit-Ratenkauf widget is displayed with the product price and can be opened.

Acceptance Test

After the successful integration of the easyCredi-Ratenkauf, an acceptance test by our team is mandatory. For this purpose, we carry out one or more test purchases, document the individual steps and, if needed, of course give you advice if something can be improved.

If all points of the checklist are fulfilled, then feel free to contact ratenkauf@easycredit.de. There we will gladly support you in going live.

Web Components

We have been providing Web Components on a central level for some time now.

The easyCredit-Ratenkauf web components are a set of components that can be used universally in e-commerce platforms such as Magento or Shopware and others. The web components ease the integration of the easyCredit-Ratenkauf payment solution by providing versatile web front-end elements for marketing, checkout and merchant management.

Installation instructions and many interactive examples of the components can be found here:

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/getting-started-installation–page

Beispiele

Example Calculator-Widget

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/marketing-widget–widget-normal

Checkout-Widget

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/checkout-checkout–checkout-initial

Infopage incl. FAQ

https://netzkollektiv.com/docs/ratenkaufbyeasycredit-components/?path=/docs/marketing-infopage–infopage

Integration Via Script

To integrate the Web Components into any system, add the following lines to the <head> of your store:

<script type="module" src="https://ratenkauf.easycredit.de/api/resource/webcomponents/v3/easycredit-components/easycredit-components.esm.js"></script>
<script nomodule src="https://ratenkauf.easycredit.de/api/resource/webcomponents/v3/easycredit-components/easycredit-components.js"></script>

Now you can use any of the components within your website:

<easycredit-widget amount="500" webshop-id="1.de.1234" />

Use In Existing Javascript Project

To use the components in a JavaScript project, you can install the NPM package:

npm install --save @easycredit-ratenkauf/web-components
# or
yarn add @easycredit-ratenkauf/web-components

Having done this, you can now import the components:

import { EasyCreditWidget } from "@easycredit-ratenkauf/web-components";

Appendix

Definition Of Terms

Device Ident

Service that collects and uses device-specific information to identify potential cases of fraud. The data collected is anonymous in the sense that it is not possible to draw any conclusions about the person from this alone. The device used is recognized and receives a score based on its activity profile via a set of rules that a customer (e.g. TeamBank) can edit and define.

Credit Check Result / Decision Outcome

Result of credit check of TeamBank whether to grant financing to a customer ("POSITIVE") or not ("NEGATIVE"). A positive decision with mandatory adjustment of the term ("POSITIVE with restriction") does not represent an independent decision result.

Order Value / Financing Amount

The monetary amount for the product(s) incl. shipping costs of a merchant that a customer wants to finance via easyCredit-Ratenkauf.

Financing Commitment

A financing commitment by TeamBank to the merchant means that TeamBank agrees to provide the installment purchase at the specified conditions. The commitment is subject to an order placed by the customer in the web store of a merchant.

Term

Time in months within which a customer must repay the order value plus interest to TeamBank.

Installment purchase transaction

The transaction data of an installment purchase includes all relevant information for the transaction processing of the installment purchase, including e.g. transaction status, customer data, merchant ID.

Installment plan

Information basis of the financing for the customer. Includes installment amount, term, total amount, effective interest rate and dates for first and last installment.

Webshop ID

TeamBank provides a unique identifier, which also serves as a unique web store identifier and is communicated manually to the merchant.

Technical Transaction ID

A globally unique identifier, in the technicalTransactionId interface model in the general transaction data, by means of which the transaction data of a specific customer can be identified. Navigation of the customer from the web store to the payment page or access from the web store to the transaction is only done with this transaction identifier, from which no inference to the data is possible. The payment page uses the technicalTransactionID to load the previously initialized transaction data. Since the customer has not yet consented to the storage of data at this point, data from initialized transactions that have not been processed further are completely deleted after a reasonably short period of time (currently 30 minutes).

After an order has been placed or has expired, the technicalTransactionId will not be used any further. An installment purchase transaction can also no longer be identified in our Partner Portal via the technicalTransactionId.

Shop Order ID

A reference used by the merchant to the customer or internally in accounting to the order in the store. The store’s own order number is not used for technical identification of a transaction, but only for human traceability, e.g. in merchant billing. Completed installment purchase orders can also be searched for in the Partner Portal using the Bestellnummer column.

Transaction ID

A human-readable, unique, six-digit ID by means of which the transaction data of a particular order can be identified. The transaction ID is the official reference to the easyCredit-Ratenkauf and is used in the pre-contractual information and in the follow-up processes of credit processing (after the order has been placed) as the primary identifier of the transaction in human and technical communication with merchants and customers.