Menu

Batch orders

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

All payment types (exceptcard payoutscan be included in an individual batch, includingTokenisationandClient Side Encryptionrequests.

You can:

  • Submitbatch ordersto Worldpay at any time of day
  • Cancela batch order
  • Perform abatch inquiryto find out the status of the batch and the payment statuses of the orders within

Jump toreference 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 inPayment 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

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

Example batch order

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

Copied!
<?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 response to a batch order

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay/DTD WorldpayPaymentServicev1//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>

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, seeGeneral errors). The batch order is given another batch status when the payments have been processed, as explained in the table below.

Batch order statuses

AttributeValues
ORDERS_SAVEDIndicates 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.
CANCELLEDYou can cancel batch orders with the status ORDERS_SAVED by sending a <modify> element (explained inCancel a batch order). The orders in a cancelled batch will not have been processed and will have no payment status.
PROCESSEDThis status indicates that all orders within the batch have been processed and that no errors were encountered.
PROCESSED_WITH_ERRORSThis 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:

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">
   <modify>
      <batchModification merchantBatchCode="B0001" /> <!--Enter the relevant batch identifier-->
      <cancel />
      <batchModification />
   </modify>
</paymentService>

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

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

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 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 automaticorder notificationsto 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/attributesM/ODescription
<orderBatch>
transactions		MandatoryThe number of individual orders in the batch.
<orderBatch>
merchantBatchCode		MandatoryThe batch identifier, which must be unique.
<order>
orderCode		MandatoryThe order code for each specific order in the batch.

Batch cancel elements

Elements/attributesM/ODescription
<modify>MandatoryThe instruction to modify.
<BatchModification>
merchantBatchCode		MandatoryThe instruction to modify the particular batch (denoted by the merchantBatchCode).
</cancel>MandatoryThe instruction to cancel this batch.

Batch inquiry elements

Elements/attributesM/ODescription
<inquiry>MandatoryThe instruction to request information.
<batchInquiry>
merchantBatchCode		MandatoryThe instruction to request the status of the particular batch (denoted by the merchantBatchCode).