Modifications EE

You can submit modifications through your merchant account through the Adyen Customer Area (CA). If you are processing more than a handful of payments on a daily basis, we recommend automating this process; to do this, we make available a web service that accepts the modification requests from your server.

To submit modification messages through our API, you need to provide valid authentication credentials:

  • The user name format is ws@Company.[YourCompanyAccount].
  • To set the corresponding password, go to the the Adyen Customer Area (CA), then select Settings  -> Users.

Adyen replies to modification requests with an appropriate response message, for example captureReceivedcancelReceived or refundReceived. This message acknowledges your modification request; however, it does not serve as a modification confirmation. After your request is processed, you receive a notification to inform you if the payout was successful.

These are the modification request types you can submit. You can also see the endpoints for these requests:

You can capture payments only for payment methods that support distinct authorisations and captures.

After authorising a payment, you can capture it to complete the transaction and collect the payment.

Request

To capture an authorised payment, you send a modification request to the capture action, where you pass the fields described below.

To define a capture delay, go to the Adyen Customer Area (CA), then select Settings | Merchant Setting | Capture Delay.

The Adyen Customer Area (CA) offers an option to configure an automated capture process to automatically capture payments after a specified number of days, ranging from no delay, i.e. immediate capture, up to 14 days.

Name Type Required Description
merchantAccount String (tick)

The merchant account where the transaction, for which the request needs to be initiated, was processed.

modificationAmount Class (tick)

The amount to capture. It consists of:

  • value
  • currency
The  currency must match the currency used in the original payment request.

The value must be smaller than or equal to the authorised amount.

value int (tick)

The payable amount that can be charged for the transaction, in minor units.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.
currency String (tick)

The three-character ISO currency code.

The  currency value must match the corresponding  currency value used in the original payment request.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is syntactically valid you receive a captureReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [capture-received].
  • If it fails, an error message is returned.

Capture final result

In most cases, the final result of a capture is sent with a notification message whose eventCode value is CAPTURE.

The  pspReference in this notification is the same as the  pspReference in the capture modification response.

The success field in the response indicates if the capture was successful or not:

  • true: the capture was successful
  • false: the capture failed. In this case, the notification message includes a reason field with a short description of the problem.

Offline capture

Some payment methods handle the capture process offline. Sometimes, we may receive a failure. In such a scenario, we send a notification message whose eventCode value is CAPTURE_FAILED.

The pspReference of this notification is the same as the pspReference in the capture modification response.

The success field in the response is set to true.

Examples

The following code examples show payment capture modification requests and responses in JSON, FORM, and SOAP.

Request:

{
    "merchantAccount" : "TestMerchant",

    "modificationAmount" : {
        "value" : 500,
        "currency" : "EUR"
    },
    
    "originalReference" : "8313547924770610",
    "reference" : "YourModificationReference"
}

Response:

{
    "pspReference" : "8413547924770610",
    "response" : "[capture-received]"
}

Request:

 <?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">500</value>
        </modificationAmount>
        <originalReference xmlns="http://payment.services.adyen.com">8313547924770610</originalReference>
        <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
      </ns1:modificationRequest>
    </ns1:capture>
  </soap:Body>
</soap:Envelope>

Response:

<?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>

Request:

merchantAccount=TestMerchant&originalReference=8313547924770610&reference=YourModificationReference&modificationAmount.currency=EUR&modificationAmount.value=500 

Response:

pspReference=8413547924770610&response=%5Bcapture-received%5D

You can cancel payments only for payment methods that support distinct authorisations and captures.

After authorising a payment, you may wish to cancel it.

Request

To cancel an authorised payment, you send a modification request to the cancel action, where you pass the fields described below.

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [cancel-received].
  • If it fails, an error message is returned.

Cancel final result

The final result of a cancellation is sent with a notification message whose eventCode value is CANCELLATION.

The pspReference of this notification is the same as the pspReference in the cancel modification response.

The success field in the response indicates if the cancellation was successful or not:

  • true: the cancellation was successful
  • false: the cancellation failed. In this case, the notification message includes a reason field with a short description of the problem.

Examples

The following code examples show payment cancellation modification requests and responses in JSON, FORM, and SOAP.

Request:

{
    "merchantAccount" : "TestMerchant",
    "originalReference" : "8313547924770610",
    "reference" : "YourModificationReference"
}

Response:

{
    "pspReference" : "8412534564722331",
    "response" : "[cancel-received]"
}

Request:

<?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:cancel xmlns:ns1="http://payment.services.adyen.com">
      <ns1:modificationRequest>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <originalReference xmlns="http://payment.services.adyen.com">8313547924770610</originalReference>
        <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
      </ns1:modificationRequest>
    </ns1:cancel>
  </soap:Body>
</soap:Envelope>

Response:

<?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:cancelResponse xmlns:ns1="http://payment.services.adyen.com"> 
      <ns1:cancelResult> 
        <pspReference xmlns="http://payment.services.adyen.com">8412534564722331</pspReference>
        <response xmlns="http://payment.services.adyen.com">[cancel-received]</authCode>
      </ns1:cancelResult> 
    </ns1:cancelResponse> 
  </soap:Body> 
</soap:Envelope>

Request:

merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=8313547924770610

Response:

pspReference=8412534564722331&response=%5Bcancel-received%5D

You may need to issue a refund when you cancel a payment and return the partially or fully charged amount to the shopper.

After capturing a payment and charging the shopper, it may  be necessary to return the paid amount to the shopper if they request a refund.

When sending the refund request through API you will receive the [refund-received] response. We send out the notification with the result of the refund as soon as it is processed.

Request

To initiate a refund of an authorised and charged payment, you send a modification request to the refund action, where you pass the fields described below:

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
modificationAmount Class (tick)

A container for the amount that needs to be refunded.

It contains the following elements:

  • value
  • currency

The  currency must match the currency used in the original payment request.

The value must be smaller than or equal to the authorised amount.

value int (tick)

The refundable amount that can be returned to the shopper.

The transaction amount needs to be represented in minor units according to the Currency codes table. Some currencies do not have decimal points, such as JPY, and some have 3 decimal points, such as BHD. For example, 10 GBP is submitted as 1000, whereas 10 JPY is submitted as 10.

currency String (tick)

The three-character ISO currency code.

The  currency value must match the corresponding  currency value used in the original payment request.

originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is valid and if the specified merchantAccount is correct, you receive a refundReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [refund-received].
  • If it fails, an error message is returned.

Refund final result

The final result of a refund is sent with a notification message whose eventCode value is REFUND.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Offline refund

Some payment methods handle the refund process offline. Sometimes, we may receive a failure. In such a scenario, we send a notification message whose eventCode value is REFUND_FAILED.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response is set to true.

Examples

The following code examples show payment refund modification requests and responses in JSON, FORM, and SOAP.

Request:

{
    "merchantAccount" : "TestMerchant",
    
    "modificationAmount" : {
        "value" : 500,
        "currency" : "EUR"
    },
    
    "originalReference" : "9313547924770610",
    "reference" : "YourModificationReference"
}

Response:

{
    "pspReference" : "8312534564722331",
    "response" : "[refund-received]"
}

Request:

<?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:refund 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">500</value>
        </modificationAmount>
        <originalReference xmlns="http://payment.services.adyen.com">9313547924770610</originalReference>
        <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
      </ns1:modificationRequest>
    </ns1:refund>
  </soap:Body>
</soap:Envelope>

Response:

<?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:refundResponse xmlns:ns1="http://payment.services.adyen.com"> 
      <ns1:refundResult> 
        <pspReference xmlns="http://payment.services.adyen.com">8312534564722331</pspReference>
        <response xmlns="http://payment.services.adyen.com">[refund-received]</authCode>
      </ns1:refundResult> 
    </ns1:refundResponse> 
  </soap:Body> 
</soap:Envelope>

Request:

merchantAccount=TestMerchant&originalReference=9313547924770610&reference=YourModificationReference&modificationAmount.currency=EUR&modificationAmount.value=500

Response:

pspReference=8312534564722331&response=%5Brefund-received%5D

If you are not sure whether a payment has been correctly captured, and at the same time you want to reverse the payment authorisation, you can issue a cancel or refund.

Request

To initiate a cancellation or refund of an authorised payment that may or may not have been captured, you send a modification request to the cancelOrRefund action, where you pass the fields below.

Name Type Required Description
merchantAccount String (tick) The merchant account where the transaction, for which the request needs to be initiated, was processed.
originalReference String (tick)
The  originalReference value corresponds to the  pspReference value assigned to the original payment.

You receive the pspReference with:

  • The payment status, or
  • The authorisation notification.
reference String (error)
If you want, you can specify your reference for the modification request.
The reference is visible in the Merchant Backoffice and in the reporting section.
This field has a length restriction: you can enter max. 80 characters.

Response

If the message you send with the call is valid and if the specified merchantAccount is correct, you receive a cancelOrRefundReceived response with the following fields:

Name Type Returned by default Description
pspReference String (tick)

Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request.

response String (tick)
  • If the request is successful, the returned value is [cancelOrRefund-received].
  • If it fails, an error message is returned.

Cancel or refund scenarios

The final result of a refund is sent with a notification message whose eventCode value is REFUND.

The pspReference of this notification is the same as the pspReference in the refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Payment authorised but not captured

If the payment is authorised, but not yet captured, it is cancelled.

 If the selected payment method for the transaction does not support cancellation, the transaction amount us fully refunded.

Cancellation

If the cancel or refund modification request produces a cancellation, the final result is sent with a notification message whose eventCode value is CANCEL_OR_REFUND.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response indicates if the cancellation was successful or not:

  • true: the cancellation was successful
  • false: the cancellation failed. In this case, the notification message includes a reason field with a short description of the problem.

Refund

If the cancel or refund modification request produces a refund, the final result is sent with a notification message whose eventCode value is CANCEL_OR_REFUND.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response indicates if the refund was successful or not:

  • true: the refund was successful
  • false: the refund failed. In this case, the notification message includes a reason field with a short description of the problem.

Failure

If the cancel or refund modification request fails, the final result is sent with a notification message whose eventCode value is SUCCESS=FALSE.

The pspReference of this notification is the same as the pspReference in the cancel or refund modification response.

The success field in the response is set to false: the refund failed.

The notification message includes a reason field with a short description of the problem.

Examples

The following code examples show payment cancel or refund modification requests and responses in JSON, FORM, and SOAP.

Request:

{
    "merchantAccount" : "TestMerchant",
    "originalReference" : "9313547924770610",
    "reference" : "YourModificationReference"
}

Response:

{
    "pspReference" : "8863534564726784",
    "response" : "[cancelOrRefund-received]"
}

Request:

<?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:cancelOrRefund xmlns:ns1="http://payment.services.adyen.com">
      <ns1:modificationRequest>
        <merchantAccount xmlns="http://payment.services.adyen.com">TestMerchant</merchantAccount>
        <originalReference xmlns="http://payment.services.adyen.com">9313547924770610</originalReference>
        <reference xmlns="http://payment.services.adyen.com">YourModificationReference</reference>
      </ns1:modificationRequest>
    </ns1:cancelOrRefund>
  </soap:Body>
</soap:Envelope>

Response:

<?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:cancelOrRefundResponse xmlns:ns1="http://payment.services.adyen.com"> 
      <ns1:cancelOrRefundResult> 
        <pspReference xmlns="http://payment.services.adyen.com">8863534564726784</pspReference>
        <response xmlns="http://payment.services.adyen.com">[cancelOrRefund-received]</authCode>
      </ns1:cancelOrRefundResult> 
    </ns1:cancelOrRefundResponse> 
  </soap:Body> 
</soap:Envelope>

Request:

merchantAccount=TestMerchant&reference=YourModificationReference&originalReference=9313547924770610

Response:

pspReference=8863534564726784&response=%5BcancelOrRefund-received%5D