Adjust Authorisation

Adjust the payment amount before it's been captured to implement tipping and other use cases.


The Adjust Authorisation modification allows you to increase or decrease the authorised amount after the initial authorisation has taken place. This functionality enables tipping, improving the chances your authorisation will be valid, charging the shopper when they have already left the merchant premises, etc.

The Adjust Authorisation modification is currently available only for Amercian Express, Discover, Visa, and Mastercard.

In order to change the authorised payment (that has not been captured yet), send a modification request to the /adjustAuthorisation endpoint. The synchronous response to this request contains a confirmation that a modification was received, and the asynchronous notification contains the result of a modification.

The advantages of using an adjusted authorisation instead of a new authorisation:

  • The shopper will see one single charge on their bank statement (depending on the issuer implementation).
  • Funds and liability shift are maintained while the /adjustAuthorisation is valid.

If you need to modify the payment amount more than once before capturing it, you can make the /adjustAuthorisation request multiple times for the same payment. In addition, you can use the /adjustAuthorisation call with the same amount as in the original /authorise request in order to extend the authorisation period.

The /adjustAuthorisation API is idempotent. If your system does not receive our confirmation, you can retry the call and it will not affect any other transactions.


The following example illustrates how to first authorise a payment for 15.00 EUR and then change the authorised amount to 17.00 EUR.

Step 1: Authorise a payment

Make an authorisation request for 15.00 EUR. To be able to modify the authorised amount in the future, set the additionalData.authorisationType parameter to PreAuth. For more information, see Card authorisation types.

Submit this request to the /authorise endpoint.

Request

{
   "reference":"YourPaymentReference",
   "merchantAccount":"TestMerchant",
   "card":{
      "number":"4111111111111111",
      "cvc":"737",
      "expiryMonth":"8",
      "expiryYear":"2018",
      "holderName":"John Smith"
   },
   "amount":{
      "currency":"EUR",
      "value":1500
   },
   "additionalData":{
      "authorisationType":"PreAuth"
   }
}
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:authorise xmlns:ns1="http://payment.services.adyen.com">
      <ns1:paymentRequest>
        <reference xmlns="http://payment.services.adyen.com">YourPaymentReference</reference>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <card xmlns="http://payment.services.adyen.com">
          <number>4111111111111111</number>
          <cvc>737</cvc>
          <expiryMonth>8</expiryMonth>
          <expiryYear>2018</expiryYear>
          <holderName>John Smith</holderName>
        </card>
        <amount xmlns="http://payment.services.adyen.com">
          <value xmlns="http://common.services.adyen.com">1500</value>
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
        </amount>
        <additionalData xmlns="http://payment.services.adyen.com">
          <entry>
            <key xsi:type="xsd:string">authorisationType</key>
            <value xsi:type="xsd:string">PreAuth</value>
          </entry>
        </additionalData>
      </ns1:paymentRequest>
    </ns1:authorise>
  </soap:Body>
</soap:Envelope>

Response

{
  "pspReference": "8884689190961333",
  "resultCode": "Authorised",
  "authCode": "83152"
}
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://payment.services.adyen.com">
  <soap:Body>
    <ns0:authoriseResponse>
      <ns0:paymentResult>
        <ns0:pspReference>8884689190961333</ns0:pspReference>
        <ns0:resultCode>Authorised</ns0:resultCode>
        <ns0:authCode>83152</ns0:authCode>
      </ns0:paymentResult>
    </ns0:authoriseResponse>
  </soap:Body>
</soap:Envelope>

Step 2: Modify the amount using Adjust Authorisation

The code below illustrates the Adjust Authorisation modification. For this, pass the pspReference you received in /authorise response as the originalReference parameter for the /adjustAuthorisation.

The initial authorisation must not have been captured, cancelled, or expired.

For information on request and response parameters, refer to AdjustAuthorisationModificationRequest and ModificationResult.

Submit this request to the /adjustAuthorisation endpoint.

Request

{
    "merchantAccount" : "TestMerchant",

    "modificationAmount" : {
        "currency" : "EUR",
        "value" : 1700
    },
    
    "originalReference" : "8884689190961333",
    "reference" : "YourModificationReference",
    "additionalData" : {
        "industryUsage" : "DelayedCharge"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <adjustAuthorisation xmlns="http://payment.services.adyen.com">
            <modificationRequest>
                <merchantAccount>TestMerchant</merchantAccount>
                <modificationAmount>
                    <currency xmlns="http://common.services.adyen.com">EUR</currency>
                    <value xmlns="http://common.services.adyen.com">1700</value>
                </modificationAmount>
                <originalReference>8884689190961333</originalReference>
                <reference>YourModificationReference</reference>
                <additionalData>
                    <entry>
                        <key xsi:type="xsd:string">industryUsage</key>
                        <value xsi:type="xsd:string">DelayedCharge</value>
                    </entry>
                </additionalData>
            </modificationRequest>
        </adjustAuthorisation>
    </soap:Body>
</soap:Envelope> 

Response

{
    "pspReference" : "8413547924770610",
    "response" : "[adjustAuthorisation-received]"
}
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://payment.services.adyen.com">
  <soap:Body>
    <ns0:adjustAuthorisationResponse>
      <ns0:adjustAuthorisationResult>
        <ns0:pspReference>8413547924780610</ns0:pspReference>
        <ns0:response>[adjustAuthorisation-received]</ns0:response>
      </ns0:adjustAuthorisationResult>
    </ns0:adjustAuthorisationResponse>
  </soap:Body>
</soap:Envelope>

Step 3: Get the result notification

After an authorised amount has been adjusted, you will receive an asynchronous callback from Adyen with the modification result. For more information on configuring these callbacks, refer to Notifications.

{
    "live": "false",
    "currency": "EUR",
    "value": "1700",
    "eventCode": "AUTHORISATION_ADJUSTMENT",
    "eventDate": "2017-10-23T13:37:31.00Z",
    "merchantAccountCode": "TestMerchant",
    "merchantReference": "YourModificationReference",
    "operations": "",
    "originalReference": "8884689190961333",
    "paymentMethod": "visa",
    "pspReference": "8515087658508006",
    "reason": "",
    "success": "true"
}
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
      <ns1:notification>
        <live xmlns="http://notification.services.adyen.com">false</live>
        <notificationItems xmlns="http://notification.services.adyen.com">
          <NotificationRequestItem>
            <additionalData xsi:nil="true"/>
            <amount>
              <currency xmlns="http://common.services.adyen.com">EUR</currency>
              <value xmlns="http://common.services.adyen.com">1700</value>
            </amount>
            <eventCode>AUTHORISATION_ADJUSTMENT</eventCode>
            <eventDate>2017-10-09T11:10:03+02:00</eventDate>
            <merchantAccountCode>TestMerchant</merchantAccountCode>
            <merchantReference>YourModificationReference</merchantReference>
            <operations xsi:nil="true"/>
            <originalReference>8884689190961333</originalReference>
            <paymentMethod>visa</paymentMethod>
            <pspReference>8413547924780610</pspReference>
            <reason xsi:nil="true"/>
            <success>true</success>
          </NotificationRequestItem>
        </notificationItems>
      </ns1:notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>

Step 4: Capture the modified amount

Capture the payment using the pspReference of the initial authorisation. You can now capture up to the new adjusted amount.

Submit this request to the /capture endpoint.

Request

{
   "merchantAccount":"TestMerchant",
   "modificationAmount":{
      "value":1700,
      "currency":"EUR"
   },
   "originalReference":"8884689190961333",
   "reference":"YourModificationReference"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:capture xmlns:ns1="http://payment.services.adyen.com">
      <ns1:modificationRequest>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <modificationAmount xmlns="http://payment.services.adyen.com">
          <currency xmlns="http://common.services.adyen.com">EUR</currency>
          <value xmlns="http://common.services.adyen.com">1700</value>
        </modificationAmount>
        <originalReference xmlns="http://payment.services.adyen.com">8884689190961333</originalReference>
        <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
      </ns1:modificationRequest>
    </ns1:capture>
  </soap:Body>
</soap:Envelope>

Response

{
   "pspReference":"8413547924770610",
   "response":"[capture-received]"
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:captureResponse xmlns:ns1="http://payment.services.adyen.com"> 
      <ns1:captureResult> 
        <pspReference xmlns="http://payment.services.adyen.com">8413547924770610</pspReference>
        <response xmlns="http://payment.services.adyen.com">[capture-received]</authCode>
      </ns1:captureResult> 
    </ns1:captureResponse> 
  </soap:Body> 
</soap:Envelope>

See also