Menu

Direct payment flow

An overview of how an APM flows in the Direct 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. Use the URL in the response to redirect the shopper
  3. Accept the payment and display the result page to the shopper
  4. Confirm the payment and notify the shopper

Direct APM payment flow

1. Send a payment request

For APMs, you send the payment request as covered in theWPG integration guide, but with the addition of the below information.

Specify a set of result URLs (explainedbelow) inside the <paymentDetails> of your request.

There can potentially be five result URLs.

Warning: Not all APMs accept all five URLs. For clarification, see the specific APM in this guide.

Copied!
...
      <paymentDetails>
        <APMCODE-SSL shopperCountryCode="CN">
          <successURL>http://www.worldpay.com/?successURL</successURL> <!--For when the payment is AUTHORISED-->
          <cancelURL>http://www.worldpay.com/?cancelURL</cancelURL> <!--For when the shopper cancels the payment, or times out-->
          <pendingURL>http://www.worldpay.com/?pendingURL</pendingURL> <!--For when AUTHORISED isn't immediately known-->
          <failureURL>http://www.worldpay.com/?failureURL</failureURL> <!--For when the payment is refused-->
          <errorURL>http://www.worldpay.com/?errorURL</errorURL> <!--For when there is an unrecoverable error-->
        </APMCODE-SSL>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>shopper@woalrpday.com</shopperEmailAddress>
      </shopper>
      <statementNarrative>YOUR STATEMENT NARRATIVE</statementNarrative>
    ...

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>

Redirect the shopper to this URL so that they can complete the next steps in the payment process. We then send the payment request to the APM provider for validation.

The below table shows what the URL 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.

Token expiry feature

Prerequisite: You have contacted Worldpay to enable this feature.

If enabled, you'll receive a tokenId in your response URL, which is unique per 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"&gt;
  <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Will contain the merchant code used in the request-->
    <reply>
      <orderStatus orderCode="YOUR ORDER CODE"> <!--Will contain the order code used in the request-->
        <reference id="REFERENCE">https://payments-test.worldpay.com/?tokenId=79b90112-ea0e-4b9a-b20f-394a276a6ac9</reference&gt;
      </orderStatus>
    </reply>
  </paymentService>

The token (and therefore the URL that contains the token) is valid by default for 300 seconds. The token can be consumed only once and subsequent attempts to consume the token will cause an error. So if the shopper is sent the same URL twice, the second attempt produces an error message.

The only exceptions to this are Boleto Bancário and Konbini/Pay-Easy. For Boleto Bancário, the token is valid for 60,000 seconds and for Konbini/Pay-Easy it is valid for 50,000 seconds. For both these exceptions the token can be re-used an infinite number of times within this period.

This functionality is useful because:

  • It enables you the merchant to email the URL to the shopper. This is not possible for other payment methods because the URL expires in five minutes
  • The shopper can click on the URL any number of times, but complete the payment only once. This means that the shopper can follow the shopper journey, but decide to complete the payment later by clicking on the same URL again

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.

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.