Menu

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

Merchant Channels page

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 statusDescription
AUTHORISEDThe payment has been approved and the funds reserved in the shopper's account.
CANCELLEDEither you or a Worldpay fraud detection service has stopped the transaction.
CAPTUREDThe funds reserved against the shopper's account have now been removed, and are travelling to your Worldpay/merchant account.
SETTLEDApplies toM/R/S - levelservice.
Funds have been received by Worldpay and are being prepared for transfer to your bank account.
SETTLED_BY_MERCHANTApplies toC - level(gateway only) service.
The gateway has successfully instructed the acquirer to transfer the funds. Your acquirer will confirm the actual settlement.
REFUSEDThe payment request has been declined by a third party, or by a Worldpay fraud detection service.
SENT_FOR_REFUNDYou've requested funds to be sent back to the shopper. If the refund required online authorisation, then this indicates that the refund was successfully authorised by the card issuer.
REFUNDEDApplies toM/R/S - levelservice.
A confirmation that the issuer will process the refund and the shopper will receive it.
REFUNDED_BY_MERCHANTApplies toC - 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 theAPM guidance.

Payment statusDescription
SENT_FOR_AUTHORISATIONWe've requested permission (from the card issuer) to process the shopper's payment.
INFORMATION_REQUESTEDApplies toM/R/S - levelservice.
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_SUPPLIEDApplies toM/R/S - levelservice.
You've sent us defence information for the dispute.
CHARGED_BACKApplies toM/R/S - levelservice.
The funds have been returned to the shopper, following the card issuer's decision.
CHARGEBACK_REVERSEDApplies toM/R/S - levelservice.
Additional defence information has reversed a chargeback decision.
ERRORThe payment wasn't completed. Your shopper may want to reattempt it.
EXPIREDThe authorisation period ended before a capture or cancel request was made.
REFUND_FAILEDThe refund couldn't be processed and the funds were returned to your account.
If online authorisation was required, this status indicates that the refund was refused by the card issuer. You should refer to the description for the reason that the refund was unsuccessful.

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

Reporting channels

There are two channels (Email, 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 other response will be treated as a failure.

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

How to prevent queuing

To reduce the risk of timeouts and queuing, follow these three steps:

  1. Store
  2. Acknowledge
  3. Process

The retry mechanism

If a notification is not successfully acknowledged, we will place it in a retry queue. We will attempt to resend the notification with increasing time intervals from 10 seconds to 2 hours until it is acknowledged. If it is not successfully ackowledged after 7 days it will be removed from the queue.

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

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">
  <notify>
    <orderStatusEvent orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->
      <!--PAYMENT AND JOURNAL DETAILS GO HERE-->
    </orderStatusEvent>
  </notify>
</paymentService>

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:

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

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 inthe 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 refundmodificationfor 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 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:

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

Note: Depending on the event type, zero or multiplewill be returned within the journal element. REFUSED, and some REFUND_FAILED events will not have anyin the notification response.

Other notification examples

Other journal examples