Menu

Hosted payment flow

An overview of how an APM flows in the Hosted integration model.

Prerequisite:

  • You have contacted Worldpay to enable the APM(s) you need to integrate.
  • You must useorder notificationsto ensure the order fulfilment status correctly reflects the payment status.

The basic steps are:

  1. Send a payment request
  2. Redirect the shopper to payment URL
  3. Accept the payment and display the result page to the shopper
  4. Confirm the payment and notify the shopper

Hosted APM payment flow

1. Send a payment request

In your payment requests send the <paymentMethodMask> as normal, as covered inPayment Detailsin the WPG integration guide. For some APMs you might need to send additional data in your XML, and this is covered in the specific APM in this guide.

2. Use the URL in the response to redirect the shopper

Our response to your payment request contains a URL, in <reference>:

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">
        <reference id="REFERENCE">https://payments-test.worldpay.com/?tokenId=79b90112-ea0e-4b9a-b20f-394a276a6ac9</reference>
      </orderStatus>
    </reply>
  </paymentService>

The below table shows what it contains in a response where the authorisation is not immediately known:

ComponentsDescription
http://worldpay.com/pendingURLThe pendingURL that you have specified in your XML order request.
tokenId=79b90112-ea0e-4b9a-b20f-394a276a6ac9An optional feature that places an expiry time on the URL. Learn more about this below.
orderKey=ADMINCODE^MERCHANTCODE^OrderCode123The orderKey parameter, including:
  • The admin code, with the limiter (^) appended. This value can be null
  • The merchant code, with the limiter (^) appended
  • The order code specified in the original XML order request
paymentStatus=SHOPPER_REDIRECTEDThe initial status of the payment.
paymentAmount=100The amount of the payment.
paymentCurrency=USDThe currency of the payment.
mac=24dcd933111a50e0f29c32f4d78ad62aTheMAC secret. This value can be null if the MAC secret is not used

Note: The MAC is returned if the payment is in the AUTHORISED, REFUSED, CANCELLED or CAPTURED status.

Append these details to the URL, before redirecting the shopper:

  • The country and language code for the shopper (explained on thePayment page integrationpage of the WPG guide)
  • The success URL, cancel URL, etc. for the transaction

The shopper is then redirected to the Worldpay payment pages to complete the next steps in the payment process.

3. Accept the payment and display the result page to the shopper

When the APM provider receives the payment request and validates the data, it starts the necessary steps to complete the payment. In some cases, the shopper interacts more with the APM provider (such as printing out a voucher from the website and paying at an outlet).

When the payment is complete, the provider confirms the result and initiates the pay-in process to Worldpay. We then return a result URL based on the current status of the payment.

Note:Useorder notifications(and not result URLs) to update order details in your system. This is because in some cases shoppers might complete the payment, but not the entire payment journey. For example, a shopper might close the browser before the successURL is returned.

Result URLs

Note: The maximum number of characters in a result URL is 1024.

Payment STATUS/outcomeParameterDescription/Comments
Cancelled by the shopper or SHOPPER_CANCELLEDcancelURLThe URL to redirect the shopper to if they cancel the payment, or if they time-out during the process.

Note: Some APMs do not provide a Cancel button on their website.

For example:
https://www.example.com/cancel.html
Full-page: append "&cancelURL=http%3A%2F%2Fwww.example.com%2Fcancel.php"
SHOPPER_REDIRECTED
or
SENT_FOR_AUTHORISATION
pendingURLThe URL to redirect the shopper to if the AUTHORISED result isn't immediately known. This is common with APMs that require more time for the shopper to complete the payment (such as post-pay vouchers).

For example: https://www.example.com/pending.html
Full-page: append "&pendingURL=http%3A%2F%2Fwww.example.com%2Fpending.php"

Note: The pendingURL also returns a status, which tells you more about the reason for the pendingURL. You can learn more about thishere.

AUTHORISEDsuccessURLThe URL to redirect the shopper to when the payment is successfully completed.

For example: https://www.example.com/success.html.
Full-page: append "&successURL=http%3A%2F%2Fwww.example.com%2Fsuccess.asp"
REFUSEDfailureURLThe URL to redirect the shopper to if the payment is refused.

For example: https://www.example.com/failure.html
Full-page: append "&failureURL=http%3A%2F%2Fwww.example.com%2Ffailure.php"
ERRORerrorURLThe URL to redirect the shopper when there is an unrecoverable error during payment processing.

For example: https//www.example.com/error.html
Full-page: append "&errorURL=http%3A%2F%2Fwww.example.com%2Ferror.php"

4. Confirm the payment and notify the shopper

When Worldpay receives pay-in notification from the APM provider, we send you an AUTHORISED notification. The time it takes for this to happen depends on the APM, and can be almost immediately, or several days.