Batched modifications

Group multiple post-processing requests together for submission.

On this page:

Jump toreference table.

What you can include in a batch

You can modify multiple transactions to:

  • Capture payments
  • Refund payments
  • Cancel or refund payments (depending on status)

    Note: You cannotcancel a Visa card payoutusing the batched modification feature.

  • Process payments that were refused with a refusal reason of REFERRED

For the Risk Management Module (RMM), you can:

  • Add or remove payment details to or from the RMM white and black lists

Connecting with the service

Create a secure connection in the same way you do to submit a payment to Worldpay (with your existing username and password for the merchant code).

Remember that the connection to Worldpay's test and live environments can also be restricted by IP address. If you have such a restriction in place, ensure that the server that hosting application for batch processing is within the current white list for both test and live.

URLs

The URLs for the batch post processing service are:

  • Test system https://secure-test.worldpay.com/jsp/merchant/xml/batch.html
  • Live system https://secure.worldpay.com/jsp/merchant/xml/batch.html

Batch size and timing

Batch size

To ensure successful batch processing and avoid potential timeouts, we strongly recommend that a batch has a minimum of 1 and a maximum of 5000 order modifications.

Batch timing

Worldpay processes the batches each day between 07:00 and 22:00 CET (Central European Time).

Structure of a batch processing request

The Worldpay batch DTD http://dtd.worldpay.com/batchService_v1.dtd defines how to interact with batch post processing.

Example batch processing request

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE batchService PUBLIC "-//Worldpay//DTD Worldpay batchService v1//EN"
  "http://dtd.worldpay.com/batchService_v1.dtd">
<batchService version="1.0" merchantCode="YOUR_MERCHANT_CODE" batchCode="BATCH_CODE"> <!--Enter your reference for this batch-->
  <capture orderCode="YOUR_ORDER_CODE_1"> <!--Enter the unique order code for this order-->
    <amount value="100" currencyCode="EUR" exponent="2"/>
  </capture>
  <capture orderCode="YOUR_ORDER_CODE_2"> <!--Enter the unique order code for this order-->
    <amount value="200" currencyCode="EUR" exponent="2"/>
  </capture>
  <capture orderCode="YOUR_ORDER_CODE_3"> <!--Enter the unique order code for this order-->
    <amount value="300" currencyCode="EUR" exponent="2"/>
  </capture>
  <cancelOrRefund orderCode="YOUR_ORDER_CODE_4"> <!--Enter the unique order code for this order-->
  <cancelOrRefund orderCode="YOUR_ORDER_CODE_5"> <!--Enter the unique order code for this order-->
</batchService>

Our reply

Worldpay responds with <ok> where a valid batch that conforms to the batch service DTD has been accepted for processing (it doesn't confirm that the modifications themselves have been successfully processed). Batches are processed offline. This applies to the entire batch, not the contents of the batch.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE batchService PUBLIC "-//Worldpay//DTD Worldpay batchService v1//EN"
  "http://dtd.worldpay.com/batchService_v1.dtd">
<batchService version="1.0" merchantCode="ExampleCode1" batchCode="BatchCode"> <!--The Batch Code you supplied in the modification -->
  <ok/>
</batchService>

What you can modify

You can modify any order that we've received (either via single payment requests orbatch orders. You can modify multiple orders to:

Batch Inquiry

To find out the status of the batch of modifications you have submitted, make a batch inquiry. This inquiry returns the status of the batch and not the status of transactions within the batch. For statuses within the batch, set upnotificationsto push these updates to you (recommended), or useorder inquiries.

Inquires of all types can only be submitted to the payment service:

  • Test service https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
  • Live service https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp

Batch status codes

The status codes you can get as a result of your inquiry:

StatusDescription
ORDERS_SAVEDThis status shows that Worldpay:
  • Was able to parse the XML in the batch order
  • Has saved the batch for processing
The orders from the batch are processed individually. Invalid orders produce individual error messages.

Note: To cancel a batch with the status ORDERS_SAVED, send abatch cancellation.

CANCELLEDYour request to cancel the batch was successful.
PROCESSEDThe batch has been processed and no errors were encountered.
PROCESSED_WITH_ERRORSThe batch has been processed but some errors were encountered.

Example inquiry

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"> <!--Enter your own merchant code-->
  <inquiry>
    <batchInquiry merchantBatchCode="BATCH_CODE"/> <!--Enter the relevant Batch Code-->
  </inquiry>
</paymentService>

Our reply

In this example response the orders in the batch have been saved (ORDERS_SAVED):

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 inquiry-->
  <reply>
    <batchStatus merchantBatchCode="BATCH_CODE" status="ORDERS_SAVED" transactions="3"/>
  </reply>
</paymentService>

Batch Cancellation

You can only cancel a batch that has the status ORDERS_SAVED. To find out if a batch can be cancelled, submit abatch inquiry.

Batches can only be cancelled via the payment service:

  • Test service https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
  • Live service https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp

Example cancellation

To cancel a batch, send a <batchModification>:

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"> <!--Enter your own merchant code-->
  <modify>
    <batchModification merchantBatchCode="BATCH_CODE"> <!--Enter the relevant Batch Code-->
      <cancel/>
    </batchModification>
  </modify>
</paymentService>

Our reply

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>
    <batchStatus merchantBatchCode="BATCH_CODE" status="CANCELLED" transactions="3"/>
  </reply>
</paymentService>

XML reference

Elements/attributesFormatLengthM/ODescription
<batchServiceversion>"1.0"N/AMService version
<batchService>
merchantCode
A-Z 0-925MYour merchant code
<batchService>
batchCode
a-z A-Z 0-9
- _ : [ * . space
25MYour reference for the batch
<amount>
value
0-910MAmount in minor units. Maximum value 2147483647
<amount>
currencyCode
A-Z3MISO 4217 currency code
<amount>
exponent
0, 2 or 31MCurrency exponent
orderCodea-z A-Z 0-9 some special characters64MThe order code you are modifying
referencea-z A-Z 0-9 some special characters128OAdditional reference for the request. Only applies to <refund>, <capture> and <referredCapture>. Will show in capture (or referredCapture) notifications for CAPTURED and SETTLED statuses, and refund notifications for SENT_FOR_REFUND and REFUNDED.
sequenceNumber0-91-2OThe sequence number for the capture within multiple captures that are covered by the same authorisation code. Only applies to <capture>.
totalCount0-91-2OThe total number of captures that are covered by the same authorisation code. Only applies to <capture>.
<referredCapture>
authorisation code
0-9TBCMAuthorisation code from the card issuer.
<referral>
[action]
stop, white or removeN/AMstop - add to blacklist
white - add to whitelist
remove - remove from all lists
<referral>
[reason]
a-z A-Z 0-9 some special characters255OReason for adding to or removing from the white or black list.