Prerequisites

As a prerequisite, you should understand:

• secuconnect API Fundamentals
• Create the Smart Transaction
• Pay with Credit Card
• Pay with SEPA Direct Debit

You should also understand if you may have searched for Subscriptions.

Abstract

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 omitted.

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

The following examples are for the more compley case of repeated credit card payments. For direct debit please disregard everything special except storing and using the Payment Conatiner ID.

Make the Initial Payment

Create the Smart Transaction

When you make the first payment, you must add the needed "mit_instructions" and  "container_instructions" to the "payment_context" when you create the Smart Transaction. The first payment is made with customer interaction, and thus called and regulated a Customer-Initiated Transaction (CIT).

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.

First an example for unscheduled recurring payments:

Please note the elements "mit_instructions" and "container_instructions" inside "payment_context" at line 66 .. 75.

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 Payment

 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.

Please note the fields with the Payment Container ID (container.id) and the Payment Transaction ID (transactions[0].id). (If there is more than one transaction, please use first one.)

In case of credit card payment, you need to save both IDs in relation to your customer account. You would also need to manage the life cycle of the Payment Container ID.

In case of direct debit, you only need to save 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:

In this case the API might respond with 200 OK and the 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.

Make the Subsequent Payments

Create the Smart Transaction

When you make later payments, you must also add different "mit_instructions" to the "payment_context" when you create the Smart Transaction:

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

Please note the following different elements inside "mit_instructions" at line 66 .. 70:

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 Payment

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

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

See Also

• API Reference: Create Smart Trasaction
• API Reference: Smart Transaction, Authorize Payment
• Status Flow of a Smart Transaction
• Subscriptions