Pay with Sofort

Prerequisites

As a prerequisite, you should understand:

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: Make the Payment

A Sofort payment basically works the same way like giropay and eps. It is processed like this:

  1. Your server asks the secuconnect API to authorise and capture the Sofort payment.

  2. You direct the payer to an URL provided in the Smart Transaction.

  3. The payer is returned to a success or failure URL, your server has provided before.

To this your server needs to respond accordingly. There is also a push notification for the case the payer is not returned.

The transaction is always captured with the authorisation, even if "auto_capture" is set to false. Payment Initiation Services (PIS) such as Sofort, giropay or eps do not have a two-step process by nature.

Always test Sofort payments with 88888888 (eight times 8) as IBAN or BIC. Otherwise, the payment will be executed even if the transaction was created in demo mode or on our test servers. Please make sure this is considered when working with demo transactions or on test servers.

The endpoint to authorise and capture a Sofort payment is POST /api/v2/Smart/Transactions/{id}/prepare/sofort :

Request
POST /api/v2/Smart/Transactions/STX_WBVJKK82Y2X3MKHN3NZCPAAF6C38AJ/prepare/sofort 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/sofort/SUCCESS",
"failure_url": "https://shop.example.org/sofort/FAILURE"
}
}

The two URLs are passed to Sofort. We will direct your customer to one of these URLs:

  • after the Sofort payment was accepted (success_url) or

  • after the Sofort payment was aborted or failed (failure_url).

If everthing 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": "2021-04-14T10:14:41+02:00",
"status": "created",
// ...
"payment_method": "sofort",
"trans_id": 34029564,
"iframe_url": "https:\/\/www.sofort.com\/payment\/go\/4e1f08c1b85dc4ea442cec44954fb14dd59dfe6d",
// ...
}

You need to direct the customer 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 him back at one of the URLs you have passed with the request. If the payment was accepted, and the success_url is called, the status of the Smart Transaction changes to pending. See the sections about the status flow, and how to check the status in order to understand more.