Recurring Payments

Prerequisites

As a prerequisite, you should understand:

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

Abstract

Your contract needs to be activated for recurring payments. Otherwise the subsequent payment with MIT cannot be authorised.

To use a credit card or SEPA direct debit for recurring payments, you must:

  • Record the Payment Container ID;

  • Reuse this very ID for subsequent payments;

  • Mark the subsequent payment as Merchant Initiated Transaction (MIT).

The MIT flag currently only affects credit card payment. Subsequent Payments can be captured without customer interaction. The Strong Customer Authentication (SCA) by the Revised Payment Services Directive (PSD2) is omitted.

Make the First Payment

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

Authorisation Request
POST /api/v2/Smart/Transactions/STX_3Z8EUQX0A2PBHRJV9FRY7P56GEDZAK/prepare/creditcard HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"container": {
"type": "credit_card",
"private": {
"owner": "Max Mustermann",
"pan": "411111XXXXXX1111",
"expiration_date": "2026-01-01T00:00:00+00:00",
"issuer": "VISA",
"transact_container": "o40dsmkQrRzPaVLP6iDEaRI+rNsBokbU6z1pRtMMzFjoHxcrht...",
"transact_skey_pubkey": "oyLkX4oddKGWywQCwUYNr8wq9s3tuwq6FYL3fzsBSYaT5MRg...",
"transact_skey_keyname": "weberpublic.pem",
"transact_hash": "1f3053bc8efcd43d74997a2368738bac13bce651c3a6bae6ac90692..."
}
},
"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"
},
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_W026W643US3TWCGZA0AVZ248W8TSMW",
"trans_id": 123456789,
"transaction_hash": "abcdefghijkl12345678"
}
],
"created": "2023-12-07T15:55:58+01:00",
"updated": "2023-12-07T15:56:16+01:00",
"status": "created",
// ...
"payment_method": "creditcard",
"trans_id": 123456789,
"iframe_url": "https://securepay.epayworldwide.com/securepay2/pay.php?...",
// ...
}

For direct debit it would look similar but there is no 3-D Secure, and 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.

Another important detail here is the Payment Container ID (container.id). Your application must record and use this ID for the subsequent payments. It must only be used for this very person.

Payment Containers are used for both kinds of payments, credit card and SEPA direct debit. They can be created implicitly like in the above example, or with a previous call to POST /api/v2/Payment/Containers.

You must save the Payment Container ID only, but not the details your have used inside container.private when creating it.

This part of the process may also be hidden from you are for using Smart Checkout instead of a custom checkout. You must then read the Smart Transaction with GET /api/v2/Smart/Transactions/{id} to obtain the Payment Container ID after the payment was authorised.

Make Subsequent Payments

The subsequent orders are merchant-initiated. Thus the Smart Transaction are marked with payment_context.merchant_initiated now:

Creation Request for Smart Transaction
POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
// ...
"basket_info": {
"sum": 3685
},
"payment_context": {
"auto_capture": true,
"merchant_initiated": true
}
}

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

Authorisation Request
POST /api/v2/Smart/Transactions/STX_HUXEQ5X302PBHTEYWP66F9AX0N44A4/prepare/creditcard HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"container": {
"id": "PCT_3JU4VGYZF2XY8EJHH9FQ7WGYNZGJA4",
},
"callback_urls": {
"success_url": "https://shop.example.com/payment/success?nonce=ciix8j3qbqffg8dcdc7b",
"failure_url": "https://shop.example.com/payment/failure?nonce=ciix8j3qbqffg8dcdc7b"
}
}

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

Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
"object": "smart.transactions",
"id": "STX_HUXEQ5X302PBHTEYWP66F9AX0N44A4",
// ...
"container": {
"object": "payment.containers",
"id": "PCT_3JU4VGYZF2XY8EJHH9FQ7WGYNZGJA4",
"type": "credit_card"
},
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_54UPYB6SGWC7PQCBXHX99248W8UWMJ",
"trans_id": 123456791,
"transaction_hash": "bcdefghijklm223456789"
}
],
"created": "2023-12-07T16:58:34+01:00",
"updated": "2023-12-07T17:00:40+01:00",
"status": "ok",
// ...
"payment_method": "creditcard",
"trans_id": 123456791,
// ...
}

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