Click here to search the entire website

Order notifications

A reliable and accurate way of automatically receiving changes to transaction statuses.

On this page:

Setting up notifications

The Merchant Channels functionality in the MAI allows you to configure which statuses you would like to receive order notifications for, through what channel and in what format.

Statuses reported

Worldpay can send a notification when a payment reaches one of these statuses:

Payment status Description
SENT_FOR_AUTHORISATION

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

AUTHORISED

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

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

An indication that the funds have been received by the acquirer and are being transferred to your bank account.

CHARGED_BACK

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

CHARGEBACK_REVERSED

Additional defence information has reversed a chargeback decision.

INFORMATION_REQUESTED

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

You've sent us defence information for the dispute.

REFUSED

The payment request has been declined by a third party, or by the Risk Management Module (RMM).

ERROR

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

CANCELLED

Either you or the Risk Management Module (RMM) have stopped the transaction.

EXPIRED

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

SENT_FOR_REFUND

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

REFUND_FAILED

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

REFUNDED

Applies to M/S - level service.

An indication that the issuer will process the refund and the shopper will receive it.

REFUNDED_BY_MERCHANT

Applies to C - level (gateway only) service.

An indication that the issuer will process the refund and the shopper will receive it.

Note:  Some payment statuses are not reported through order notifications. To check any possible status for a payment you can consult its payment details in the Merchant Administration Interface (MAI), or send an inquiry request. To learn about the flow of the different payment statuses, see The Payment Process.

When they're reported

Order notifications for the statuses AUTHORISED, CANCELLED (by Risk Management Module) 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. 

Reporting channels

There are two channels (Email, HTTPS) and three formats (text, CGI, XML).

Email (SMTP) notifications

Email order notifications can be sent to one or more valid email addresses that you specify through the MAI. You (or the eventual recipient) do not reply to these messages.

HTTP(S) notifications

HTTP(S) order notifications are sent to a URL on your system that can process the information contained in the message. The URL usually points to a page with script (ASP, PHP, Perl, CGI) that interprets the content of the notification, and sends the interpreted result through to your back-office system.

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

When you receive an HTTP(S) order notification:

  • Confirm receipt with "[OK]" (literally [OK], in capital letters and between square brackets). Any appended characters will be ignored (such as "not [OK]" or "abc[OK]123")

  • Use the HTTP response code 200. Other codes will be interpreted as errors

Warning:  If you do not acknowledge receipt of all notifications with [OK] and a 200 response code, this can quickly cause delays (or loss) of all subsequent notifications in the queue. If you do not want to receive notifications on certain payment statuses, instead use the Merchant Channels functionality in the MAI to deactivate them.

The retry mechanism

If we don't receive an [OK] reply, 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. If acknowledged, or after a week, the retry mechanism stops sending the message and proceeds with the next notification from the queue.

The retry mechanism guarantees the delivery of order notifications for a week; however, it does not provide certainty on the time of delivery.

Order notifications for AUTHORISED, CANCELLED and REFUSED events (for online payment methods) are sent out by the payment server that processed the transaction. Therefore it is possible for you to still receive the above notification types when you have incorrectly acknowledged a previous order notification. The queue can be formed of:

  • Other incorrectly acknowledged order notifications

  • The AUTHORISED, CANCELLED and REFUSED events for offline payment methods

  • All other event types i.e. CAPTURED, since the mechanism responsible for re-sending incorrectly acknowledged notifications also sends these notifications

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

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