Search

Are you looking for test card numbers?

Would you like to contact support?

Online-payment icon

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 before the payment is captured. This allows for tipping as the amount can be changed based on the tip, charging after the customer has left the premises, like charging for beverages consumed from a hotel mini-bar, and may increase the length of time you can capture an authorised payment.

Adjust Authorisation is currently available only for Discover, Visa, and Mastercard. Support is ultimately up to the issuer.

To change the amount, send a modification request to the /adjustAuthorisation endpoint. A synchronous response confirms that a modification was received, and an asynchronous notification contains the result of a modification.

The advantages of adjusted authorisation over a new authorisation:

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

To modify the amount more than once before capturing, make multiple /adjustAuthorisation requests. Additionally, you can make a /adjustAuthorisation request with the same amount as in the original /authorise request to extend the authorisation period.

The API is idempotent. If you do not receive confirmation, you can retry the call and it will not affect any other transactions.

Authorisation types

For some schemes, you can set each card payment request to be handled as either a pre-authorisation or a final authorisation.

  • Pre-authorisation is used when the amount to be authorised is unknown. For example, when the customer adds a tip. This allows you to increase or decrease the amount later using the /adjustAuthorisation endpoint.
  • Final authorisation is used where a final amount is agreed up front and the transaction will definitely be captured in whole. It cannot be adjusted.

By default, Adyen handles all card payment requests as final authorisations.

To use this functionality, choose one of the following options:

  • Define a default authorisation flow at the merchant level for all card transactions. This functionality requires additional configuration on Adyen's end. To enable it, contact the Support Team.
  • Manually specify the authorisation type in each payment request. For this, add an authorisationType parameter to the additionalData object. For more information, refer to authorisationType.

Step 1: Authorise a payment

  1. Make an authorisation request for 15.00 EUR. Set the additionalData.authorisationType parameter to PreAuth.
  2. 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 API Explorer.

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