Ingenico Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

1. Introduction

The introduction of the PSD2 guideline 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 (blocking the funds on your customers’ credit card) step. This decoupled amount feature allows you to

  • Delay / partially split shipments
  • Increment an authorised amount

When your customer authenticates an amount higher than the authorisation, you can capture the additional amount(s) later - without renewing the authentication for this additional amount. In contrast to a classic recurring payment you are not liable for these additional amounts, but your customers are - provided you do not exceed the original authentication amount.
To capture these additional amount(s) you still have to tokenise the initial transaction with the full amount to be authenticated.

Have a look at typical use cases and how they implement this new feature.

Decoupled amount is available for credit card payment methods

and integration mode Server-to-server

2. Understand use cases

The need to process different amounts during the authentication/authorisation might happen in situations like these:

  1. Delayed/Partially split shipment: 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!

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

Learn now how to implement either scenario in your customers’ payment journey.

3. Initiate order

To use this feature, you need to process your transactions in two steps:

  1. Send a standard CreatePayment with 3-D Secure at the time of the initial order
  2. Finalise the order via a standard CaptureRequest

This chapter covers the first step. Refer to the dedicated chapter for the second step

Once you want to initiate an order, send the CreatePayment request with the following properties: 

Properties Remarks

order.amountOfMoney.amount

cardPaymentMethodSpecificInput

    • threeDSecure.AuthenticationAmount
    • tokenize
    • unscheduledCardOnFileRequestor
    • unscheduledCardOnFileSequenceIndicator

    Depending on use case, send the following values:

    • 1. Delayed/Partially split shipment
      • order.amountOfMoney.amount: Set to "0"
      • threeDSecure.AuthenticationAmount: The full amount you want to charge when finalising the order
      • tokenize: Set to "true" to create a token for 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


    A typical request looks like this:

    
    {
       "Cardpaymentmethodspecificinput":{
          "Paymentproductid":1,
          "Threedsecure":{
             "Authenticationamount":27530
          },
          "Requiresapproval":true,
          "Skipauthentication":true,
          "Skipfraudservice":true,
          "Tokenize":true,
          "Unscheduledcardonfilerequestor":"cardholderinitiated",
          "Unscheduledcardonfilesequenceindicator":"first",
          "Card":{
             "Cvv":"451",
             "Cardnumber":"4111111111111111",
             "Expirydate":"1225",
             "Cardholdername":"wile e. Coyote"
          },
          "Isrecurring":false,
          "Paymentproductid":1,
          "Transactionchannel":"ecommerce",
          "Threedsecure":{
             "Externalcardholderauthenticationdata":{
                "Cavv":"aaabbeg0vhi0vniqejrwaaaaaaa=",
                "Directoryservertransactionid":"f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
                "Eci":"05",
                "Threedsecureversion":"2.1.0"
             }
          }
       },
       "Order":{
          "Amountofmoney":{
             "Currencycode":"eur",
             "Amount":0
          },
          "Customer":{
             "Billingaddress":{
                "Countrycode":"nl"
             }
          },
          "References":{
             "Merchantorderid":123456,
             "Merchantreference":"ogpc8xjurfpfitba6orrpkbupogpvd"
          }
       }
    }
    
    • 2. Increment an authorised amount
      • order.amountOfMoney.amount: The minimum base amount you want to charge when finalising the order
      • threeDSecure.AuthenticationAmount: The minimum base amount + the margin
      • tokenize: Set to "true" to create a token for 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

      A typical request looks like this:

      
      {
         "cardPaymentMethodSpecificInput":{
            "PaymentProductId":1,
            "ThreeDSecure":{
               "AuthenticationAmount":1200
            },
            "RequiresApproval":true,
            "SkipAuthentication":true,
            "SkipFraudService":true,
            "tokenize":true,
            "unscheduledCardOnFileRequestor":"cardholderinitiated",
            "unscheduledCardOnFileSequenceIndicator":"first",
            "card":{
               "cvv":"451",
               "cardNumber":"4111111111111111",
               "expiryDate":"1225",
               "cardholderName":"Wile E. Coyote"
            },
            "isRecurring":false,
            "paymentProductId":1,
            "transactionChannel":"ECOMMERCE",
            "threeDSecure":{
               "externalCardholderAuthenticationData":{
                  "cavv":"AAABBEg0VhI0VniQEjRWAAAAAAA=",
                  "directoryServerTransactionId":"f25084f0-5b16-4c0a-ae5d-b24808a95e4b",
                  "eci":"05",
                  "threeDSecureVersion":"2.1.0"
               }
            }
         },
         "order":{
            "amountOfMoney":{
               "currencyCode":"EUR",
               "amount":1000
            },
            "customer":{
               "billingAddress":{
                  "countryCode":"NL"
               }
            },
            "references":{
               "merchantOrderId":123456,
               "merchantReference":"oGPc8xJURfpFitBa6ORrpkBuPoGpvD"
            }
         }
      }
      

      4. Finalise order

      Once you want to finalise the order, send a standard CapturePayment request with these properties:

      Properties Remarks

      order.amountOfMoney.amount

      cardPaymentMethodSpecificInput

        • threeDSecure.AuthenticationAmount
        • token
        • unscheduledCardOnFileRequestor
        • unscheduledCardOnFileSequenceIndicator

        Depending on use case, send the following values:

        • 1. Delayed/Partially split shipment
          • order.amountOfMoney.amount: the full amount you want to charge (equal to cardPaymentMethodSpecificInput.threeDSecure.AuthenticationAmount as sent in step 1)
          • token: Set to the value you received during step 1
          • unscheduledCardOnFileRequestor: Set to "merchantinitiated" to indicate that this is the second step in this transaction
          • unscheduledCardOnFileSequenceIndicator: Set to "subsequent" o indicate that this is the second step in this transaction


        A typical request looks like this:

        
        {
          "cardPaymentMethodSpecificInput": {
           
        "PaymentProductId": 1,
        "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"
              }
            },
          }
        }
        
        • 2. Increment an authorised amount
          • order.amountOfMoney.amount: an amount between the minimum base (equal to order.amountOfMoney.amount as sent in step 1) and the maximum amount (equal to cardPaymentMethodSpecificInput.threeDSecure.AuthenticationAmount as sent in step 1)
          • token: Set to the value you received during step 1
          • unscheduledCardOnFileRequestor: Set to "merchantinitiated" to indicate that this is the second step in this transaction
          • unscheduledCardOnFileSequenceIndicator: Set to "subsequent" o indicate that this is the second step in this transaction

          A typical request looks like this:

          
          {
            "cardPaymentMethodSpecificInput": {
             
          "PaymentProductId": 1,
          "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"
                }
              },
            }
          }
          

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