- Home
- All APIs
- WPG guide
- About Direct
- Batch orders
Batch orders
Instead of sending Worldpay orders for processing individually, you can submit a large number of orders in one batch.
All payment types (except
You can:
- Submit
batch orders to Worldpay at any time of day Cancel a batch order- Perform a
batch inquiry to find out the status of the batch and the payment statuses of the orders within
Jump to
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<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 batchmerchantBatchCode
- The unique identifier for the batch
Example orderBatch element
<orderBatch transactions="300" merchantBatchCode="B0123">
</orderBatch>
<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:
<?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
<?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, see
Batch order statuses
Attribute | Values |
---|---|
ORDERS_SAVED | Indicates that Worldpay:
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 |
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>
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
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
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). |