Step 1: Create the Payment Transaction

Being authenticated, we let the API create the Payment Transaction for the first payment. Our example uses SEPA direct debit. The API endpoint for this is POST https://connect.secucard.com/api/v2/Payment/Secupaydebits:

Request
POST /api/v2/Payment/Secupaydebits HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"demo": true,
"customer": {
"contact": {
"forename": "Grover",
"surname": "Mustermann",
"address": {
"street": "Koelpinstr.",
"street_number": "604",
"postal_code": "09999",
"city": "Musterstadt",
"country": "DE"
},
"email": "SAS187@example.net"
}
},
"subscription": {
"purpose": "Gartengeräte-Club Mgl.-Nr. 220897"
},
"amount": 2495,
"redirect_url": {
"url_success": "https://shop.example.com/checkout/payment/success",
"url_failure": "https://shop.example.com/checkout/payment/failure",
"url_push": "https://shop.example.com/order/payment/update"
}
}

This will create a Payment Transaction about €24.95.

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

The URLs redirect_url/url_success and redirect_url/url_failure are needed to receive the customer back after authentication. redirect_url/url_push to inform your system about status changes. Each of these URLs may have up to 2000 characters.

If everything is fine, the API responds with 200 OK, and the representation of the Payment Transaction:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "payment.secupaydebits",
"id": "xoevuoacybse5221103",
"trans_id": 33922083,
"payment_id": "PCI_47RJ95TKJGCTZ0W2CBKMKE4PP484N3",
"status": "internal_server_status",
"amount": 2495,
"currency": "EUR",
"purpose": "",
"order_id": null,
"transaction_status": 1,
"basket": null,
"accrual": false,
"payment_action": "sale",
"customer": {
"object": "payment.customers",
"id": "PCU_W7B3GGUDH2X3GH3YJ37YQ82Z03JFAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_WVHJQFQ4JNVYNG5B55TYK748ZCHQP8"
},
"contact": {
"forename": "Grover",
"surname": "Mustermann",
"name": "Grover Mustermann",
"address": {
"street": "Koelpinstr.",
"street_number": "604",
"postal_code": "09999",
"city": "Musterstadt",
"country": "DE"
},
"email": "SAS187@example.net"
},
"created": "2021-04-09T19:03:39+02:00"
},
"redirect_url": {
"iframe_url": "https:/\/api-dev6.secupay-ag.de\/payment\/xoevuoacybse5221103",
"url_success": "https:\/\/shop.example.com\/checkout\/payment\/success",
"url_failure": "https:\/\/shop.example.com\/checkout\/payment\/failure",
"url_push": "https:\/\/shop.example.com\/order\/payment\/update"
},
"iframe_url": "https:\/\/api-dev6.secupay-ag.de\/payment\/xoevuoacybse5221103",
"subscription": {
"id": 2402,
"purpose": "Gartenger\u00e4te-Club Mgl.-Nr. 220897"
}
}

Please note the following fields, added by the API:

  • redirect_url/iframe_url is needed to authorise the payment in the next step;

  • id is needed to access the transaction (step 3);

  • customer/id and subscription/id are needed for the subsequent payments.