Integration Guide

This guide is for current implementations. For legacy implementations see Reuse a Payment Instrument. There is also a migration guide at Migration to Secupay Acquiring.

This page explains how to reuse a bank account or credit card to implement a one-click payment solution. This will offer your buyer an express checkout experience.

Please ensure that the customer agrees before you save the payment instrument in order to comply with the regulations.

Requirements

Before you read this, you should understand:

How It Works

Direct debit and credit card payments work with Payment Containers that store the payment instrument (bank account, credit card). These Payment Containers can be used as handle to the payment instrument. You can use the Payment Container ID to make a payment.

Make the Initial Payment

Create the Smart Transaction

When you make the first payment, you must add the needed and "container_instructions" to the "payment_context" when you create the Smart Transaction:

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "contract": {
        "id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
    },
    "customer": {
        "contact": {
            "company_name": "Musterfirma GmbH"
            "forename": "Max",
            "surname": "Mustermann",
            "address": {
                "street": "Musterallee",
                "street_number": "23-25",
                "postal_code": "09005",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "m.muster@example.net",
            "mobile": "+491775555555",
            "phone": "+495555555555"
        }
    },
    "transactionRef": "Bestellung am 25.02.2026 bei ACME Buero-Paradies auf Example.com",
    "merchantRef": "20000345",
    "basket": {
        "products": [
            {
                "id": 1,
                "articleNumber": 30037,
                "ean": "4999012345678",
                "desc": "Druckerpapier Eco A4 80g",
                "quantity": 10,
                "priceOne": 7900,
                "tax": 19
            },
            {
                "id": 2,
                "item_type": "shipping",
                "desc": "Versand Spedition",
                "quantity": 1,
                "priceOne": 500,
                "tax": 19
            }
        ]
    },
    "basket_info":
    {
        "sum": 8400,
        "currency": "EUR"
    },
    "payment_context":
    {
        "auto_capture": true,
        "dynamic_descriptor":
        {
            "merchant_name": "ACME Buero-Paradies",
            "merchant_city": "Bielefeld"
        },
        "container_instructions":
        {
            "request_token": true,
            "notification_url": "https://shop.example.com/network-token/update"
        }
    }
}

Please note the element "container_instructions" inside "payment_context" at line 66 .. 70.

If everything is fine, the API responds with 200 OK and the created Smart Transaction.

Details of the related fields:

Field	Type	Meaning
`container_instructions`	object	Instructions considered when creating the Payment Container in the next step.

Details of "container_instructions":

Field	Type	Meaning
`request_token`	boolean	Requests to save the credit card reference securely on the servers of a credit card network like VISA or MasterCard (“Network Token“)
`notification_url`	string	Callback URL on your server for status updates for the Payment Container related to the Network Token

Authorise and Capture the Payment

Imagine you have authorised the Smart Transaction for the first order by using this call, for example:

Request

POST /api/v2/Smart/Transactions/STX_3Z8EUQX0A2PBHRJV9FRY7P56GEDZAK/prepare/creditcard HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "container": {
        "type": "credit_card",
        "private": {
            "owner": "Max Mustermann",
            "pan": "463544XXXXXX2298",
            "expiration_date": "2034-02-01T00:00:00+00:00",
            "issuer": "VISA",
            "transact_container": "MzkzOTQ0MGI1YTBmMDg2ZDkxYTEwNzIyZTMwNTgwNGZjYTU3...",
            "transact_skey_pubkey": "8ebccbb725d89d6286f227e672f24155e8b50b9688e7a45b...",
            "transact_skey_keyname": "spp_2025.pem",
            "transact_hash": "671439c1a91466df0249d8ab1b3595b682def08b1aea05a2d66e6adcf3d37a98"
        }
    },
    "callback_urls": {
        "success_url": "https://shop.example.com/payment/success?nonce=ciix8j3qbqffg8dcdc7b",
        "failure_url": "https://shop.example.com/payment/failure?nonce=ciix8j3qbqffg8dcdc7b"
    }
}

If everything was fine, the API would have responded with something with 200 OK and the updated Smart Transaction:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "object": "smart.transactions",
    "id": "STX_3Z8EUQX0A2PBHRJV9FRY7P56GEDZAK",
    // ...
    "container": {
        "object": "payment.containers",
        "id": "PCT_3JU4VGYZF2XY8EJHH9FQ7WGYNZGJA4",
        "type": "credit_card",
        // ...
        "token_status": {
            "status": "requested",
            // ...
        }
    },
    "transactions": [
        {
            "object": "payment.transactions",
            "id": "PCI_W026W643US3TWCGZA0AVZ248W8TSMW",
            "trans_id": 123456789,
            "transaction_hash": "abcdefghijkl12345678"
        }
    ],
    "created": "2025-02-25T15:55:58+01:00",
    "updated": "2025-02-25T15:56:16+01:00",
    "status": "created",
    // ...
    "payment_method": "creditcard",
    "trans_id": 123456789,
    "iframe_url": "https://connect-testing.secuconnect.com/spp/challenge/?token=5ab8b08...",
    // ...
}

For direct debit it would look similar but there is no 3-D Secure, and thus no iframe_url. Credit card payments require a 3-D Secure check if not exempted. So the iframe_url may be present or not. If auto_capture is set, the payment would be captured immediately after successful authorisation.

Please note the fields with the Payment Container ID (container.id). You need to save the Payment Container ID in relation to your customer account. You would also need to manage the life cycle of the Payment Container ID.

A saved payment instrument may be offered this way:

"IBAN ending with 3389"
"MasterCard ending with 5454 (expires 12/25)"

Thus you have to save these details:

the Payment Container ID ("PCT_...);
the last 4 characters of the IBAN ("3389");
the last 4 characters of the credit card number ("5454");
the credit card brand name ("MasterCard");
the card expiry date (25-M12).

The credit card iframe ensures that you will not see the full credit card number, nor the security code.

You should only save the Payment Container if the authorisation was successful, this is on status "accepted" or "ok" (line 27), and if the token status is not "failed" (line 12).

Make the Subsequent Payments

There is nothing special when creating the Smart Transaction for a later payment when making a one-click payment.

When the bank account or credit card is reused with a subsequent payment, you pass the Payment Container ID to the Smart Transaction endpoints, when you authorise the payment:

Request

POST /api/v2/Smart/Transactions/STX_MUCAB363K8DIZ97UZLQZRWWDT06XYL/prepare/creditcard HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "container": {
        "id": "PCT_W44PJNRAV2NPM7CG6Z0YYE877CJBAZ"
    }
}

The Payment Container is contained in the Smart Transaction, which is returned (assuming 200 OK):

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
  
{
    "object": "smart.transactions",
    "id": "STX_MUCAB363K8DIZ97UZLQZRWWDT06XYL",
    // ...
    "container": {
        "object": "payment.containers",
        "id": "PCT_W44PJNRAV2NPM7CG6Z0YYE877CJBAZ",
         // ...
        "token_status": {
            "status": "active",
            // ...
        }
    },
    "transactions": [
        {
            "object": "payment.transactions",
            "id": "PCI_7OWJ3NESIARHHUKG1RNJ76WTIFHHOQ"
        }
    ],
    "created": "2020-03-27T11:03:56+01:00",
    "updated": "2020-03-27T11:04:34+01:00",
    "status": "ok",
    // ...
}

The response is the same, except new transaction IDs.

Network Token Lifecycle

Manage Status Changes of the Network Token

Beginning with our new acquiring solution, we will also start to send push notifications for Network Token status changes. This can be used to activate or to remove the Payment Container. The push notification is sent for the Payment Container holding the Network Token.

All details are found here: Network Token Status Notifications

Archive the Network Token

Beginning with our new acquiring solution, you can request the deletion or archiving the network token.

The endpoint for archiving the network token is PUT /api/v2/Payment/Containers/{id}/archive:

Request

PUT /api/v2/Smart/Transactions/PCT_3JU4VGYZF2XY8EJHH9FQ7WGYNZGJA4/archive HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with HTTP status 200 OK, and confirms the successful deletion request:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "result": true
}

This will cause the following token status flow and actions:

Status	Meaning
`archivePending`	Token was invalidated, and deletion request is forwarded to the card network.
`archived`	Deletion request was executed.

You will also receive push notificatiosn, s. Network Token Status Notifications