Pay with easyCredit

Prerequisites

As a prerequisite, you should understand:

Process Details

Ratenkauf by easyCredit has the following restrictions:

  • It is only offered to consumers (B2C).

  • It does not work with mixed baskets (marketplaces).

  • It supports only EUR as currency.

  • The order total must be between €200 and €10,000.

  • The ordered articles must be passed (article name, unit price, and quantity).

  • Mixed baskets (marketplaces) are not possible.

  • Stakeholder payments (platforms and marketplaces) are not possible.

  • The customer name and address must be passed.

The process includes an external authorisation. After the Smart Transaction is created, these steps are needed:

  1. Your server asks the secuconnect API to authorise for Ratenkauf by easyCredit.

  2. You direct the payer to an URL provided in the Smart Transaction. It leads to the easyCredit page to arrange the details of the instalment payment, and authorise it.

  3. After this the payer is returned to the success or failure URL your server has provided before.

  4. After successful authorisation, your server can ask the secuconnect API to capture the payment.

When the Smart Transaction was set up for auto-capture, you can save the last step.

There are also push notifications. These should be used to control the status of your order. This works even if the payer did not see the success or failure URL for some reason.

Step 1: Create a Smart Transaction

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Smart/Transactions.

Request
POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"is_demo": true,
"intent": "sale",
"contract": {
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ"
},
"merchantRef": "K/01234",
  "transactionRef": "B/001234567",
   "basket": {
"products": [
{
"id": 1,
"articleNumber": 30037,
"ean": "4999012345678",
"desc": "Höhenverstellbarer Schreibtisch",
"quantity": 1,
"priceOne": 49800,
"tax": 19
},
{
"id": 2,
"item_type": "coupon",
"desc": "Coupon 20 €",
"quantity": 1,
"priceOne": 2000,
"tax": 19
},
{
"id": 3,
"item_type": "shipping",
"desc": "Versand Spedition",
"quantity": 1,
"priceOne": 3500,
"tax": 19
}
]
},
"basket_info": {
"sum": 51300,
"currency": "EUR"
},
  "payment_context": {
"auto_capture": false
}
}

This creates a Smart Transaction to pay a hotel reservation. The customer is preset with the previously created object, and the amount is €119.70.

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

If everything is fine, the API responds with 200 OK:

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"merchant": {
"object": "general.merchants",
"id": "MRC_AZS7P6FTNTC6NK0QWFDBREW94ZY2O7",
"companyname": "Smart Checkout Testmerchant 8"
},
"provider_contract": {
"object": "general.contracts",
"id": "GCR_QP49BFHYYKVAQBFWGE5VBBUUJEQ2P8"
},
"contract": {
"object": "general.contracts",
"id": "GCR_CNEUVF64H5S8R58R7PB4Q6CNJESBPJ"
},
"customer": {
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"contact": {
"forename": "Max",
"surname": "Mustermann",
"name": "Max Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "mmustermann@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
},
"transactions": [],
"created": "2020-03-27T10:55:23+01:00",
"status": "created",
"merchantRef": "K/01234",
  "transactionRef": "B/001234567",
  "intent": "sale",
"basket": {
"products": [
{
"id": 1,
"articleNumber": 30037,
"ean": "4999012345678",
"desc": "Höhenverstellbarer Schreibtisch",
"quantity": 1,
"priceOne": 49800,
"tax": 19
},
{
"id": 2,
"item_type": "coupon",
"desc": "Coupon 20 €",
"quantity": 1,
"priceOne": 2000,
"tax": 19
},
{
"id": 3,
"item_type": "shipping",
"desc": "Versand Spedition",
"quantity": 1,
"priceOne": 3500,
"tax": 19
}
]
},
"basket_info": {
"sum": 51300,
"currency": "EUR"
},
  "is_demo": true,
// ...
"payment_context": {
"auto_capture": false,
"payment_methods": null,
"merchant_initiated": false,
"accrual": false,
"creditcard_schemes": [
"mastercard",
"visa",
"american express"
]
},
// ...
}

As you see, the system behind the secuconnect API added many things. Most interesting for is the ID of the Smart Transaction, here STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2. You need it for the subsequent API calls.

Step 2: Authorise the Payment

The endpoint to authorise for Ratenkauf by easyCredit payment is POST /api/v2/Smart/Transactions/{id}/prepare/easycredit .

Request
POST /api/v2/Smart/Transactions/STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ/prepare/easycredit HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"callback_urls": {
"success_url": "https://shop.example.org/SUCCESS",
"failure_url": "https://shop.example.org/FAILURE"
}
}

These are the parameters:

Parameter

Type

Meaning

callback_urls

object

Callback URLs for the external authorisation process between the buyer and easyCredit / TeamBank.

customer

object

Optional customer. Needed if not already set.

The callback_urls in detail:

Parameter

Type

Meaning

success_url

string

URL the buyer is directed to after successful easyCredit negotiation and authorisation.

failure_url

string

URL the buyer is directed to after the negotiation or authorisation failed.

If everything is fine, the API responds with 200 OK and a respresentation of the Smart Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ",
// ...
"updated": "2022-10-14T10:14:41+02:00",
"status": "created",
// ...
"payment_method": "easycredit",
"trans_id": 55679607,
"iframe_url": "https://ratenkauf.easycredit.de/app/payment/c2917535.1017161431dvgiYaMiJMBfsPNYKZdKptSk/finanzierungsvorgaben",
// ...
}

These fields are noteworthy:

Parameter

Type

Meaning

status

string

Status of the Smart Transaction, still "created" so far.

payment_method

string

Payment method, always "easycredit" in this case.

trans_id

int

ID of the Payment Transaction, and also the order ID in the easyCredit transaction.

iframe_url

string

URL for the external credit authorisation between the buyer and easyCredit.

You need to direct the buyer to iframe_url now, in order to make the payment.

Despite its name, you must not open the iframe_url within an Iframe ( <iframe> ):

  • It is forbidden to conduct a Sofort payment within an Iframe. (s. link to Sofort Integration Center)

  • Some popular browsers have very strict same-origin restrictions for third party content, so that Cookie technology will not work inside Iframes. Most external authorisation flows cannot be completed.

After this you will receive them back at one of the URLs you have passed with the request.

If the payment was authorised, the success_url is called and credit details are added to the Smart Transaction, that has changed to status approved, or ok (with auto-capture) now. You can obtain the details by reading the Smart Transaction:

Request
GET /api/v2/Smart/Transactions/STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with 200 OK and a respresentation of the Smart Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ",
// ...
"updated": "2022-10-14T10:14:41+02:00",
"status": "approved",
// ...
   "payment_instructions": {
"interest": 2886,
"total_value": 60286,
"number_of_installments": 10,
"installment": 6100,
"last_installment": 5386
},
   // ...
}

These fields are noteworthy:

Parameter

Type

Meaning

status

string

Status of the Smart Transaction, either "approved", or already "ok" (with auto-capture).

payment_instructions

object

Detailed conditions of the negotiated credit.

The payment_instructions in detail:

Parameter

Type

Meaning

interest

int

Total interest (smallest currency unit).

total_value

int

Total value including the interest (smallest currency unit).

number_of_installments

int

Number of instalments to pay.

installment

int

Amount to pay for all instalments except the last one (smallest currency unit).

last_installment

int

Amount to pay for the last instalment (smallest currency unit).

For the above this means, the buyer agreed a credit contract payable in 10 instalments of €61.00, but the last one is €53.86. This are €602.86 including an interest of €28.86. At easyCredit the buyer should have seen this summary:

images/download/thumbnails/156211566/image2022-10-20_13-46-28.png

(The number of instalments is displayed somewhat above.)


Now you can display the details, and ask the buyer for confirmation. If auto-capture is active, and the Smart Transaction has status ok, you can already confirm the order.

Step 3: Capture the Payment

The endpoint to capture the payment is POST /api/v2/Smart/Transactions/{id}/start. For Ratenkauf by easyCredit this means to mark the conclusion of contract.

Request
POST /api/v2/Smart/Transactions/STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ/start HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json

If everything is fine, the API responds with 200 OK and a respresentation of the Smart Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ",
// ...
"updated": "2022-10-14T10:15:36+02:00",
"status": "ok",
// ...
"payment_instructions": {
"interest": 2886,
"total_value": 60286,
"number_of_installments": 10,
"installment": 6100,
"last_installment": 5386
},
// ...
}

If everything is good, the status of the Smart Transaction switches to "ok".