- Home
- All APIs
- WPG guide
- Order notifications
- Modification requests
Modification requests
How to modify an order you've previously submitted. You can:
- Send
order modifications tocancel ,capture orrefund the payment that belongs to an order - Add a
back-office code to an order - Send an
authorisation code Increase authorisation Submit a response to a Request For Information (RFI)
Jump to
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
Structure of an order modification
To modify orders created in 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
<?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
<?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:
- Via
order notifications - By sending an
order inquiry - Via the Command Batch section of the Merchant Admin Interface (shown in the
Merchant Admin Interface Guide )
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.
<?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:
<?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>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 the
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:
<?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:
<?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 to
When we receive the above order modification, we reply with:
<?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>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 for
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.
<?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:
<?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:
Order Notifications - Common statuses (Table) - SENT_FOR_REFUNDOrder Notifications - Additional statuses (Table) - REFUND_FAILEDOrder Notifications - Other notification examples - A refund request for EUR 44.65Order Notifications - A refund failedThe payment process - C/M/R/S-level payment flow (Note for each service level)The payment process - C/M/R/S-level payment statuses (Table for each service level) - SENT_FOR_REFUNDThe payment process - C/M/R/S-level payment statuses (Table for each service level) - REFUND_FAILED
Use this order modification to either cancel (if authorised) or refund (if captured) the payment.
<?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:
<?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:
<?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:
<?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, contact
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:
<?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:
<?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 in
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 the
Authorisation code order modification is only available when your service with Worldpay is enabled for referrals. The default value is ‘not enabled’. Please email
Below is an example of the <orderModification> child element <authorise>:
<?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:
<?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 the
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.
<?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:
Enter the file name of your submission into the
fileNameattribute. Accepted file extensions are: zip, doc, docx, jpg, jpeg, png, gif, tiff, pdf, txt.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.
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
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. |
<capture>sequenceNumber | Optional | The 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 | Optional | The 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> | 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. |
Next: Want to send batches of modification requests? Use our
