Click here to search the entire website

Inquiry requests

You can send us an inquiry to find out the last payment status of an order you have previously submitted.

For details see:

Jump to reference table.

Activating the service

To activate inquiry requests, contact your Relationship Manager.

Why we recommend notifications over inquiries

Inquiries are susceptible to replication delays, and so the results may not always be real-time. If you do use inquiries, you should wait at least 5 minutes after the initial transaction, or after a modification has been sent.

To determine the real-time status of transactions, use order notifications. Notifications are sent to you automatically when the status of a transaction changes, and are available during maintenance periods (whereas inquiries may not be).

Types of inquiry

The three main types of inquiry are:

Note:  For other types of inquiry, speak to your Implementation Manager.

Structure of an order inquiry

To inquire about orders created in the Direct payment requests or Hosted payment requests pages, the <paymentService> root element must contain the child <inquiry>, which in turn must contain the <orderInquiry> about the relevant orderCode:

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>

    <orderInquiry orderCode="YOUR_ORDER_CODE"> <!--Enter the relevant order code-->

  </inquiry>

</paymentService>

Example order inquiry

Our reply

When we have received a valid order inquiry from you, we respond with a message containing the payment status for the 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 version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the inquiry-->

  <reply>

    <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the inquiry-->

      <payment>

        <!--RESPONSE INFORMATION GOES HERE-->

      </payment>

    </orderStatus>

  </reply>

</paymentService>

Our reply

The <payment> element holds the payment details and the status information.

The payment status is specified by the <lastEvent> element.  Depending on the specific payment status various other elements can be shown.

If no payment status can be found for the order, the Worldpay reply contains an error element instead of a payment element.

For an overview of all payment statuses, and for details of the different account types in the Worldpay system see The payment process.

Reply examples

 

Structure of a refundable amount inquiry

Use <refundableAmountInquiry> to find the available refundable balance of a transaction:

Select

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

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

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

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

  <inquiry>

    <refundableAmountInquiry orderCode="YOUR_ORDER_CODE"/>

  </inquiry>

</paymentService>

Example refundable amount inquiry

Refundable amount inquiry response

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

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

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

<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the inquiry-->

  <reply>

    <refundableAmount orderCode="ExampleOrder1"> <!--The orderCode you supplied in the inquiry-->

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

      <date dayOfMonth="01" month="01" year="2020" hour="01" Minute="01" second="01"> </date>

    </refundableAmount>

  </reply>

</paymentService>

Our response

XML reference

Inquiry elements

Elements/attributes

M/O

Description

<inquiry>

Optional The instruction to request information.

<batchInquiry>

Optional The instruction to request the status of the particular batch (denoted by the merchantBatchCode).
<refundableAmountInquiry>

  orderCode

Optional The instruction to find out the available refundable balance of this transaction.

Response elements

Elements/attributes

M/O

Description

<thirdPartyReference> Optional Returned if you have enabled the third party reference facility. Used as an identifier when tracking refunds from an issuer/scheme. Contact us to turn this on.
<refundableAmount> Optional Returns details of the available refundable balance of a transaction.
<ISO8583ReturnCode> Optional Returns the refusal response code from the issuer and a mapped description (reason) from Worldpay. For a list of response codes and their descriptions, see Issuer Response Codes.