Modification requests

How to modify an order you've previously submitted. You can:

Jump toreference table.

Best practice: Using order modifications We recommend that you use order modifications to capture, cancel or refund orders. Performing these tasks manually through the Merchant Admin Interface is only viable for small numbers of orders. Using order modifications in conjunction withnotificationsallows you to respond more rapidly to information about your orders.

Structure of an order modification

To modify orders created in theDirect payment requestsorHosted payment requestspages, the <paymentService> root element must contain the child element <modify>. Within <modify> you add the <orderModification> element that contains the required orderCode attribute.

Example capture modification

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
"http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <capture>
        <amount value="10965" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </capture>
    </orderModification>
  </modify>
</paymentService>

Our reply

Worldpay responds with <ok> where a valid modification that conforms to the payment service DTD has been accepted for processing (it doesn't confirm that the modification itself has been successfully processed, just that we've accepted it).

Note: The content of the <ok> element varies by modification, as covered inTypes of modification and how they're used.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <captureReceived orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
        <amount value="10965" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </captureReceived>
    </ok>
  </reply>
</paymentService>

Checking the status

After an order modification has been successfully processed you can check the new status of the payment or the change:

Types of modification and how they're used

You can use a modification to:

You can only cancel a payment after it has reached the AUTHORISED status. It can no longer be cancelled after it has reached the status of CAPTURED.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <cancel/>
    </orderModification>
  </modify>
</paymentService>

When we receive the above order modification, we reply with:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <cancelReceived orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
    </ok>
  </reply>
</paymentService>

You can capture a payment that is AUTHORISED.

As shown below, you can attach a reference to a capture modification, allowing you to track the modification in your system. This reference can contain up to 128 characters, including special characters. The reference used here will show in notifications for CAPTURED and SETTLED statuses. You can also see references in the Command Batch section of theMAI.
For C - level, Worldpay acquired customers, you may also have the reference shown on selected acquiring reconciliation files, truncated down to a maximum of 20 characters. Contact us for further information.

Capture 1 of 2:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <capture reference="YourReference" sequenceNumber="1" totalCount="2">> <!--Returned if added to capture modifications-->
        <amount value="10965" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </capture>
    </orderModification>
  </modify>
</paymentService>

Capture 2 of 2:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <capture reference="YourReference" sequenceNumber="2" totalCount="2">> <!--Returned if added to capture modifications-->
        <amount value="10965" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </capture>
    </orderModification>
  </modify>
</paymentService>

You can do a partial capture if required. Please note that in general only one capture (partial or full) can be done for each authorised payment. You may have a special arrangement with Worldpay, which enables you to perform multiple partial captures on a single order. If your organization is enabled for multiple partial captures, then additional capture attributes sequenceNumber and totalCount must be included. WPG does not perform validation on these fields, other than for length (no more than two numeric digits). If you pass one of these attributes, validation checks that the other was passed. Validation errors are returned in the response. Jump toModify Elementsfor usage. The total captured amount can never exceed the originally authorised amount.

When we receive the above order modification, we reply with:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <captureReceived orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
        <amount value="10965" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </captureReceived>
    </ok>
  </reply>
</paymentService>

You can request a refund only after a payment has reached the CAPTURED status. Refunds can never exceed the original captured amount, but you can do one or more partial refunds of the captured amount. For Authorised refunds, refer toRefund Authorisation.

Note: As shown below, you can attach a reference to a refund modification, allowing you to track the modification in your system. This reference can contain up to 128 characters, including special characters. The reference used here will show in notifications forSENT_FOR_REFUNDandREFUNDEDstatuses. You can also see references in the Command Batch section of theMAI.
For C - level, Worldpay acquired customers, you may also have the reference shown on selected acquiring reconciliation files, truncated down to a maximum of 20 characters. Contact us for further information.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
"http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <refund reference="YourReference"> <!--Returned if added to refund modifications-->
        <amount value="12720" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </refund>
    </orderModification>
  </modify>
</paymentService>

If your request is valid we will respond with the below message:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <refundReceived orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
        <amount value="12720" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
      </refundReceived>
    </ok>
  </reply>
</paymentService>

Note:This is not proof that the refund has processed.

The refund will be processed if there are funds available and the financial institutions involved support refunds. If you have notifications set up, you will be notified.

If a refund can't be processed then for:

M - level, the transaction status will be updated. C - level, you have to check the relevant acquiring reconciliation files.

From October 2020, the Worldwide Payment Gateway will be supporting online refunds. This is a requirement introduced by Visa that requires refunds to be sent to card issuers for authorisation. This is initially required for the US and Canada, the rest of the world will be progressively introduced for all regions up until April 2022. Other card issuers are expected to adopt this requirement over time.

The Worldwide Payment Gateway (WPG) will determine whether a refund should be authorised or not. You do not need to make any changes to how you submit a refund.

You may want to receive additional information to help understand if a refund has been authorised, and if the authorisation has been successful or not. You should refer to the order notifications section below, particularly those relating to SENT_FOR_REFUND and REFUND_FAILED.

Note: Refunds sent for authorisation are called online refunds throughout our documentation. References and examples can be found in the following locations:

Use this order modification to either cancel (if authorised) or refund (if captured) the payment.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <cancelOrRefund/>
    </orderModification>
  </modify>
</paymentService>

When we receive the above order modification, we reply with:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <voidReceived orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
      </voidReceived>
    </ok>
  </reply>
</paymentService>

When you use a separate code (back-office code) in your system to identify orders that have been processed by us, you can attach this code to an order in our system. The back-office code is different from the order code as supplied by you with the original order details. A back-office code you have attached will appear in the Worldpay transfer reports.

To attach a back-office code to an order, send an order modification containing the <addBackOfficeCode> element to our system at the moment of your choosing. For example:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <addBackOfficeCode backOfficeCode="CAP1234"/>
    </orderModification>
  </modify>
</paymentService>

When we receive the above order modification, we reply with:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <backofficeCodeReceived orderCode="ExampleOrder1" backOfficeCode="CAP1234"/> <!--The orderCode and backOfficeCode you supplied in the modification -->
    </ok>
  </reply>
</paymentService>

You use an increase authorisation request for Top Up Credit Card authorisations. You can only use this request if you have an acquiring relationship with American Express (AMEX), Elavon or CCA.

An authorisation request can only be sent when the feature ‘special property’ has been enabled. For more information, contactcorporatesupport@worldpay.com.

The request is submitted as an order modification to increase the amount to be authorised for an existing order. This example shows a request to increase the authorisation by EUR 5:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <increaseAuthorisation>
        <amount value="500" currencyCode="EUR" exponent="2"/>
      </increaseAuthorisation>
    </orderModification>
  </modify>
</paymentService>

If the initial order amount was EUR 60 and the payment method AMEX-SSL, our reply to the above order modification will be:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the modification -->
      <payment>
        <paymentMethod>AMEX-SSL</paymentMethod>
          <amount value="6000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
          <lastEvent>AUTHORISED</lastEvent>
       <AuthorisationId id="622206"/>
          <balance accountType="IN_PROCESS_AUTHORISED">
            <amount value="6500" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
          </balance>
          <cardNumber>4444********1111</cardNumber>
        </payment>
      </orderStatus>
  </reply>
</paymentService>

In the reply, the <payment> child elements <paymentMethod> and <amount> contain the payment method used and the initially authorised amount (EUR 60). This includes the currency, its exponent and the <debitCreditIndicator> that indicates the amount is positive. The <lastEvent> shows the payment status.

The <balance> element reports on the accountType IN_PROCESS_AUTHORISED in the Worldpay system, which is where the increased authorised amount (EUR 65) is transferred to. For credit card payments, the first and last four digits of the card number are returned in <cardNumber>.

More details on the different account types in the Worldpay system can be found inthe payment process.

You may request the authorisation of a payment and find that it is refused, with the refusal reason REFERRED. In this case, you should contact us for more information. However, this situation only applies if the Worldpay system uses your own accounts with the acquiring banks.

When the acquiring card issuer decides to authorise the payment, they will supply you with an authorisation code. You can send this code either through the Merchant Interface (see theMerchant Interface Guide) or through anorder modificationto change the payment status in the Worldpay system to AUTHORISED.

Authorisation code order modification is only available when your service with Worldpay is enabled for referrals. The default value is ‘not enabled’. Please emailcorporatesupport@worldpay.com.

Below is an example of the <orderModification> child element <authorise>:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <authorise authorisationCode="acbsdf"/>
    </orderModification>
  </modify>
</paymentService>

When we receive the above order modification, we reply with:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the modification -->
  <reply>
    <ok>
      <authorisationCodeReceived orderCode="ExampleOrder1"> authorisationCode="acbsdf"/>
    </ok>
  </reply>
</paymentService>

Note that you cannot use an authorisation code to 're-authorise’ a refund request that has been refused.

There's a table at the bottom of this page describing theorder modification elements and attributes.

Submit a response to an RFI

If you have received a notification about a payment that has been disputed, there are two ways to submit your defence documentation:

  • In an XML request modification
  • Through the Dispute Management menu option in the Merchant Interface. See theMerchant Interface Guidefor details

Submitting defence documentation in an XML request

The modification request contains two tags related to defence documentation – <disputeDefence> and <disputeAttachment>. You must send at least one of these tags.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
  "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <modify>
    <orderModification orderCode="YOUR_ORDER_CODE"> <!--The unique order code for this payment-->
      <defend>
        <disputeDefence><YOUR_DEFENCE_TEXT></disputeDefence> <!--Enter defence text for this order code-->
        <disputeAttachment fileName="defence.txt">ZGVmZW5jZQ==</disputeAttachment> <!--Add a defence file attachment for this order code-->
      </defend>
    </orderModification>
  </modify>
</paymentService>

To submit defence documentation in a request:

  1. Enter the file name of your submission into the fileName attribute. Accepted file extensions are: zip, doc, docx, jpg, jpeg, png, gif, tiff, pdf, txt.

  2. Between the <disputeAttachment> tags, enter the content of the submission file encoded using Base64, as defined by section 6.8 of RFC2045 Internet Message Bodies (find ithere).

    The decoded file content data must not exceed 4MB. The entire XML request must not exceed 8MB.

  3. Upload the document. When the document is uploaded successfully, the payment status changes to INFORMATION_SUPPLIED, and you will receive anotification(providing you have notifications enabled for INFORMATION_SUPPLIED statuses). Note that you cannot modify or delete evidence.

    If you submit a defence submission for an order within 10 minutes of a previous successful submission, you will receive an error response message containing the errorCode = 8.

Note: Getting an error? You can find the codes inRFI/Dispute errors.

XML reference

Modify elements

Order modification elements/attributesM/ODescription
<modify>MandatoryThe instruction to modify.
<orderModification>
orderCode		MandatoryThe instruction to modify the particular order (denoted by the orderCode).
<cancel/>OptionalThe request to cancel an order. Can't be actioned if the payment status has reached CAPTURED.
<capture>OptionalThe request to capture a payment. Must include the <date> and <amount> information.
<capture>
reference		OptionalThe request to add a reference to the capture modification. Can contain up to 128 characters, including special characters. Will show in notifications for CAPTURED and SETTLED statuses.
<capture>
sequenceNumber		OptionalThe request to add a sequence number to the capture modification when you use multiple captures for the same authorisation. Can contain up to two numeric characters and must be used with totalCount. Only applies to <capture>.
<capture>
totalCount		OptionalThe request to add the total number of captures to the capture modification when you use multiple captures for the same authorisation. Can contain up to two numeric characters and must be used with sequenceNumber. Only applies to <capture>.
<refund>OptionalThe request to refund a payment. Must include the <amount> information.
<refund>
reference		OptionalThe request to add a reference to the refund modification. Can contain up to 128 characters, including special characters. Will show in notifications for SENT_FOR_REFUND and REFUNDED statuses.
<cancelOrRefund>OptionalThe request to cancel (if AUTHORISED) or refund (if CAPTURED) a payment. Must include the <amount> information.
<addBackOfficeCode>
backOfficeCode		OptionalThe request to add your particular back office code to an order (and the backOfficeCode attribute contains the code).
<increaseAuthorisation>OptionalThe request to increase authorisation for Top Up Credit Card authorisations. Only applies to AMEX, Elavon or CCA. Must include the <amount> information.
<authorise>
authorisationCode		OptionalThe request to add issuer's authorisation code to formerly REFERRED payments. Only applies if you're enabled for referrals

Response elements

Order modification elements/attributesM/ODescription
<cancelReceived>
orderCode		OptionalWe've received your cancel request for the given orderCode.
<captureReceived>
orderCode		OptionalWe've received your capture request for the given orderCode and <amount>.
<refundReceived>
orderCode		OptionalWe've received your refund request for the given orderCode and <amount>.
<voidReceived>
orderCode		OptionalWe've received your <cancelOrRefund> request for the given orderCode and <amount>.
<backofficeCodeReceived>
orderCode		OptionalWe've received your backOfficeCode for the given orderCode.
<authorisationCodeReceived>
orderCode		OptionalWe've received your authorisationCode for the given orderCode.

Next: Want to send batches of modification requests? Use ourbatched modification service.

Feedback or bugs to report?

Ask our developer community.

Get support

STAY CONNECTED

©2020 Worldpay, LLC and/or its affiliates. All rights reserved.

Within this page
Structure of an order modificationChecking the statusTypes of modification and how they're usedSubmit a response to an RFIXML reference

​

Search our documentation, API references and articles.