Menu

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 toreference 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 has been sent.

To determine the real-time status of transactions, useorder 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 theDirect payment requestsorHosted payment requestspages, the <paymentService> root element must contain the child <inquiry>, which in turn must contain the <orderInquiry> about the relevant orderCode:

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"> <!--Enter your own merchant code-->
  <inquiry>
    <orderInquiry orderCode="YOUR_ORDER_CODE"/> <!--Enter the relevant order code-->
  </inquiry>
</paymentService>

Visa OCT inquiry

Visa OCT inquiries contain the element <OCTTxnId>. Note that this differs from Visa OCTnotificationswhich contain the element <OCTTxnID>.

Our response

When we receive a valid order inquiry from you, we respond with a message containing the payment status for the order:

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 inquiry-->
  <reply>
    <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the inquiry-->
      <payment>
        <!--RESPONSE INFORMATION GOES HERE-->
      </payment>
    </orderStatus>
  </reply>
</paymentService>

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 seeThe payment process.

Other response examples

Refundable amount inquiry

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

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

Refundable amount inquiry response

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

Payment options inquiry

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

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

Copied!
<?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>
    <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>AIRPLUS-SSL</paymentOption>
  </reply>
</paymentService>

XML reference

Inquiry elements

Elements/attributesM/ODescription
<inquiry>OptionalThe instruction to request information.
<batchInquiry>OptionalThe instruction to request the status of the particular batch (denoted by the merchantBatchCode).
<refundableAmountInquiry>
orderCode
OptionalThe instruction to find out the available refundable balance of this transaction.
<paymentOptionsInquiry>OptionalThe instruction to find out the available payment methods for the countryCode supplied.

Response elements

Elements/attributesM/ODescription
<thirdPartyReference>OptionalReturned 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>OptionalReturns details of the available refundable balance of a transaction.
<ISO8583ReturnCode>OptionalReturns the refusal response code from the issuer and a mapped description (reason) from Worldpay. For a list of response codes and their descriptions, seeAuthorisation response codes.
<paymentOption>OptionalReturns each available payment method in the country you supplied in your <paymentOptionsInquiry>.