Click here to search the entire website

Order notifications

The best way to keep your systems up to date with the latest status of your payments.

Best practice:  To ensure you know the outcome of the payment, notifications are essential for Hosted integrations.

On this page:

Setting up notifications

  1. Log in to the production Merchant Administration Interface (MAI):

    https://secure.worldpay.com/sso/public/auth/login.html?serviceIdentifier=merchantadmin

    Note:  To set up notifications in both test and production environments, you need to log in to the production MAI.

  2. Click INTEGRATION, then select Merchant Channel from the top menu.

  3. In the Merchant Channels (Production and Test) areas:

    1. Activate the http channel and select xml under Content.

    2. Enter the Address to receive test and production notifications.

  4. In the Merchant Channel Events (Production and Test) areas, select the payment statuses you want to receive notifications on.

Statuses reported

Worldpay can send a notification when a payment reaches one of the below statuses.

When they're reported

Order notifications for the statuses AUTHORISED, CANCELLED (post authorisation risk rejection) and REFUSED are sent immediately when a payment has obtained one of these statuses. Order notifications for the other payment statuses are handled by a different mechanism and are typically sent within 15 minutes of being generated. 

Common Statuses

Payment status Description
AUTHORISED

The payment has been approved and the funds reserved in the shopper's account.

CANCELLED

Either you or a Worldpay fraud detection service has stopped the transaction.

CAPTURED The funds reserved against the shopper's account have now been removed, and are travelling to your Worldpay/merchant account.
SETTLED

Applies to M/R/S - level service.

Funds have been received by Worldpay and are being prepared for transfer to your bank account.

SETTLED_BY_MERCHANT

Applies to C - level (gateway only) service.

The gateway has successfully instructed the acquirer to transfer the funds. Your acquirer will confirm the actual settlement.

REFUSED

The payment request has been declined by a third party, or by Worldpay fraud detection services.

SENT_FOR_REFUND

You've requested funds to be sent back to the shopper.

REFUNDED

Applies to M/R/S - level service.

A confirmation that the issuer will process the refund and the shopper will receive it.

REFUNDED_BY_MERCHANT

Applies to C - level (gateway only) service.

The gateway has successfully instructed the acquirer to process the refund. Your acquirer will confirm the actual refund.

Additional Statuses

These are some of the less common statuses.

Note:  We also have some statuses that are specific to Alternative Payment Methods (APMs), explained in the APM guide.

Payment status Description
SENT_FOR_AUTHORISATION

We've requested permission (from the card issuer) to process the shopper's payment.

INFORMATION_REQUESTED

Applies to M/R/S - level service.

A card issuer has requested information about a transaction. The amount of the disputed transaction has been held until the outcome of the dispute.

INFORMATION_SUPPLIED

Applies to M/R/S - level service.

You've sent us defence information for the dispute.

CHARGED_BACK

Applies to M/R/S - level service.

The funds have been returned to the shopper, following the card issuer's decision.

CHARGEBACK_REVERSED

Applies to M/R/S - level service.

Additional defence information has reversed a chargeback decision.

ERROR

The payment wasn't completed. Your shopper may want to reattempt it.

EXPIRED

The authorisation period ended before a capture or cancel request was made.

REFUND_FAILED

The refund couldn't be processed and the funds were returned to your account.

Note:  To learn about the flow of the different payment statuses, see The Payment Process.

Reporting channels

There are two channels (Email and HTTPS). With HTTPS, we only offer the XML format.

HTTPS order notifications are sent to a URL endpoint on your system that can process the information contained in the message.

How to confirm the message is from Worldpay

Order notifications sent to your system may have direct impact on your delivery process, so we advise you to ensure the messages are genuine, such as:

  • Receiving the messages on a secure server

  • Checking the Worldpay client certificate for authenticity

  • Checking the sender's domain name

Secure server (HTTPS)

Using a secure server on your side will enable you to use the Secured HTTP (HTTPS) protocol to receive Worldpay order notifications. Even though the connection is secured, using the HTTPS protocol does not guarantee that it was actually Worldpay who sent the message.

Authenticating the sender

You can validate that the HTTP notifications are originating from Worldpay using one of these methods:

  1. Client certificates - configure your server to ask for a Worldpay TLS (SSL) certificate. We can send our certificate with all communications.

  2. Reverse DNS lookup - the domain is *.worldpay.com. Whilst this can place additional burden on a proxy server or firewall, we recommend this approach rather than using IP addresses. If you use IPs to validate notifications from Worldpay, this could fail when:

    • We change our RIPE IP addresses

    • We amend the Worldwide Payment Gateway RIPE address range

    • We invoke disaster recovery

    We will endeavour to advise you of changes to our IP range(s), but we can't guarantee that this will always happen.

How to acknowledge receipt

Notification acknowledgement

To acknowledge receipt of a notification, you must respond within 30 seconds with the following:

  • HTTP status code 200

  • "[OK]" in the response body

Any non-200 status code will be treated as a failure.

Warning:  If you return a HTTP 200 status and omit "[OK]" from the response body, you must change this to a non-2XX status code (e.g. 400).

How to prevent queuing

To prevent a backlog of notifications, follow these three steps:

  1. Store

  2. Acknowledge

  3. Process

If you store and process the notification before acknowledging receipt, this may cause delays.

The retry mechanism

If a notification is not successfully acknowledged, we initially wait 10 seconds before attempting to deliver the notification again. We'll then place it in a queue and attempt to resend it at increasing intervals of up to 2 hours for a period of 7 days.

Order notifications for online payment methods will continue to be sent for the first AUTHORISED, CANCELLED and REFUSED event per transaction - all other events will be queued.

XML notifications

To interpret XML order notifications it is helpful to understand the payment process.

Note:  For XML notifications, the Content-Type is text/xml; charset=UTF-8.

The notify element

Within the <paymentService> element, the message indicates that it's a notification (<notify>) on a status change of a specific order (<orderStatusEvent>), which in turn contains the orderCode:

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

  <notify>

    <orderStatusEvent orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->

      <!--PAYMENT AND JOURNAL DETAILS GO HERE-->

    </orderStatusEvent>

  </notify>

</paymentService>

Notify element

Payment details

The <payment> element contains the payment details for the order. Included are the:

  • <paymentMethod>

  • Original payment <amount>

  • Last payment status change (<lastEvent>)

  • Current <balance> for the order at the appropriate accountType in our system

This is an example of the payment information for a Mastercard (ECMC-SSL) payment for the amount of EUR 24 that has been AUTHORISED:

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

  <notify>

    <orderStatusEvent orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->

      <payment>

       <paymentMethod>ECMC-SSL</paymentMethod>

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

        <lastEvent>AUTHORISED</lastEvent>       

<AuthorisationId id="622206"/>

        <balance accountType="IN_PROCESS_AUTHORISED">

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

        </balance>

        <cardNumber>5255********2490</cardNumber>

        <riskScore value="0"/>

      </payment>

    </orderStatusEvent>

  </notify>

</paymentService>

Example notification on a Mastercard payment

Note:  It is possible that for certain off-line payment methods a status change has occurred after the event that is reported on, but before the notification is sent. This can also happen when a notification is sent via the retry mechanism. The payment element contains balance information at the time the order notification is sent. Hence, the accounts involved in the last status change are shown here.

Journal details

Once payments reach the AUTHORISED status, they are mapped to journals as they move through our system. These interactions are explained in the payment process.

The <journal> element contains useful information about the payment status and the movement of funds, so it is useful for tracking partial captures and refunds (you can also use the reference attribute in a capture or refund modification for this purpose).

It specifies:

  • The payment status (journalType)

  • The date the status was given (<bookingDate>)

  • The details of corresponding transactions (<accountTx>) between our accounts

Worldpay processes payments in batches, and the batchId indicates the batch in which the transfer has been processed. The debitCreditIndicator indicates whether the transfer is positive ("credit") or negative ("debit").

Example notifications

Example authorised notification

This is an example of an authorisation notification, where the status of the payment changes to AUTHORISED and an amount of EUR 24 is transferred to the account IN_PROCESS_AUTHORISED:

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

  <notify>

    <orderStatusEvent orderCode="Your_order_code">

      <payment>

        <paymentMethod>VISA_CREDIT-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="2400" currencyCode="EUR" exponent="2" debitCreditIndicator="credit"/>

        <lastEvent>AUTHORISED</lastEvent>       

<AuthorisationId id="622206"/>

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

        <cardHolderName>***</cardHolderName>

        <issuerCountryCode>N/A</issuerCountryCode>

        <cardNumber>4444********1111</cardNumber>

        <riskScore value="0"/>

      </payment>

      <journal journalType="AUTHORISED" sent="n">

        <bookingDate>

          <date dayOfMonth="01" month="01" year="2020"/>

        </bookingDate>

        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="30">

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

        </accountTx>

      </journal>

    </orderStatusEvent>

  </notify>

</paymentService>

Example authorisation notification

Note:  For other events, more than one (or even none) <accountTx> may show up within the journal element. An example of an event with no associated <accountTx> transaction is REFUSED.

Other notification examples

Other journal examples

Modification requests