Menu

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:

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.