Click here to search the entire website

Batch orders

Instead of sending Worldpay orders for processing individually, you can submit a large number of orders in one batch.

All payment types can be included in an individual batch, including Tokenisation and Client Side Encryption requests.

You can:

  • Perform a batch inquiry to find out the status of the batch and the payment statuses of the orders within

Jump to reference tables.

Benefits

Sending batch orders is right for you if:

  • You do not need immediate online feedback on the status of orders

  • The selected payment method requires little or no interaction with the shopper, after the order has been placed (for example, an offline payment with Giropay, or a debit payment with Solo)

  • Your business model allows you to store large numbers of orders securely on your own platform, and send them to Worldpay at regular intervals for processing

orderBatch element

To group orders created in Payment requests, the <submit> element contains an <orderBatch> element. The <orderBatch>element contains multiple <order> elements, which in turn contain your orders. Each batch order should ideally contain between 100 and 3000 individual orders.

The <orderBatch> element has two attributes:

  • transactions - The number of orders in the batch

  • merchantBatchCode - The unique identifier for the batch

Example orderBatch element

<orderBatch transactions="300" merchantBatchCode="B0123">
</orderBatch>

orderBatch attributes

Example batch order

This example has only 3 orders, but ideally you should submit between 100 and 3,000:

Select

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE paymentService PUBLIC "-//Worldpay/DTD WorldpayPaymentServicev1//EN"

  "http://dtd.worldpay.com/paymentService_v1.dtd">

<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">

  <submit>

    <orderBatch transactions="3" merchantBatchCode="B0001"> <!--Enter the batch identifier which must be unique-->

      <order orderCode="YOUR_ORDER_CODE">

        <description>YOUR_DESCRIPTION</description>

        <amount currencyCode="GBP" exponent="2" value="5000"/>

        <paymentDetails>

          <CARD-SSL>

            <cardNumber>4444333322221111</cardNumber>

            <expiryDate><date month="01" year="2020"/></expiryDate>

            <cardHolderName>A Shopper</cardHolderName>

            <cardAddress>

              <address>

                <address1>47A</address1>

                <address2>Queensbridge Road</address2>

                <address3>Suburbia</address3>

                <postalCode>CB94BQ</postalCode>

                <city>Cambridge</city>

                <state>Cambridgeshire</state>

                <countryCode>GB</countryCode>

              </address>

            </cardAddress>

          </CARD-SSL>

          <session shopperIPAddress="123.123.123.123" id="0215ui8ib1"/>

        </paymentDetails>

        <shopper>

          <shopperEmailAddress>jshopper@myprovider.com</shopperEmailAddress>

          <browser>

            <acceptHeader>text/html</acceptHeader>

            <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>

          </browser>

        </shopper>

      </order>

      <order orderCode="SECOND_ORDER_CODE">

        <description>YOUR_DESCRIPTION</description>

        <amount value="2600" currencyCode="EUR" exponent="2"/>

        <orderContent>

          <![CDATA[order content here]]>

        </orderContent>

        <paymentDetails>

          <SEPA_DIRECT_DEBIT-SSL>

            <bankAccount-SEPA>

              <iban>NL36200400000628808808</iban>

              <accountHolderName>A Shopper</accountHolderName>

            </bankAccount-SEPA>

          </SEPA_DIRECT_DEBIT-SSL>

        </paymentDetails>

        <shopper>

          <shopperEmailAddress>jshopper@myprovider.nl</shopperEmailAddress>

        </shopper>

      </order>

      <order orderCode="THIRD_ORDER_CODE">

        <description>YOUR_DESCRIPTION</description>

        <amount currencyCode="GBP" exponent="2" value="5000"/>

        <paymentDetails>

          <CARD-SSL>

            <cardNumber>5454545454545454</cardNumber>

            <expiryDate><date month="01" year="2020"/></expiryDate>

            <cardHolderName>A Shopper</cardHolderName>

            <cardAddress>

              <address>

                <address1>47A</address1>

                <address2>Queensbridge Road</address2>

                <address3>Suburbia</address3>

                <postalCode>CB94BQ</postalCode>

                <city>Cambridge</city>

                <state>Cambridgeshire</state>

                <countryCode>GB</countryCode>

              </address>

            </cardAddress>

          </CARD-SSL>

          <session shopperIPAddress="123.123.123.123" id="0215ui8ib1"/>

        </paymentDetails>

        <shopper>

          <shopperEmailAddress>ashopper@myprovider.com</shopperEmailAddress>

        </shopper>

      </order>

    </orderBatch>

  </submit>

</paymentService>

Example batch order

Example response to a batch order

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN"

  "http://dtd.worldpay.com/paymentService_v1.dtd">

<paymentService merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the order-->

  <reply>

    <batchStatus transactions="3" merchantBatchCode="B0001" status="ORDERS_SAVED"/> <!--The batch details you supplied in the order-->

  </reply>

</paymentService>

Response to a batch order (batchStatus)

When we receive a valid and correctly formatted batch order, our reply message confirms that the (<batchStatus>) is ORDERS_SAVED. The batch order will be processed at a scheduled time.

The orders from the batch are processed individually and invalid orders will generate individual error messages (for these, see General errors). The batch order is given another batch status when the payments have been processed, as explained in the table below.

Batch order statuses

Attribute

Values

ORDERS_SAVED

Indicates that Worldpay:

  • Has saved the batch for processing at a scheduled time

  • Was able to parse the XML in the batch order

The orders from the batch are processed individually. Invalid orders will generate individual error messages.

CANCELLED

You can cancel batch orders with the status ORDERS_SAVED by sending a <modify> element (explained in Cancel a batch order). The orders in a cancelled batch will not have been processed and will have no payment status.

PROCESSED

This status indicates that all orders within the batch have been processed and that no errors were encountered.

PROCESSED_WITH_ERRORS

This status indicates that the orders within the batch have been processed but some errors were encountered.

Cancel a batch order

You can only cancel a batch if it is not yet processed (if it has a status of ORDERS_SAVED).

The <paymentService> root element contains the child element <modify> and its child <batchModification>. Within this, send us the <cancel/> request as shown here:

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

    <batchModification merchantBatchCode="B0001"/> <!--Enter the relevant batch identifier-->

      <cancel/>

    <batchModification/>

  </modify>

</paymentService>

Example cancel batch order request

When you cancel an order batch, Worldpay sends no reply message.

Note:  In addition to cancelling a batch, you can also manipulate multiple orders within (and outside of) a batch, using our batched modification service.

Batch inquiries

Use batch inquiries to find out the status of a batch, including the payment statuses of its individual payments.

The <paymentService> root element contains the child element <inquiry> and its child <batchInquiry>. The latter has the required attribute merchantBatchCode.

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

  <inquiry>

    <batchInquiry merchantBatchCode="979"/> <!--Enter the relevant batch identifier-->

  </inquiry>

</paymentService>

Example batch inquiry

Our reply to a batch inquiry

When we have received your valid batch inquiry, we respond with an XML message that contains the batch status and the payment statuses of the individual orders in the batch. The example reply shown below is for a processed batch that contains the two orders 1003B979 and 1004B979, both having authorised payments:

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

  <reply>

    <batchStatus merchantBatchCode="979" status="PROCESSED" transactions="6"> <!--The merchantBatchCode is the batch code you supplied in the order-->

      <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the first batch order-->

        <payment>

          <paymentMethod>VISA-SSL</paymentMethod>

          <amount value="14000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>

          <lastEvent>AUTHORISED</lastEvent>

        <AuthorisationId id="622206"/>

          <reference>YourReference</reference> <!--Returned if added to capture or refund modifications-->

          <balance accountType="IN_PROCESS_AUTHORISED">

            <amount value="14000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>

          </balance>

          <cardNumber>4444********1111</cardNumber>

        </payment>

      </orderStatus>

      <orderStatus orderCode="ExampleOrder2"> <!--The orderCode you supplied in the second batch order-->

        <payment>

          <paymentMethod>ECMC-SSL</paymentMethod>

          <amount value="70600" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>

          <lastEvent>AUTHORISED</lastEvent>

        <AuthorisationId id="622206"/>

          <balance accountType="IN_PROCESS_AUTHORISED">

            <amount value="70600" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>

          </balance>

          <cardNumber>5555********4444</cardNumber>

        </payment>

      </orderStatus>

    </batchStatus>

  </reply>

</paymentService>

Our reply to a batch inquiry

Note:  Although batch inquiries can be a useful tool, we recommend that you instead use automatic order notifications to find out about changes to the transactions in a batch. Inquiries will not always return the real-time status of in-flight transactions.

XML reference

Batch order elements

Elements/attributes

M/O

Description

<orderBatch>

    transactions

Mandatory The number of individual orders in the batch.

<orderBatch>

    merchantBatchCode

Mandatory The batch identifier, which must be unique.

<order>

    orderCode

Mandatory

The order code for each specific order in the batch.

Batch cancel elements

Elements/attributes

M/O

Description

<modify>

Mandatory The instruction to modify.

<BatchModification>

    merchantBatchCode

Mandatory The instruction to modify the particular batch (denoted by the merchantBatchCode).

</cancel>

Mandatory

The instruction to cancel this batch.

Batch inquiry elements

Elements/attributes

M/O

Description

<inquiry>

Mandatory The instruction to request information.

<batchInquiry>

    merchantBatchCode

Mandatory The instruction to request the status of the particular batch (denoted by the merchantBatchCode).