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.

Demo Transactions

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

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.

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:

Recurring Payment

To use a credit card for recurring payments, you must:

• Make the first payment with a Customer Initiated Transaction (CIT). You must also request a Network Token, and record both Payment Container ID (PCT_…) and Payment Transaction ID (PCI_…).
• Make the subsequent payments as Merchant Initiated Transactions (MIT). You must also pass the recorded IDs at different stages of the process.

Subsequent Payments can be captured without customer interaction. The Strong Customer Authentication (SCA) by the Revised Payment Services Directive (PSD2) is not needed.

There are these two cases:

• Scheduled: A series of recurring payments with a fixed amount and frequency, such as a subscription service.
• Unscheduled: A series of irregular transactions using stored card details, such as an automatic account top-up or a rideshare fee. Often this is referred to as Unscheduled Card On File, or for short UCOF.

For the API integration, this makes only a difference for the first payment.

To make recurring payments with direct debit, you will still only need to record the Payment Container ID and pass it back later.

In connection with the migration to the new acquiring system, this means:

• No changes to implementations used simultaneously for SEPA direct debits
• When the Smart Transaction is created for credit card payments, the additional parameters change; like before these are different between the first payment and subsequent payments
• In addition to the Payment Container ID (PCT_…), also the Payment Transaction ID from first payment must be recorded now; it must be passed when creating the Smart Transactions for subsequent payments
• For a more reliable solution than before, status changes of the Payment Container can be subscribed now

The following examples consider only credit card payment. The examples at Recurring Payments show the resulting calls in full detail.

Create the Smart Transaction for the Initial Payment

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

First an example for unscheduled recurring payments:

Now the same example with only the necessary or changed fields for scheduled recurring payments:

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

Details of the related fields:

Details of "mit_instructions":

Details of "container_instructions":

Authorise and Capture the Initial Payment (Custom Checkout)

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

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

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.

Existing implementations need to save the Payment Container ID (container.id). Now you also need the Payment Transaction ID (transactions[0].id). It is passed when creating the Smart Transactions for subsequent payments.

You would also need to manage the life cycle of the Payment Container ID.

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 the Payment Container details would be useless, and standing order or subscription would not work.

Please take these considerations into account:

• The Network Token creation might fail from the beginning
• The Network Token might be invalidated later for a number of reasons (token expiry, card not renewed, etc.)

You must handle this situation.

Imagine this authorisation request:

Or, when returned to the success URL by Smart Checkout, you would call something like GET /api/v2/Smart/Transactions/STX_3Z8EUQX0A2PBHRJV9FRY7P56GEDZAK.

In both cases the API would respond with 200 OK and an updated Smart Transaction like this:

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

In this case don't save the Payment Container details, and manage the situation.

Create the Smart Transaction for Subsequent Payments

When you create the Smart Transaction for later payments:

• You can remove the flag "merchant_initiated" from "payment_context" (s. Recurring Payments (Legacy))
• You must add different "mit_instructions" to "payment_context"; it must contain the flag "type": "mit" and pass the Payment Transaction ID (PCI_…) as "cit_reference"

The changed parts would look like here:

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

Please note the following different elements inside "mit_instructions":

type

cit_reference

The other object "container_instructions" is no longer needed.

If everything is fine, the API responds with 200 OK and the created Smart Transaction. There is nothing special in the responded Smart Transaction.

Authorise and Capture the Subsequent Payment

With the call to authorise the payment, you would pass the Payment Container ID only instead of all the details:

This is not different than before.

If everything is fine, the API responds again with 200 OK and the updated Smart Transaction:

The payment is authorised or already captured (if accompanied by the auto_capture flag). Please check the payment status.

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