Reuse a Payment Instrument

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.

Obtain the Payment Container

When the bank account or credit card is used for the first time, you pass the account or card details to the Smart Transaction endpoints, when you authorise the payment. (S. Pay with Credit Card; Pay with SEPA Direct Debit). During the authorisation process, it creates a Payment Container to manage the payment instrument.

This is our example request for the authorisation of a SEPA direct debit payment:

Request
POST /api/v2/Smart/Transactions/STX_xxx/prepare/debit HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "container": {
        "merchant_id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
        "type": "bank_account",
        "private": {
            "owner": "Max Mustermann",
            "iban": "DE35500105175418493188"
        }
    }
}

The new 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_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"container": {
"object": "payment.containers",
"id": "PCT_W44PJNRAV2NPM7CG6Z0YYE877CJBAZ"
},
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7"
}
],
"created": "2020-03-27T10:55:23+01:00",
"updated": "2020-03-27T10:56:39+01:00",
"status": "ok",
// ...
}

The field container/id contains ID of the new Payment Container ("PCT_...). It must be saved in relation to the customer account.

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

Use the Existing Payment Container

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.

This is again for the authorisation of a SEPA direct debit payment:

Request
POST /api/v2/Smart/Transactions/STX_xxx/prepare/debit HTTP/1.1
Host: connect-testing.secupay-ag.de
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"
},
"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.