Introduction

Description of the changes which are required by easyCredit API update, which impacts implementation and requires changes on the merchant side.

Required changes

Creation of Payment

API calls which are in scope of change are marked in red:

Changes are in 2 API calls:

2. Initial creation of payment

1. changes in parameters
  1. new parameters
  2. modification of existing ones

11. Getting the information about transaction and financing

1. response parameters "Decision" and "Process" are deprecated
2. response parameter "Financing" is modified
  1. more data
  2. payload is in English, not in German

Capture & Credit

These Actions are now asynchronous.

This means, that will responde always with Status=Request and update the final Status asynchronously, by sending notification to URLNotify, defined in the initial payment creation.

Details are described below.

Detailed description of changes

1. Initial request to: easyCredit.aspx

Key

Format

CND

Description: current integration

Description: new integration (version=v3)

Beschreibung: aktuelle Integration

Beschreibung: neue Integration (Version=v3)

version

an2

C

N/A

Mandatory for using new easyCredit API v3, please pass value: "v3"

Example: ...&version=v3&...

N/A

Mandatory for using new easyCredit API v3, please pass value: "v3"

Example: ...&version=v3&...

bdFirstName

ans..50

M

N/A

First name in invoicing address

N/A

Vorname in der Rechnungsadresse

bdLastName

ans..50

M

N/A

Last name in invoicing address

N/A

Nachname in der Rechnungsadresse

sdFirstName

ans..50

M

N/A

First name in delivery address

N/A

Vorname in der Lieferadresse

sdLastName

ans..50

M

N/A

Last name in delivery address

N/A

Nachname in der Lieferadresse

Employment

enum

C

Occupation of the customer. Possible entries are:

ANGESTELLTER

ANGESTELLTER_OEFFENTLICHER_DIENST

ARBEITER

BEAMTER

RENTNER

SELBSTAENDIGER

ARBEITSLOSER

SONSTIGES

Occupation of the customer. Possible entries are:

EMPLOYEE

EMPLOYEE_PUBLIC_SECTOR

WORKER

CIVIL_SERVANT

RETIREE

SELF_EMPLOYED

UNEMPLOYED

OTHER

Beruf des Kunden. Mögliche Einträge sind:

ANGESTELLTER

ANGESTELLTER_OEFFENTLICHER_DIENST

ARBEITER

BEAMTER

RENTNER

SELBSTAENDIGER

ARBEITSLOSER

SONSTIGES

Beruf des Kunden. Mögliche Einträge sind:

EMPLOYEE

EMPLOYEE_PUBLIC_SECTOR

WORKER

CIVIL_SERVANT

RETIREE

SELF_EMPLOYED

UNEMPLOYED

OTHER

ArticleList

ans..1024

O

Basket information (incl. article numbers) for the articles ordered with hire purchase. These data can have some influence on the credit decision. The article list must be created in JSON format.

Example:

Afterwards the article list created in JSON format must be Base64 encoded.

Basket information (incl. article numbers) for the articles ordered with hire purchase. These data can have some influence on the credit decision. The article list must be created in JSON format.

{
  "shoppingCartInformation": [
      {
        "productName": "Washing Machine",
        "quantity": 1,
        "price": 599.95,
        "manufacturer": "Siemens",
        "productCategory": "Household Appliances",
        "articleNumber": [
          {
            "numberType": "GTIN",
            "number": 1111111
          }
        ]
      }
    ]
}

Afterwards the article list created in JSON format must be Base64 encoded.

Warenkorbinformationen (inkl. Artikelnummern) zu den per Ratenkauf bestellten Artikeln. Diese Daten können einen gewissen Einfluss auf die Kreditentscheidung haben. Die Artikelliste muss im JSON-Format erstellt werden.

Example:

Anschließend muss die im JSON-Format erstellte Artikelliste Base64-kodiert werden.

Warenkorbinformationen (inkl. Artikelnummern) zu den per Ratenkauf bestellten Artikeln. Diese Daten können einen gewissen Einfluss auf die Kreditentscheidung haben. Die Artikelliste muss im JSON-Format erstellt werden.

{
  "shoppingCartInformation": [
      {
        "productName": "Washing Machine",
        "quantity": 1,
        "price": 599.95,
        "manufacturer": "Siemens",
        "productCategory": "Household Appliances",
        "articleNumber": [
          {
            "numberType": "GTIN",
            "number": 1111111
          }
        ]
      }
    ]
}

Anschließend muss die im JSON-Format erstellte Artikelliste Base64-kodiert werden.

URLNotify

ans..256

M

Complete URL which calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead.

Complete URL which calls up in order to notify the shop about the payment result and result of Capture and Credit. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead.

Vollständige URL, die das aufruft, um den Shop über das Zahlungsergebnis zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Sie darf keine Parameter enthalten: Nutzen Sie stattdessen den Parameter UserData.

Vollständige URL, die das aufruft, um den Shop über das Zahlungsergebnis und das Ergebnis von Buchung and Gutschrift zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Sie darf keine Parameter enthalten: Nutzen Sie stattdessen den Parameter UserData.

New validation logic

The delivery address must match the invoice address or it must be a packstation.
FirstName and LastName of delivery and customer should match.
The invoice address must match the delivery address.
FirstName and LastName of Invoice Address and customer should match.

Example Request and Response

Example request
===============

MerchantID=YourMerchantID
TransID=123456
RefNr=27022017_01
Amount=59995
Currency=EUR
EventToken=INT
URLFailure=https://your.shop.info/failure.aspx
URLSuccess=https://your.shop.info/success.aspx
URLNotify=https://your.shop.info/notify.aspx
Salutation=MR
FirstName=John
LastName=Doe
DateOfBirth=1999-02-02
bdFirstName=John
bdLastName=Doe
bdStreet=Schwarzenbergstraße
bdStreetNr=4
bdAddressAddition=Computop GmbH
bdZip=96050
bdCity=Bamberg
bdCountryCode=DE
PackingStation=NO
sdFirstName=John
sdLastName=Doe
sdStreet=Schwarzenbergstraße
sdStreetNr=4
sdAddressAddition=Computop GmbH
sdZip=96050
sdCity=Bamberg
sdCountryCode=DE
Email=max@mustermann.de
Employment=EMPLOYEE
MonthlyNetIncome=100000
Phone=015124011444
CustomerSince=1999-02-02
CustomerLoggedIn=YES
NumberOrders=1
ArticleList=ew0KCSJzaG9wcGluZ0NhcnRJbmZvcm1hdGlvbiI6IFsNCgkJew0KCQkJInByb2R1Y3ROYW1lIjogIldhc2hpbmcgTWFjaGluZSIsDQoJCQkicXVhbnRpdHkiOiAxLA0KCQkJInByaWNlIjogNTk5Ljk1LA0KCQkJIm1hbnVmYWN0dXJlciI6ICJTaWVtZW5zIiwNCgkJCSJwcm9kdWN0Q2F0ZWdvcnkiOiAiSG91c2Vob2xkIEFwcGxpYW5jZXMiLA0KCQkJImFydGljbGVOdW1iZXIiOiBbDQoJCQkgIHsNCgkJCQkibnVtYmVyVHlwZSI6ICJHVElOIiwNCgkJCQkibnVtYmVyIjogMTExMTExMQ0KCQkJICB9DQoJCQldDQoJCX0NCgldDQp9
version=v3

Example response
================

mid=YourMerchantID
PayID=e8be1739b7754b68b4a53bbf33670efc
TransID=123456
XID=b4b01e1654744bdd87fbb496cbbf79e1
refnr=27022017_01
Status=AUTHORIZE_REQUEST
Code=0
Description=REQUEST

2. Retrieving information about installments easyCreditDirect.aspx

The request remains the same. The parameter 'version=v3' ist not needed anymore.

The response now containes only the 'Financing' parameter instead of all three parameters 'Decision', 'Process' and 'Financing'.

Key

Format

CND

Description: current integration

Description: new integration (version=v3)

Beschreibung: aktuelle Integration

Beschreibung: neue Integration (Version=v3)

EventToken

enum

M

Defines the request to be made at easyCredit:

<DEC> loads decision date for a previous initialization

<PRO> loads general transaction data for a previous initialization

<FIN> loads financing data for a previous initialization

<GET> With this EventToken the three requests <DEC>, <PRO> and <FIN> can be triggered with one call (recommended).

Defines the request to be made at easyCredit:

<GET> With this EventToken all the installment information will be retrieved.

Definiert die bei easyCredit zu stellende Anfrage:

<DEC> lädt Entscheidungsdatum für eine vorherige Initialisierung

<PRO> lädt allgemeine Transaktionsdaten für eine vorherige Initialisierung

<FIN> lädt Finanzierungsdaten für eine vorherige Initialisierung

<GET> Mit diesem EventToken können die drei Anfragen <DEC>, <PRO> und <FIN> mit einem Aufruf ausgelöst werden (empfohlen).

Definiert die bei easyCredit zu stellende Anfrage:

<GET> Mit diesem EventToken werden alle Rateninformationen abgerufen.

Key

Format

CND

Description: current integration

Description: new integration (version=v3)

Beschreibung: aktuelle Integration

Beschreibung: neue Integration (Version=v3)

Decision

ans..1024

O

Contains decision data for a previous initialization. There are returned in JSON format and Base64 encoded.

Example JSON format (already Base64 decoded):

Notice: Important within this answer is the "decision result" below "decision". Only in case of positive „GREEN“ decided hire purchase all numbers, amounts and information connected with this hire purchase should be presented to the customer on the final confirmation page in the shop. These includes:

- the duration selected by the customer (number of installments)

- the repayment plan (including alternative repayment plan)

- precontractual information (a link to the system hire purchase)

- total amount with designated interest amounts for hire purchase

All information are returned within parameters Process and Financing.

Deprecated

Enthält Entscheidungsdaten für eine vorherige Initialisierung. Sie werden im JSON-Format und Base64-codiert zurückgegeben.

Beispiel JSON-Format (bereits Base64-dekodiert):

Hinweis: Wichtig innerhalb dieser Antwort ist das "Entscheidungsergebnis" unter "Entscheidung". Nur bei positiv „GRÜN“ entschiedenem Ratenkauf sollten dem Kunden alle mit diesem Ratenkauf verbundenen Zahlen, Beträge und Informationen auf der abschließenden Bestätigungsseite im Shop präsentiert werden. Dazu gehören:

- die vom Kunden gewählte Laufzeit (Anzahl der Raten)

- der Tilgungsplan (einschließlich alternativem Tilgungsplan)

- vorvertragliche Informationen (ein Link zum Systemmietkauf)

- Gesamtbetrag mit ausgewiesenen Zinsbeträgen für Ratenkauf

Alle Informationen werden in den Parametern Process und Financing zurückgegeben.

Veraltet

Process

ans..1024

O

Contains general transaction data for a previous initialization. They are returned in JSON format and Base64 encoded.

Example JSON format (already Base64 decoded):

Deprecated

Enthält allgemeine Transaktionsdaten für eine vorherige Initialisierung. Sie werden im JSON-Format und Base64-codiert zurückgegeben.

Beispiel-JSON-Format (bereits Base64-dekodiert):

Veraltet

Financing

ans..1024

O

Contains financing data for a previous initialization. They are returned in JSON format and Base64 encoded.

Example JSON format (already Base64 decoded):

Contains all the necessary data for a previous initialization. They are returned in JSON format and Base64 encoded.

Example JSON format (already Base64 decoded):

{
  "decision": {
    "transactionId": "EWZEN7",
    "deviceIdentToken": "dffedf20-21df-11ec-9621-0242ac130002",
    "orderValue": 2614.79,
    "interest": 234.56,
    "nominalInterest": 8.64,
    "effectiveInterest": 8.99,
    "merchantSpecificInterest": 8.99,
    "totalValue": 2849.35,
    "decisionOutcome": "POSITIVE",
    "numberOfInstallments": 9,
    "minNumberOfInstallments": 2,
    "maxNumberOfInstallments": 60,
    "installment": 302,
    "lastInstallment": 293.58,
    "firstInstallmentDate": "2023-03-20",
    "lastInstallmentDate": "2023-03-20",
    "amortizationPlanText": "string",
    "urlPreContractualInformation": "string",
    "installmentPlans": [
      {
        "totalValuePlan": 0,
        "interests": {
          "effectiveInterest": 8.99,
          "nominalInterest": 8.64,
          "interest": 234.56
        },
        "paymentPlan": {
          "numberOfInstallments": 9,
          "firstInstallmentDate": "2023-03-20",
          "lastInstallmentDate": "2023-03-20",
          "installment": 302,
          "lastInstallment": 293.58
        }
      }
    ],
    "mtan": {
      "required": true,
      "status": "PENDING",
      "remainingAttempts": 2,
      "successful": true,
      "mobilePhoneNumberInvalid": true,
      "skipMobilePhoneNumberValidation": true
    },
    "bankAccountCheck": {
      "required": false,
      "successful": false
    }
  },
  "transaction": {
    "financingTerm": 6,
    "orderDetails": {
      "orderValue": 2614.79,
      "orderId": "A1ZU560",
      "numberOfProductsInShoppingCart": 1,
      "invoiceAddress": {
        "address": "Beuthener Str. 25",
        "additionalAddressInformation": "3 OG",
        "zip": "90471",
        "city": "Nürnberg",
        "country": "DE",
        "firstName": "Ralf",
        "lastName": "Ratenkauf"
      },
      "shippingAddress": {
        "address": "Beuthener Str. 25",
        "additionalAddressInformation": "3 OG",
        "zip": "90471",
        "city": "Nürnberg",
        "country": "DE",
        "firstName": "Ralf",
        "lastName": "Ratenkauf",
        "packageStation": true
      },
      "shoppingCartInformation": [
        {
          "productName": "Washing Machine",
          "quantity": 1,
          "price": 599.95,
          "manufacturer": "Siemens",
          "productCategory": "Household Appliances",
          "articleNumber": [
            {
              "numberType": "GTIN",
              "number": 1111111
            }
          ]
        }
      ]
    },
    "shopsystem": {
      "shopSystemManufacturer": "Shopware 5.5.10",
      "shopSystemModuleVersion": "1.6.3"
    },
    "customer": {
      "gender": "MR",
      "firstName": "Ralf",
      "lastName": "Ratenkauf",
      "birthDate": "1949-10-17",
      "birthName": "string",
      "birthPlace": "string",
      "title": "PROFDR",
      "contact": {
        "email": "test@test.de",
        "mobilePhoneNumber": "017186397426",
        "phoneNumber": "01771234567",
        "phoneNumbersConfirmed": false
      },
      "bank": {
        "iban": "DE06760320009210030015",
        "bic": "MARKDEFFXXX"
      },
      "employment": {
        "employmentType": "EMPLOYEE",
        "monthlyNetIncome": 3000
      },
      "companyName": ""
    },
    "customerRelationship": {
      "customerStatus": "EXISTING_CUSTOMER",
      "customerSince": "2007-10-10",
      "orderDoneWithLogin": false,
      "numberOfOrders": 3,
      "negativePaymentInformation": "NO_INFORMATION",
      "riskyItemsInShoppingCart": false,
      "logisticsServiceProvider": "Hermes"
    },
    "consent": {
      "sepaMandate": true,
      "advertisement": true,
      "dataProcessing": true,
      "consentToActInOnwnName": true
    },
    "redirectLinks": {
      "urlSuccess": "https://www.google.com/search?q=easycreditSuccess",
      "urlCancellation": "https://www.google.com/search?q=easycreditCanceled",
      "urlDenial": "https://www.google.com/search?q=easycreditDenied",
      "urlAuthorizationCallback": "https://www.google.com/search?=ratenkaufCallback"
    }
  },
  "status": "OPEN"
}

Enthält Finanzierungsdaten für eine vorherige Initialisierung. Sie werden im JSON-Format und Base64-codiert zurückgegeben.

Beispiel-JSON-Format (bereits Base64-dekodiert):

Enthält alle notwendigen Daten für eine vorherige Initialisierung. Sie werden im JSON-Format und Base64-codiert zurückgegeben.

Beispiel-JSON-Format (bereits Base64-dekodiert):

{
  "decision": {
    "transactionId": "EWZEN7",
    "deviceIdentToken": "dffedf20-21df-11ec-9621-0242ac130002",
    "orderValue": 2614.79,
    "interest": 234.56,
    "nominalInterest": 8.64,
    "effectiveInterest": 8.99,
    "merchantSpecificInterest": 8.99,
    "totalValue": 2849.35,
    "decisionOutcome": "POSITIVE",
    "numberOfInstallments": 9,
    "minNumberOfInstallments": 2,
    "maxNumberOfInstallments": 60,
    "installment": 302,
    "lastInstallment": 293.58,
    "firstInstallmentDate": "2023-03-20",
    "lastInstallmentDate": "2023-03-20",
    "amortizationPlanText": "string",
    "urlPreContractualInformation": "string",
    "installmentPlans": [
      {
        "totalValuePlan": 0,
        "interests": {
          "effectiveInterest": 8.99,
          "nominalInterest": 8.64,
          "interest": 234.56
        },
        "paymentPlan": {
          "numberOfInstallments": 9,
          "firstInstallmentDate": "2023-03-20",
          "lastInstallmentDate": "2023-03-20",
          "installment": 302,
          "lastInstallment": 293.58
        }
      }
    ],
    "mtan": {
      "required": true,
      "status": "PENDING",
      "remainingAttempts": 2,
      "successful": true,
      "mobilePhoneNumberInvalid": true,
      "skipMobilePhoneNumberValidation": true
    },
    "bankAccountCheck": {
      "required": false,
      "successful": false
    }
  },
  "transaction": {
    "financingTerm": 6,
    "orderDetails": {
      "orderValue": 2614.79,
      "orderId": "A1ZU560",
      "numberOfProductsInShoppingCart": 1,
      "invoiceAddress": {
        "address": "Beuthener Str. 25",
        "additionalAddressInformation": "3 OG",
        "zip": "90471",
        "city": "Nürnberg",
        "country": "DE",
        "firstName": "Ralf",
        "lastName": "Ratenkauf"
      },
      "shippingAddress": {
        "address": "Beuthener Str. 25",
        "additionalAddressInformation": "3 OG",
        "zip": "90471",
        "city": "Nürnberg",
        "country": "DE",
        "firstName": "Ralf",
        "lastName": "Ratenkauf",
        "packageStation": true
      },
      "shoppingCartInformation": [
        {
          "productName": "Washing Machine",
          "quantity": 1,
          "price": 599.95,
          "manufacturer": "Siemens",
          "productCategory": "Household Appliances",
          "articleNumber": [
            {
              "numberType": "GTIN",
              "number": 1111111
            }
          ]
        }
      ]
    },
    "shopsystem": {
      "shopSystemManufacturer": "Shopware 5.5.10",
      "shopSystemModuleVersion": "1.6.3"
    },
    "customer": {
      "gender": "MR",
      "firstName": "Ralf",
      "lastName": "Ratenkauf",
      "birthDate": "1949-10-17",
      "birthName": "string",
      "birthPlace": "string",
      "title": "PROFDR",
      "contact": {
        "email": "test@test.de",
        "mobilePhoneNumber": "017186397426",
        "phoneNumber": "01771234567",
        "phoneNumbersConfirmed": false
      },
      "bank": {
        "iban": "DE06760320009210030015",
        "bic": "MARKDEFFXXX"
      },
      "employment": {
        "employmentType": "EMPLOYEE",
        "monthlyNetIncome": 3000
      },
      "companyName": ""
    },
    "customerRelationship": {
      "customerStatus": "EXISTING_CUSTOMER",
      "customerSince": "2007-10-10",
      "orderDoneWithLogin": false,
      "numberOfOrders": 3,
      "negativePaymentInformation": "NO_INFORMATION",
      "riskyItemsInShoppingCart": false,
      "logisticsServiceProvider": "Hermes"
    },
    "consent": {
      "sepaMandate": true,
      "advertisement": true,
      "dataProcessing": true,
      "consentToActInOnwnName": true
    },
    "redirectLinks": {
      "urlSuccess": "https://www.google.com/search?q=easycreditSuccess",
      "urlCancellation": "https://www.google.com/search?q=easycreditCanceled",
      "urlDenial": "https://www.google.com/search?q=easycreditDenied",
      "urlAuthorizationCallback": "https://www.google.com/search?=ratenkaufCallback"
    }
  },
  "status": "OPEN"
}

Example Request and Response

Example request
===============

MerchantID=YourMerchantID
PayID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TransID=123456
RefNr=27022017_01
Amount=59995
Currency=EUR
EventToken=GET

Example response
================

mid=YourMerchantID
PayID=b1ecea6e3e8b426fbb614a14f901ac4a
TransID=123456
XID=2e2b31055fbf445d91c6564947d63ffb
refnr=27022017_01
financing=    

Status=AUTHORIZE_REQUEST
Code=0
Description=REQUEST