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>

Our response

When we have received 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

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>
        <paymentMethod>VISA-SSL</paymentMethod>
        <paymentMethodDetail> <!--Not returned by default - contact us to enable-->
          <card number="444433******1111" type="creditcard">
            <expiryDate> <!--Not returned by default - contact us to enable-->
              <date month="01" year="2020"/>
            </expiryDate>
          </card>
        </paymentMethodDetail>
        <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <AuthorisationId id="622206"/>
        <CVCResultCode description="A"/>
        <AVSResultCode description="A"/>
        <AAVAddressResultCode description="A"/>
        <AAVPostcodeResultCode description="A"/>
        <AAVCardholderNameResultCode description="A"/>
        <AAVTelephoneResultCode description="A"/>
        <AAVEmailResultCode description="A"/>
        <ThreeDSecureResult description="Cardholder authenticated">
          <eci>05</eci> <!--Not returned by default - contact us to enable-->
          <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <!--Not returned by default - contact us to enable-->
        </ThreeDSecureResult>      
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <cardNumber>4444********1111</cardNumber>
        <riskScore value="0"/>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Note: In the above example the payment element contains the optional child elements: <AuthorisationID>, the various AVS/CVC/AAV and ThreeDSecure result codes, and <riskScore>. To add these parameters, contact your Relationship Manager.

This shows a referred Mastercard (ECMC) payment with payment status REFUSED:

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>
        <paymentMethod>ECMC-SSL</paymentMethod>
        <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>REFUSED</lastEvent>
        <ISO8583ReturnCode code="2" description="REFERRED"/>
        <CVCResultCode description="C"/>
        <AVSResultCode description="E"/>
        <AAVAddressResultCode description="B"/>
        <AAVPostcodeResultCode description="B"/>
        <AAVCardholderNameResultCode description="B"/>
        <AAVTelephoneResultCode description="B"/>
        <AAVEmailResultCode description="B"/>
        <ThreeDSecureResult description="Authentication offered but not used">
      </payment>
    </orderStatus>
  </reply>
</paymentService>

This shows a refused MAESTRO payment where the card has been blocked:

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>
        <paymentMethod>MAESTRO-SSL</paymentMethod>
        <amount value="2750" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>REFUSED</lastEvent>
        <ISO8583ReturnCode code="76" description="CARD BLOCKED"/>
        <CVCResultCode description="C"/>
        <AVSResultCode description="E"/>
        <AAVAddressResultCode description="B"/>
        <AAVPostcodeResultCode description="B"/>
        <AAVCardholderNameResultCode description="B"/>
        <AAVTelephoneResultCode description="B"/>
        <AAVEmailResultCode description="B"/>
        <ThreeDSecureResult description="Authentication offered but not used"/>
      </payment>
    </OrderStatus>
  </reply>
</paymentService>

Note: For refused transactions no further processing takes place and consequently no balance information is presented. The <ISO8583ReturnCode> shows 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.

This shows a cancelled VISA payment:

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>
    <orderStatusEvent orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->
      <payment>
       <paymentMethod>VISA-SSL</paymentMethod>
          <amount value="1000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>CANCELLED</lastEvent>
        <CVCResultCode description="C"/>
        <AVSResultCode description="E"/>
        <AAVAddressResultCode description="B"/>
        <AAVPostcodeResultCode description="B"/>
        <AAVCardholderNameResultCode description="B"/>
        <AAVTelephoneResultCode description="B"/>
        <AAVEmailResultCode description="B"/>
        <ThreeDSecureResult description="Cardholder authenticated">
          <eci>05</eci> <!--Not returned by default - contact us to enable-->
          <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <!--Not returned by default - contact us to enable-->
        </ThreeDSecureResult>
        <cardNumber>5255********2490</cardNumber>
        <riskScore value="0"/>
      </payment>
      <journal journalType="CANCELLED" sent="n">
        <bookingDate>
          <date dayOfMonth="01" month="01 year="2020"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="30">
          <amount value="1000" currencyCode="EUR" exponent="2" debitCreditIndicator="debit"/>
      </journal>
    </orderStatusEvent>
  </reply>
</paymentService>

This shows a captured American Express payment:

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>
        <paymentMethod>AMEX-SSL</paymentMethod>
        <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>CAPTURED</lastEvent>
        <reference>YourReference</reference> <!--Returned if added to capture modifications-->
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

In this American Express (AMEX) example EUR 40 has been captured of the initial authorised amount of EUR 41. The remaining amount of EUR 1 is displayed in the balance information of the account type IN_PROCESS_AUTHORISED:

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>
        <paymentMethod>AMEX-SSL</paymentMethod>
        <amount value="4100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>CAPTURED</lastEvent>
        <reference>YourReference</reference> <!--Returned if added to capture modifications-->
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="4000" currencyCode=" EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

This order inquiry into a settled American Express (AMEX) payment results in a reply that contains balance information on the account types SETTLED_BIBIT_COMMISSION and SETTLED_BIBIT_NET. These show the commission amount withheld from the initial payment amount, and the amount settled:

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>
        <paymentMethod>AMEX-SSL</paymentMethod>
        <amount value="4000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>SETTLED</lastEvent>
        <reference>YourReference</reference> <!--Returned if added to capture modifications-->
        <balance accountType="SETTLED_BIBIT_COMMISSION">
          <amount value="23" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="3977" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Note: Depending on your service level, you may instead receive a SETTLED_BY_MERCHANT <lastEvent> here. To understand service levels, seeThe payment process.

This is an example of a payment for which a partial refund of EUR 215 has been requested:

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>
        <paymentMethod>CARTEBLEUE-SSL</paymentMethod>
        <amount value="28301" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>SENT_FOR_REFUND</lastEvent>
        <reference>YourReference</reference> <!--Returned if added to refund modifications-->
        <CVCResultCode description="NOT SUPPLIED BY SHOPPER"/>
        <balance accountType="SETTLED_BIBIT_COMMISSION">
          <amount value="184" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="28117" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="21500" currencyCode="EUR" exponent="2" debitCreditIndicator="debit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

An amount of EUR 281.17 has been transferred to the account type SETTLED_BIBIT_NET. This is the amount of the initial order amount minus the commission amount of EUR 1.84. Note that the amount to be refunded is debited from the account type IN_PROCESS_CAPTURED.

If the initial payment is captured but not yet settled the above payment element will only show balance information of the IN_PROCESS_CAPTURED account type.

As shown in the balance information an amount of EUR 215 has been debited from the account type IN_PROCESS_CAPTURED.

This is an example of a payment where a refund of EUR 215 has been requested after the payment was settled:

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>
        <paymentMethod>ECMC-SSL</paymentMethod>
        <amount value="21500" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>REFUNDED</lastEvent>
        <reference>YourReference</reference> <!--Returned if added to refund modifications-->
        <thirdPartyReference>35425156083060117338001</thirdPartyReference> <!--Useful for tracking delayed refunds from an issuer-->
      </payment>
    </orderStatus>
  </reply>
</paymentService>

Note: Depending on your service level, you may instead receive a REFUNDED_BY_MERCHANT <lastEvent> here. To understand service levels, seeThe payment process.

This is an example of a failed refund:

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">
  <reply>
    <orderStatus orderCode="YOUR_ORDER_CODE">
      <payment>
        <paymentMethod>VISA_CREDIT-SSL</paymentMethod>
        <amount value="100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>REFUND_FAILED</lastEvent>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="100" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
      </payment>
      <date dayOfMonth="10" month="06" year="2020" hour="8" minute="35" second="0"/>
    </orderStatus>
  </reply>
</paymentService>

Note: You may not receive the <balance> attributes for all unsuccessful refunds. This element is not populated for all refund failures.

The reply message for a charged back Maestro payment reports on the balance of the account types SETTLED_BIBIT_NET and SETTLED_BIBIT_COMMISSION. Note that the charged back amount is debited from the SETTLED_BIBIT_NET account:

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>
        <paymentMethod>MAESTRO-SSL</paymentMethod>
        <amount value="1200" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>CHARGED_BACK</lastEvent>
        <balance accountType="SETTLED_BIBIT_COMMISSION">
          <amount value="48" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="1248" currencyCode="EUR" exponent="2" debitCreditIndicator="debit"/>
        </balance>
      </payment>
    </orderStatus>
  </reply>
</paymentService>

The reply message below is an example where either:

  • No payment was found for the order (the order has not reached a payment status yet)
  • No order with the orderCode used (for that merchantCode) was found in the system
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-->
      <error code="5"><![CDATA [Could not find payment for order]]></error>
      <date dayOfMonth="01" month="01" year="2020" hour="01" Minute="01" second="01"/>
    </orderStatus>
  </reply>
</paymentService>

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>.