Click here to search the entire website

Inquiry requests

Get information about orders you've submitted, or your payment options for a specific country.

For details see:

Jump to reference table.

Activate the service

To activate inquiry requests, contact your Relationship Manager.

Types of inquiry

The four main types of inquiry are:

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

Why we recommend notifications over order inquiries

Order inquiries (the most popular type of inquiry) are susceptible to replication delays, and so the results may not always be real-time. If you do use order inquiries, you should wait at least 5 minutes after the initial transaction, or after a modification request 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).

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 response

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 response

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.

Other response examples

 

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

Payment options inquiry

Use <paymentOptionsInquiry> to see which payment methods are available for a particular countryCode:

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>

    <paymentOptionsInquiry countryCode="NL"/>

  </inquiry>

</paymentService>

Payment options inquiry response

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

  <reply>

    <paymentOption>PAYPAL-EXPRESS</paymentOption>

    <paymentOption>DINERS-SSL</paymentOption>

    <paymentOption>ECMC-SSL</paymentOption>

    <paymentOption>VISA-SSL</paymentOption>

    <paymentOption>AMEX-SSL</paymentOption>

    <paymentOption>DISCOVER-SSL</paymentOption>

    <paymentOption>MAESTRO-SSL</paymentOption>

    <paymentOption>JCB-SSL</paymentOption>

    <paymentOption>CASH-DELIVERY</paymentOption>

    <paymentOption>INCASSO_NL-FAX</paymentOption>

    <paymentOption>SEPA_DIRECT_DEBIT-SSL</paymentOption>

    <paymentOption>AIRPLUS-SSL</paymentOption>

    <paymentOption>BOKU-SSL</paymentOption>

    <paymentOption>CHINAUNIONPAY-SSL</paymentOption>

    <paymentOption>ENVOY_TRANSFER_EUR-BANK</paymentOption>

    <paymentOption>PAYSAFECARD-SSL</paymentOption>

    <paymentOption>IDEAL-SSL</paymentOption>

    <paymentOption>UATP-SSL</paymentOption>

  </reply>

</paymentService>

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.

<paymentOptionsInquiry>

Optional The instruction to find out the available payment methods for the countryCode supplied.

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.
<paymentOption> Optional Returns each available payment method in the country you supplied in your <paymentOptionsInquiry>