Background

In November 2024, secupay AG obtained principal membership for Visa and Mastercard for credit card acquiring services. This enables us to offer our customers services that are better tailored to their needs. In order to benefit from the changes, the service must be converted to the new acquiring model and, depending on the scope of functions, the technical connection must also be adapted. We will involve you in this process in good time and to the extent necessary.

The following is only relevant for credit card payments.

Demo Transactions

Beginning with secupay Acquiring, demo mode transactions are no longer available at the live system.

Currently you can create both, demo and live transactions, on both environments, sandbox and live. In future, there will be no demo transaction mode, but only sandbox and live environments.

Dynamic Descriptors

The following would have no effect when applied to subscription payments.

Dynamic descriptors can be used to pass a DBA (“doing business as”) name and local address instead of the legal name and registration address. A DBA can be a trademark or store name that is better understandable by the card holders when checking their card or bank statements, and can lead to fewer chargebacks. This works only with credit card payment together with the new acquiring by secupay.

Please note that you must only use DBA names and addresses to which you have a legitimate claim.

The dynamic descriptor can be passed when creating the Smart Transaction that is used to control the checkout process. It needs to be inserted in the payment context of the Smart Transaction details:

Excerpt from Request Body
POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secuconnect.com
...
 
{
// ...
"payment_context": {
// ...
"dynamic_descriptor": {
"merchant_name": "ACME Buero-Paradies",
"merchant_city": "Bielefeld"
}
}
}

One-Click Payment

These parts need to be revised:

  • Your system must request a network token when doing the first payment
  • Your system should save the Payment Container only if desirable
  • Your system should remove the payment method when a push notification signalises the Network Token became invalid.

Create the Smart Transaction for the Initial Payment

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
 
{
// ...
"payment_context":
{
// ...
"container_instructions":
{
"request_token": true,
"notification_url": "https://shop.example.com/user/payment-methods/update-token?tref=hm5a1j37nmz68o49zgiy56ntr85uftph"
}
    }
}

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

Handle Failed Token Request upon Initial Payment

When you authorise (and perhaps auto-capture) the first payment, the payment may succeed whilst the Network Token request would fail. In this case you would not save the Payment Container details for one-click. In effect your customer must enter the card data again next time.

Imagine this authorisation request:

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"
}
}

In this case the API might respond with 200 OK and the updated Smart Transaction like this:

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": "failed",
// ...
}
},
"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...",
// ...
}

Please note container.token_status.status being "failed" (line 14).

In this case don't save the Payment Container details. You might show the user an informational message, and you might want to leave a log entry.

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

Archiving the Network Token

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

All details are found here: Archiving the Network Token