Click here to search the entire website

Batched modifications

This service lets you group multiple post-processing requests together for submission.

On this page:

Jump to reference 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)

  • 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:

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

Select

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

Example batch processing request (five orders)

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.

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

Reply to a batch processing request

 

What you can modify

You can modify any order that we've received (either via single payment requests or batch 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 up notifications to push these updates to you (recommended), or use order inquiries.

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

Batch status codes

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

Status Description
ORDERS_SAVED

This 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 a batch cancellation.

CANCELLED Your request to cancel the batch was successful.
PROCESSED The batch has been processed and no errors were encountered.
PROCESSED_WITH_ERRORS The batch has been processed but some errors were encountered.

Example inquiry

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"> <!--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):

<?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 a batch inquiry.

Batches can only be cancelled via the payment service:

Example cancellation

To cancel a batch, send a <batchModification>:

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"> <!--Enter your own merchant code-->

  <modify>

    <batchModification merchantBatchCode="BATCH_CODE"> <!--Enter the relevant Batch Code-->

      <cancel/>

    </batchModification>

  </modify>

</paymentService>

Example batch cancellation request

Our reply

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

Our response

XML reference

Elements/attributes Format Length M/O Description
<batchServiceversion> "1.0" N/A M Service version

<batchService>

    merchantCode

A-Z 0-9 25 M Your merchant code

<batchService>

    batchCode

a-z A-Z 0-9

- _ : [ * . space

25 M Your reference for the batch

<amount>

    value

0-9 10 M Amount in minor units. Maximum value 2147483647

<amount>

    currencyCode

A-Z 3 M ISO 4217 currency code

<amount>

    exponent

0, 2 or 3 1 M Currency exponent
orderCode a-z A-Z 0-9 some special characters 64 M The order code you are modifying
reference a-z A-Z 0-9 some special characters 128 O

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

<referredCapture>

  authorisation code

0-9 TBC M Authorisation code from the card issuer.

<referral>

  [action]

stop, white or remove N/A M

stop - add to blacklist

white - add to whitelist

remove - remove from all lists

<referral>

  [reason]

a-z A-Z 0-9 some special characters 255 O Reason for adding to or removing from the white or black list.