Click here to search the entire website

Modification requests

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

Jump to reference 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 with notifications allows you to respond more rapidly to information about your orders.

Structure of an order modification

To modify orders created in the Direct payment requests or Hosted payment requests pages, 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

Select

<?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 in Types of modification and how they're used.

<?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 the order 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 the Merchant Interface Guide for 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.

Select

<?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 it here).

    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 a notification (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 in RFI/Dispute errors.

XML reference

Modify elements

Order modification elements/attributes

M/O

Description

<modify>

Mandatory

The instruction to modify.

<orderModification>

    orderCode

Mandatory

The instruction to modify the particular order (denoted by the orderCode).

<cancel/>

Optional

The request to cancel an order. Can't be actioned if the payment status has reached CAPTURED.

<capture>

Optional

The request to capture a payment. Must include the <date> and <amount> information.

<capture>

    reference

Optional

The 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.

<refund>

Optional

The request to refund a payment. Must include the <amount> information.

<refund>

    reference

Optional

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

Optional

The request to cancel (if AUTHORISED) or refund (if CAPTURED) a payment. Must include the <amount> information.

<addBackOfficeCode>

    backOfficeCode

Optional The request to add your particular back office code to an order (and the backOfficeCode attribute contains the code).

<increaseAuthorisation>

Optional The request to increase authorisation for Top Up Credit Card authorisations. Only applies to AMEX, Elavon or CCA. Must include the <amount> information.
<authorise>

    authorisationCode

Optional

The request to add issuer's authorisation code to formerly REFERRED payments. Only applies if you're enabled for referrals

Response elements

Order modification elements/attributes

M/O

Description

<cancelReceived>

    orderCode

Optional

We've received your cancel request for the given orderCode.

<captureReceived>

    orderCode

Optional We've received your capture request for the given orderCode and <amount>.

<refundReceived>

    orderCode

Optional

We've received your refund request for the given orderCode and <amount>.

<voidReceived>

    orderCode

Optional

We've received your <cancelOrRefund> request for the given orderCode and <amount>.

<backofficeCodeReceived>

    orderCode

Optional

We've received your backOfficeCode for the given orderCode.

<authorisationCodeReceived>

    orderCode

Optional We've received your authorisationCode for the given orderCode.

Want to send batches of modification requests? Use our batched modification service