Sign up

Introduction

The introduction of the SCA guidelines requires you to meet new challenges, but also offers you new opportunities.

One of them is the possibility to process different amounts during the authentication (the 3-D Secure check) and the authorisation (the actual payment) step. By combining it with our tokenisation feature, both steps can happen at different points in time, enabling you to:

  • Delayed/partially split shipments: You want to offer your customers goods/services for a trial period. Alternatively, some goods/services are not available at the time of the order. Finalise/charge the delivery at a later point – but your customers will not have to visit you store and authenticate themselves again!
  • Increment an authorised amount: You want to add a margin to a base amount, as the final amount you want to charge eventually is either equal or higher at the time of the order. Think of booking a hotel room in advance, but you have to charge more on the final invoice because of additional services during the stay. There is no need for a separate transaction to cover this margin: simply authenticate the order for the maximum amount (base amount + margin) and charge anything between the base and the maximum amount later.

By tokenising your customers' card during the first (the authentication) step, you can complete the transaction in the second (the actual payment) for either use case.

Entkoppelung Autorisierung/Authentifizerung is available for the following payment methods: 

Payment Flow

This is a high-level payment flow covering only the mandatory steps. Read the dedicated chapter in our Server-to-server guide or detailed information, code samples and optional steps in the flow. For specific information about the 3-D Secure authentication flow, read the dedicated chapter in our 3-D Secure and SCA guide.
  1. Your customer goes to your check-out page and enters their credit card data to finalise the purchase.
  2. You send the first CreatePayment requests to our platform, including the mandatory 3-D Secure v2 properties. Depending on the use case, differences apply:
    "Delayed/partially split shipments" use case
    "Increment an authorised amount" use case
  3. Our platform sends a response containing a merchantAction object, instructing you to roll out 3-D Secure.
  4. You redirect the customer to her/his issuing bank to the redirectUrl. The cardholders identify themselves.
  5. We submit the actual financial transaction to the acquirer to process it. You deliver the goods/services.
  6. At later point, you send the second CreatePayment request to our platform to finalise the transaction. Depending on the use case, difference apply:
    "Delayed/partially split shipments" use case
    "Increment an authorised amount" use case
  7. Skipping 3-D Secure, we submit the actual financial transaction to the acquirer to process it.

Integration

To use this feature, you need to include additional properties to your request.

Depending on the use case and which of the two steps in the payment flow you want to perform, differences apply:

First request

Second request

Perform first request for delayed/partially split shipments

Add the following properties to a standard CreatePayment request (including mandatory 3-D Secure properties):

{
    "Cardpaymentmethodspecificinput": {
        "Paymentproductid": XXX,
        "Threedsecure": {
            "Authenticationamount": 27530
        },
        "Requiresapproval": true,
        "Skipauthentication": false,
        "Tokenize": true,
        "Unscheduledcardonfilerequestor": "cardholderinitiated",
        "Unscheduledcardonfilesequenceindicator": "first",
        "Card": {
            "Cvv": "451",
            "Cardnumber": "4330264936344675",
            "Expirydate": "1225",
            "Cardholdername": "wile e. Coyote"
        },
        "Isrecurring": false,
        "Transactionchannel": "ecommerce"
    },
    "Order": {
        "Amountofmoney": {
            "Currencycode": "eur",
            "Amount": 0
        },
        "Customer": {
            "Billingaddress": {
                "Countrycode": "nl"
            },
            "device": {
                "acceptHeader": "texthtml,application/xhtml+xml,application/
xml;q=0.9,/;q=0.8",
                "ipAddress": "77.67.63.226",
                "locale": "es",
                "timezoneOffsetUtcMinutes": "-120",
                "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) 
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36",
                "browserData": {
                    "colorDepth": "32",
                    "javaEnabled": "true",
                    "screenHeight": "600",
                    "screenWidth": "400"
                }
            }
        }
    },
    "References": {
        "Merchantorderid": 123456,
        "Merchantreference": "ogpc8xjurfpfitba6orrpkbupogpvd"
    }
}
Properties Remarks

order.amountOfMoney.amount

Set to "0"

cardPaymentMethodSpecificInput
     threeDSecure.authenticationAmount
     tokenize
     unscheduledCardOnFileRequestor
     unscheduledCardOnFileSequenceIndicator

threeDSecure.authenticationAmount: The full amount you want to charge when finalising the order in the second step.

tokenize: Set to "true" to create a token you need in the second step.

unscheduledCardOnFileRequestor: Set to "cardholderinitiated" to indicate that your customers initiate this transaction.

unscheduledCardOnFileSequenceIndicator: Set to "first" to indicate that this is the first step in this transaction.

Find detailed information about this object and its properties in our CreatePaymentAPI.

Perform first request for incrementing an authorised amount

Add the following properties to a standard CreatePayment request (including mandatory 3-D Secure properties):

{
    "Cardpaymentmethodspecificinput": {
        "Paymentproductid": XXX,
        "Threedsecure": {
            "Authenticationamount": 1200
        },
        "Requiresapproval": true,
        "Tokenize": true,
        "Unscheduledcardonfilerequestor": "cardholderinitiated",
        "Unscheduledcardonfilesequenceindicator": "first",
        "Card": {
            "Cvv": "451",
            "Cardnumber": "4330264936344675",
            "Expirydate": "1225",
            "Cardholdername": "wile e. Coyote"
        },
        "Isrecurring": false,
        "Transactionchannel": "ecommerce"
    },
    "Order": {
        "Amountofmoney": {
            "Currencycode": "eur",
            "Amount": 1000
        },
        "Customer": {
            "Billingaddress": {
                "Countrycode": "nl"
            },
            "device": {
                "acceptHeader": "texthtml,application/xhtml+xml,application/
                xml;q=0.9,/;q=0.8",
                "ipAddress": "77.67.63.226",
                "locale": "es",
                "timezoneOffsetUtcMinutes": "-120",
                "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 
                (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36",
                "browserData": {
                    "colorDepth": "32",
                    "javaEnabled": "true",
                    "screenHeight": "600",
                    "screenWidth": "400"
                }
            }
        }
    },
    "References": {
        "Merchantorderid": 123456,
        "Merchantreference": "ogpc8xjurfpfitba6orrpkbupogpvd"
    }
}
Properties Remarks

order.amountOfMoney.amount

The minimum base amount you want to charge when finalising the order in the second step.

cardPaymentMethodSpecificInput
     threeDSecure.authenticationAmount
     tokenize
     unscheduledCardOnFileRequestor
     unscheduledCardOnFileSequenceIndicator

threeDSecure.authenticationAmount: The minimum base amount + the margin.

tokenize: Set to "true" to create a token you need in the second step.

unscheduledCardOnFileRequestor: Set to "cardholderinitiated" to indicate that your customers initiate this transaction.

unscheduledCardOnFileSequenceIndicator: Set to "first" to indicate that this is the first step in this transaction.

Find detailed information about this object and its properties in our CreatePaymentAPI.

Perform second request for delayed/partially split shipments

Add the following properties to a standard CreatePayment request:

{
  "cardPaymentMethodSpecificInput": {
   
"PaymentProductId": XXX,
"ThreeDSecure": {
"RequiresApproval": true,
"SkipAuthentication": true,
"SkipFraudService": true,
},
"token": "f5a1bf4d98b141109d331b2b224212e0",
"unscheduledCardOnFileRequestor": "merchantInitiated",
"unscheduledCardOnFileSequenceIndicator": "subsequent",
 
    "isRecurring": false,
    "paymentProductId": 1,
    "transactionChannel": "ECOMMERCE",
  },
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 2753
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    },
  }
}
Properties Remarks

order.amountOfMoney.amount

The full amount you want to charge (equal to cardPaymentMethodSpecificInput.threeDSecure. authenticationAmount as sent in the first step).

cardPaymentMethodSpecificInput
      token
      unscheduledCardOnFileRequestor
      unscheduledCardOnFileSequenceIndicator

token: Set to the value you received in our response in the first step.

unscheduledCardOnFileRequestor: Set to "merchantinitiated" to indicate that this is the second step in this transaction.

unscheduledCardOnFileSequenceIndicator: Set to "subsequent" to indicate that this is the second step in this transaction.

Find detailed information about this object and its properties in our CreatePaymentAPI.

Perform second request for incrementing an authorised amount

Add the following properties to a standard CreatePayment request:

{
  "cardPaymentMethodSpecificInput": {
   
"PaymentProductId": XXX,
"ThreeDSecure": {
"RequiresApproval": true,
"SkipAuthentication": true,
"SkipFraudService": true,
},
"token": "f5a1bf4d98b141109d331b2b224212e0",
"unscheduledCardOnFileRequestor": "merchantInitiated",
"unscheduledCardOnFileSequenceIndicator": "subsequent",
 
    "isRecurring": false,
    "paymentProductId": 1,
    "transactionChannel": "ECOMMERCE",
  },
  "order": {
    "amountOfMoney": {
      "currencyCode": "EUR",
      "amount": 200
    },
    "customer": {
      "billingAddress": {
        "countryCode": "NL"
      }
    },
  }
}
Properties Remarks

order.amountOfMoney.amount

An amount between the minimum base (equal to order.amountOfMoney.amount as sent in the first step) and the maximum amount (equal to cardPaymentMethodSpecificInput.threeDSecure.authenticationAmount as sent in the first step.


Make sure that the margin does not exceed 20% of the base amount.

cardPaymentMethodSpecificInput
     token
     unscheduledCardOnFileRequestor
     unscheduledCardOnFileSequenceIndicator

token: Set to the value you received in our response in the first step.

unscheduledCardOnFileRequestor: Set to "merchantinitiated" to indicate that this is the second step in this transaction.

unscheduledCardOnFileSequenceIndicator: Set to "subsequent" to indicate that this is the second step in this transaction.

Find detailed information about this object and its properties in our CreatePaymentAPI.

Was this page helpful?

Do you have any comments?

Thank you for your response.