WorldPay Sandbox User Guide

Transcription

Sandbox User Guide
Version 2.3 – May 2013
Corporate Gateway
Table of Contents
About This Guide ....................................................................................................................... 1
Version 2.3 ............................................................................................................................. 1
Version 2.2 ............................................................................................................................. 2
Audience ................................................................................................................................ 3
Copyright................................................................................................................................ 3
Printing This Guide .................................................................................................................... 4
Sandbox Overview .................................................................................................................... 5
What Is Sandbox?.................................................................................................................. 5
Differences Between Sandbox and Production ..................................................................... 5
Planning Your Testing ............................................................................................................... 7
What Should I Test? .............................................................................................................. 7
Restrictions ............................................................................................................................ 8
Accessing Sandbox ................................................................................................................. 10
Test Merchant Interface ....................................................................................................... 10
Card Payment Methods........................................................................................................... 11
Creating a Payment ............................................................................................................. 11
Authorising or Refusing a Payment ..................................................................................... 16
Capturing or Cancelling a Payment ..................................................................................... 16
Settling a Payment............................................................................................................... 18
Refunding a Payment .......................................................................................................... 18
Alternative Payment Methods (APMs)..................................................................................... 20
About Testing APMs ............................................................................................................ 20
Supported APMs.................................................................................................................. 22
About Submitting APM Test Orders..................................................................................... 24
Submitting APM Test Orders - Direct Integration ................................................................ 36
Submitting APM Test Orders - Redirect Integration ............................................................ 52
Authorising APM Test Payments (Direct and Redirect)....................................................... 85
Capturing APM Test Payments (Direct and Redirect) ......................................................... 86
Settling APM Test Payments (Direct and Redirect)............................................................. 87
ii
Table of Contents
Refunding APM Test Payments........................................................................................... 88
Testing Your Integration .......................................................................................................... 99
Interaction ............................................................................................................................ 99
Shopper Experience ............................................................................................................ 99
Products ............................................................................................................................. 100
Appendix................................................................................................................................ 101
Test Card Numbers............................................................................................................ 101
Sandbox APM Features at a Glance ................................................................................. 103
iii
iv
About This Guide
This guide explains how to use the Sandbox, WorldPay's secure-test environment.
Version 2.3
Release date: May 2013
Change description: More alternative payment methods (APMs) added. Bank transfer
refund behaviour and bank account inquiry sections added. Information about American
Express SafeKey, China Union Pay refunds and other refunds added.
Book > Topic(s)
Section(s)
Change(s)
Appendix >
Sandbox APM
Features at a Glance
Table
New columns and new APMs
(rows).
Submitting APM Test Orders Direct Integration > Delayed
Testing Multibanco
Payments
New section.
Testing Multibanco
Payments
New section.
New Topic EPS
(Redirect)
All new content.
About Retrieving a List
of Banks
New content.
Bank Transfer Refund
scenarios, Sandbox
Features for Testing
Bank Transfer Refunds
New content, including diagrams.
Testing Refunds of
China Union Pay
Information about the refund failed
feature added.
Supported APMs
Boleto and Kiwi added.
Non-Hybrid APMs (Direct)
Submitting APM Test Orders Redirect Integration >
Delayed Non-Hybrid APMs
(Redirect)
Submitting APM Test Orders Redirect Integration > EPS
(Redirect)
Submitting APM Test Orders Direct Integration > Fast
Bank Transfers (Direct)
Refunding APM Test
Payments > Bank Transfer
Refunds
Refunding APM Test
Payments > Automatic
Refunds
Submitting APM Test Orders Redirect Integration >
section
Delayed Hybrid APMs
(Redirect)
About Submitting APM Test
Orders > Intermediate Data
Intermediate Data
Collection Pages
New topic.
1
Book > Topic(s)
Section(s)
Change(s)
Bulk Capture section
New section.
Amex Safekey section.
New content.
Collection Pages
Alternative Payment Methods >
Capturing APM Test
Payments (Direct and
Redirect)
Creating a Payment > Testing
3D Secure Authentication
Version 2.2
Release date: February 2013
Change description: More alternative payment methods (APMs) and payments statuses
added. Support for testing refunds of APM payments added.
Chapter > Section(s)
Change(s)
Supported APMs
Added Boleto, eNETS and Konbini alternative
payment methods.
About Submitting APM Test Orders > Payment
Added more payment statuses.
Statuses
About Submitting APM Test Orders > Best
Added more order notifications.
Practice Guidelines
Submitting APM Test Orders - Direct Integration >
Added improved payment reference.
Fast Bank Transfers (Direct)
Submitting APM Test Orders - Redirect Integration >
Added improved payment reference.
Fast Bank Transfers (Redirect)
Submitting APM Test Orders - Redirect Integration >
New.
eNETS (Redirect)
2
Authorising APM Test Payments (Direct
and Redirect)
New.
Capturing APM Test Payments (Direct and
Redirect)
New.
Settling APM Test Payments (Direct and
Redirect)
New.
Refunding APM Test Payments
New.
About This Guide
Chapter > Section(s)
Appendix > Sandbox
Change(s)
APM Features at a
New.
Glance
Audience
This guide is intended for merchants and developers who want to test the integration of their
in-house ordering systems with the WorldPay Corporate Gateway. It applies to merchants
who are using WorldPay's direct or redirect integration model.
It is recommended that you are familiar with the requirements for submitting XML orders, as
described in one or more of the following WorldPay guides:
For the direct integration model, refer to the Submitting Transactions in the XML
Direct Model Guide.
For the redirect integration model, refer to the Hosted Payment Page (XML Redirect)
Guide.
For integration of alternative payment methods (APMs) using either the direct or
redirect integration model, refer to the Alternative Payment Methods Guide.
Information about refunding APMs can be found in the Refunding Alternative
Payments Guide.
You should also have an understanding of the payment life cycle and the payment statuses
that make up the life cycle. For more information, refer to the Payment Status Definitions
Guide.
An understanding of the basic functions of the Merchant Interface is recommended. For more
information, refer to the Merchant Interface Guide.
Copyright
© WorldPay (UK) Limited
While every effort has been made to ensure the accuracy of the information contained in this
publication, the information is supplied without representation or warranty of any kind, is
subject to change without notice and does not represent a commitment on the part of
WorldPay (UK) Limited. WorldPay (UK) Limited, therefore, assumes no responsibility and
shall have no liability, consequential or otherwise, of any kind arising from this material or any
part thereof, or any supplementary materials subsequently issued by WorldPay (UK) Limited.
WorldPay (UK) Limited has made every effort to ensure the accuracy of this material.
3
Printing This Guide
You can download a printed version of this guide, in Adobe’s Portable Document Format
(PDF), from our Guides page at the following URL:
http://www.worldpay.com/support/guides
4
Sandbox Overview
What Is Sandbox?
Sandbox provides a comprehensive secure-test environment where you can test your
technical integration with WorldPay. Sandbox supports the testing of both card payments and
alternative payment methods. You can submit orders and test the payment life cycle — from
initial order submission through to the SETTLED state. Sandbox simulates a production
experience but in a shielded secure-test environment.
Sandbox features can help you with your testing:
Simulators
You can use simulators to specify payment parameters such as the payment
outcome or CVC response. Simulators help you to test the shopper payment flow,
including handovers between your system and the WorldPay payment service.
Magic values
Magic values represent individual payment parameters that you can specify directly
in an XML order. When you use one or more magic values, you can bypass
simulators and speed up your testing process.
Differences Between Sandbox and Production
There are some differences between how payments are processed in Sandbox and how they
are processed in the production environment. In addition, there are differences between how
card payments and alternative payment methods work in Sandbox.
Ensure that you only send test orders to Sandbox. Do not send live orders to
Sandbox. Do not point your live website or shoppers to Sandbox.
Money
No real money is involved in Sandbox. This means that you do not need any real payment
details, such as credit cards. For a list of test card numbers, see Test Card Numbers.
To avoid a compromise of shopper data, it is recommended that you use
dummy shopper data when testing transactions in Sandbox.
5
Risk Management
When you submit payments to test your integration you will be acting as your own customer.
As a result, fraud screening products, such as the Risk Management Module (RMM), will flag
the fact that ‘a shopper’ (that is, yourself) is submitting an unusual pattern of payments. This
could also block any subsequent payments. To prevent this from happening, check your
fraud screening settings with WorldPay and those for other products you might use to screen
payments against online fraud.
Payment Methods
In the production environment, the payment methods available can be tailored to support
your business model. They depend on a number of factors, including the payment methods
you require, your pricing and your acquirer. In Sandbox, you have the option to test all
payment methods at a standardised pricing, irrespective of your production setup. If you have
questions on how your individual production setup varies from your test setup, contact your
relationship manager for advice.
WorldPay offers a wide range of payment options for your shoppers. In Sandbox, more
alternative payment methods will become available for testing in upcoming releases.
Aspects of timing, the payment cycle and reporting differ between Sandbox and the
production environment. In addition, the way payments are handled in Sandbox may vary
between card payment methods and alternative payment methods.
Reports
Reports are handled as follows in Sandbox:
Card payments
For card payments, not all reports are available in Sandbox. Some reports that are
available will not offer the same content you can expect in production; they will return
empty or ‘dummy’ content instead. For more information about the availability or
content of reports in Sandbox, contact your relationship manager.
Alternative payment methods
For alternative payment methods, reporting is currently not available. It is planned for
a future release.
6
Planning Your Testing
What Should I Test?
Integration
Your integration is the core of your interaction with WorldPay. A number of integration
methods—some of which can be combined with each other—are available to you in the
production environment and in Sandbox. We suggest that you identify the possible
combinations you will support for your customers and then test those combinations in
Sandbox.
For more information on integration with WorldPay's Corporate Gateway, see one of the
following guides:
For information on the direct integration model, refer to Submitting Transactions in
the XML Direct Model Guide.
For information on the redirect integration model, Hosted Payment Page (XML
Redirect) Guide.
Consider the following characteristics that are possible in an integration with WorldPay:
Integration language
Communication between your system and the WorldPay Payment Service is realised
through predefined XML messages over the Internet.
Submission method
Single payment, batch processing, XML order modification.
Payment pages
Standard, customised, mobile devices, single currency, multi-currencies.
Shopper interaction
ecommerce, recurring, mail order/telephone order (MOTO), mobile devices.
Authentication (3D Secure) on card payments
With 3D Secure, without 3D Secure.
Payment methods
Card, alternative payment methods, shopper languages, character set and special
characters.
7
Configuration
Your configuration is complex and tailored to your needs. This includes any user logins and
their associated permissions, the products available, your merchant code setup, contact
details and customisation of any products. You can amend your configuration by using the
Merchant Interface (MI). Ensure that you familiarise yourself with the various configuration
options available in Sandbox and in the production environment.
The only settings change that can be made from Sandbox is the XML
password for the Sandbox test environment. You must configure all other
settings in production which will then be copied across to Sandbox within a
period of 15 minutes.
Risk and Fraud Management
WorldPay has a number of products available to help you reduce risk of fraud on your
website. In addition to our products, you might also have your own processes in place and we
recommend that you test your risk management setup in Sandbox. For more information on
risk and fraud, see Introduction to Fraud.
Payment Life Cycle
We suggest you submit test payments and follow their life cycle from when a shopper arrives
on your website, to submitting a shopper payment to WorldPay, through to when WorldPay
receives those funds from your customer.
You can test the reconciliation of your WorldPay payments. You can view all test orders you
have submitted to WorldPay and their payments from within the test Merchant Interface (MI).
If configured, you can also receive notifications about your payments and about updates to
them. Reports are available for card payments. They will be available for alternative payment
methods in a future release.
Reconciliation
For test payments, Sandbox lets you test the reconciliation of your WorldPay payments. You
can view all orders you have submitted to WorldPay and their payments from within the
Merchant Interface (MI). You will also receive reports (card payments only) and notifications
for your test payments and updates of them.
Restrictions
Stress Testing
Sandbox supports a transaction rate of 1 transaction per second (1 TPS).
If you are using batch processing, we recommend including no more than 100 payments per
batch.
8
Planning Your Testing
Chargebacks
A chargeback involves the return of shopper funds.
For card payments, the return of funds is initiated and enforced by the card issuer.
Some card issuers will allow you to defend a chargeback claim.
For some alternative payment methods, the shopper can request the reversal of the
payment transaction by the payment service provider.
Sandbox provides the following chargeback functionality:
For card payments, when a transaction is in dispute, and where supported by card
issuers, you can use the Merchant Interface (MI) to upload supporting information in
an effort to prevent the chargeback. This feature is available on the Dispute
Management (Test) page.
For alternative payment methods (APMs), chargeback functionality is currently not
available in Sandbox
Transfers
In the production environment, after the payment cycle has completed and all funds are
settled by WorldPay (or your acquirer), funds will be transferred to you. This bank transfer
cannot be simulated in Sandbox.
Billing and Invoicing
The billing applied to payments in Sandbox is based on standardised charges and will not
reflect the exact charges of your individual agreement with WorldPay. There are
subsequently no monthly invoices produced in Sandbox.
9
Accessing Sandbox
The URL for Sandbox is:
https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
As part of testing, you can send the following to this URL:
XML orders
XML order modifications
XML order enquiries
There is no change in the format of XML orders, modifications and enquiries
that you submit to Sandbox. The XML format used for Sandbox is the same
as that for the production environment.
Test Merchant Interface
As a complement to the Sandbox environment, a test version of the Merchant Interface (MI)
is also available. You can use the test version of the Merchant Interface to view the status of
test payments and to push payments through the payment cycle at an accelerated pace. Only
payments created in Sandbox are viewable in the test MI.
The URL for the test merchant interface is:
http://www.worldpay.com/support/gg/index.php?page=newlogin&c=WW
To log in to the test MI
Log in to test Merchant Interface using the following:
Username – Your merchant code in capital letters.
Password – Your XML password.
You can set up different XML passwords for the test and production
environments. Do this in the test Merchant Interface.
There are two ways to tell that you are viewing the test version of the MI:
The test version is displayed with a yellow background and contains a TEST
watermark.
The heading for every section is followed by (Test). For example, the heading for the
page that shows order information is Orders (Test).
10
Card Payment Methods
Creating a Payment
Overview: Creating a Payment
SENT_FOR_AUTHORISATION refers to the initial payment status of a new payment. It
means that you have asked WorldPay to process a payment and we have passed the
payment details on for authorisation.
CURRENCIES
Some payment methods will only support certain currencies. If you are using WorldPay’s
hosted payment pages, then WorldPay will convert those payments into an accepted
currency. Note that Sandbox allows you to test a large number of currencies, which might
include different currency combinations to your production setup. Please contact your
relationship manager if you would like to discuss your payment methods and/or currencies
you offer your customers.
Submitting an Order
You can submit a unique order for processing to WorldPay. Payment details are also required
to create a corresponding payment for this order. Those payment details are either obtained
by WorldPay if you redirect your customers to WorldPay’s hosted payment pages, or by
yourself if you collect those details on your website directly.
For non-card payment methods your customer might be re-directed to another payment
scheme, and most offline payment methods will not require any capture of shopper details.
Test Values
Standard Values
The following default values will be applied to a card payment:
AUTHENTICATION (3D SECURE)
MasterCard Secure Code / Verified by Visa will not be applied to your payments by
default. The payment will have no 3D response at all.
PAYMENT RESULT
The default payment outcome for any card payment will AUTHORISED.
CVC
The Card Verification Code (CVC) also known as Card Security Code will be
returned as APPROVED.
AVS
The Address Verification System (AVS) compares the billing address provided by
your customer with the billing address the card issuer holds on file. The default
response for a card payment will be APPROVED.
11
Magic Values
You can pre-define payment results that differ from the default values applied to card
payments. This is achieved through the use of certain values (‘magic values’) you submit with
a payment. Magic values are a quick way to specify a desired outcome, such as a specific 3D
Secure response. Magic values work for test payments in Sandbox only and will be ignored
for real payments in the production environment. For a full list of magic values, refer to the
Sandbox Magic Values Spreadsheet.
Magic values are not case sensitive You can apply magic values in the following scenarios:
AUTHENTICATION (3D SECURE)
The cardholder name can be used to determine the 3D Secure response. For
example, a cardholder name of ‘Identified’ will return an ‘Identified’ authentication
response. This will only be applied in participating card schemes, such as
MasterCard or Visa.
PAYMENT RESULT
The cardholder name can be used to define the payment result, for example
‘Refused’ will cause your test payment to be refused. If WorldPay acts as your
acquirer, then you might be enabled for extended reason codes in the production
environment. This can be simulated in Sandbox by adding the corresponding reason
code, for example ‘Refused34’.
AUTHENTICATION + PAYMENT RESULT
If a magic value is needed for both payment result and authentication response, then
those two magic values can be added together if they are connected via a full stop [.].
For example Identified.Refused34
CVC
Magic values can be supplied in the security code / CVC field.
AVS
Magic values can be supplied in the address field.
Using Simulators
You can pre-define payment results through the use of payment simulators. There are two
different simulator pages available for card payments:
3D Simulator
This simulator enables you to select the authentication response returned from a card issuer.
This simulator page will only appear if you enter the magic value ‘3D’ for a qualifying card.
Acquirer Simulator
This simulator enables you to select the payment outcome, CVC response and AVS
response of a qualifying payment. It appears as a default. However, you can override it and
prevent it from being displayed by providing a magic value for the payment outcome in the
cardholder name.
12
Testing 3D Secure Authentication
3D Secure provides additional level of security protection to merchants. It is offered under
three trade names:
Trade Name
Scheme or Company Name
MasterCard Secure
Code
MasterCard
SafeKey
American Express (AMEX)
Verified by Visa
Visa
Overview
3D Secure uses an XML protocol to provide an authentication procedure for online payments.
In Sandbox, many of the steps in the flow are automated and virtual; there is no separate
shopper, issuer or acquirer. The test procedure concerns the XML messages passed
between various parties.
Testing 3D Secure Orders
Before you start testing, ensure that your WorldPay account is enabled for 3D Secure. The
WorldPay Support group is responsible for the 3D Secure installation. WorldPay Support also
provide a dummy card issuer site so that this part of the process can also be tested.
The value of the cardHolderName element in the XML order message controls the
operation of the test, as follows:
cardHolderName
Value
3D
Test Environment Behaviour
The payment card participates in the 3D Secure scheme. The simulator
starts; use it to select further options.
For Verified by Visa and MasterCard Secure Code: The Shopper does not
participate in the 3D Secure scheme, even though the scheme is offered. The
Simulator does not start and the result in the Customer Interaction field is
Authentication offered but not used.
NO3D
For AMEX SafeKey only: A shopper has an American Express card with 3D,
but the shopper is attempting to make a payment in a country that does not
support American Express 3D Secure.
The Simulator does not start and the result in the customer interaction field
is ECommerce. For more information, see the Testing American
Express Safekey.
3DVEERROR
The payment card participates in the 3D Secure scheme. The simulator starts
and simulates a system/connectivity issue that occurs before the cardholder
is asked to authenticate. The 3D Secure result is Authentication
Unavailable.
Any other value
A normal ecommerce transaction with no 3D Secure initiated.
13
You can use the value of the paResponse element to manipulate the outcome of the payer
authentication. Use the dummy issuer site to select the following options from the drop-down
list:
paResponse Value
Meaning
IDENTIFIED
Cardholder Authenticated
NOT_IDENTIFIED
Authentication Offered but not used
UNKNOWN_IDENTITY
Cardholder Failed Authentication. The order does not proceed to
authorisation.
CANCELLED_BY_SHOPPER
Cardholder Failed Authentication. The order does not proceed to
authorisation.
ERROR
Response failed validation checks. The order does not proceed to
authorisation.
ERROR
3D
Secure_VALID_ERROR_CODE
Authentication Unavailable. The error code is valid. It is acceptable
to proceed to authorisation.
ERROR
3D
Secure_INVALID_ERROR_CO
DE
Response failed validation checks. The order does not proceed to
authorisation.
In the production environment, the length of the paResponse element can be up
to 4.7KB. However, in the test environment you must use considerably shorter
lengths such as those in the table above, otherwise a parse error occurs.
Testing American Express Safekey
American Express participates in the 3D Secure protocol under the name of Safekey. You
can test it in the same way as testing MasterCard Secure Code and Verified by Visa.
However there is an exception, due to the fact that some countries that offer American
Express do not participate in the 3D Secure scheme.
An example might be a cardholder with an American Express card from a country with
Safekey who attempts to buy goods and services from a merchant in a country without
American Express Safekey. In this case the cardholder's American Express account is set up
for 3D Secure, but the American Express scheme in the merchant's country cannot interact
with 3D Secure.
To test this scenario, use an AMEX test card number, and enter NO3D as the cardHolder
name in the XML script. This can be done in the simulator. The result is the word
ECommerce in the customer interaction field (see below):
14
Results of a no 3D verification scenario for American Express
A Verified by Visa or MasterCard Secure Code test of NO3D produces a similar screen, but
with Authentication offered but not used in the customer interaction field:
Results of a no 3D verification scenario for VISA
A test with MasterCard Secure Code produces the same result as for Visa.
15
Verifying Your Results
Once you have submitted your first order, check if you have received the relevant
notifications. You can view and amend your notifications setup in the Merchant Interface (MI).
You can also use the MI to view the order you have submitted and the payment(s) linked to it.
We recommend that you familiarise yourself with the MI and how to locate payments. We
suggest you also verify that your own systems have reacted as expected to the transaction
you have submitted to WorldPay.
Authorising or Refusing a Payment
Overview: Authorising or Refusing a Payment
A payment may be refused by the card issuer of your customer. In this case, a payment
event of REFUSED is added to the payment history of the SENT_FOR_AUTHORISATION
payment. The payment status of REFUSED is final.
Alternatively, the payment may be AUTHORISED which means that the card issuer of your
customer confirmed that funds are available and reserved for you. A payment event of
AUTHORISED is added to the payment history of the SENT_FOR_AUTHORISATION
payment.
Risk Management
If you are using the Risk Management Module (RMM), then payments may also be refused
based on the risk score of the payment, even if all other parameters would otherwise allow
the payment to be authorised. You can view the risk score of a payment and the RMM
settings online when you login to the Merchant Interface (MI).
Multi-Currency
Both an AUTHORISED and a REFUSED amount will always be in the same currency as the
SENT_FOR_AUTHORISATION amount.
Please check if you have received the relevant notifications. You can view and amend your
notifications setup in the Merchant Administration Interface (MAI). You can also use the MAI
to view the details of an authorised / refused payment. We recommend that you familiarise
yourself with the MAI and how to view payments. We suggest you also verify that your own
systems have reacted as expected to the various payment responses.
Capturing or Cancelling a Payment
Overview: Capturing or Cancelling a Payment
You can confirm that you wish to receive the funds that have been authorised (‘reserved’) for
you. To do so, you must capture the payment. To confirm that you do not wish to receive
funds, you must cancel the payment. You cannot capture REFUSED or CANCELLED
payments.
16
If you have not specified a capture delay with WorldPay, then your payments will be captured
automatically within 15 to 30 minutes and you need to take no action to capture those
payments.
If you do have a capture delay enabled, then your payment will be captured when this delay
expires, unless you have already either captured or cancelled the payment.
Multi-Currency
Both a CAPTURED amount and a CANCELLED amount will always be in the currency as the
SENT_FOR_AUTHORISATION amount.
Methods for Capturing a Payment in Sandbox
You have several options to capture a payment.
XML
You can submit an XML order modification request for an authorised payment to capture a
payment. Refer to Order Modifications and Order Inquiries Guide for details.
Single and Bulk Payment Capture
You can login to the Merchant Interface (MI) to capture a payment. There are two options
available to you:
Single Payment
Locate the payment in the MI and use the Capture button displayed on the Payment
Details screen to capture the payment.
Bulk Capture
Use the Bulk Capture option on the left-hand navigation panel to select several
payments to capture. You can capture up to 100 AUTHORISED payments at once.
Partial Capture
Depending on your individual setup and agreement with WorldPay, you may be enabled for
partial capture in Sandbox. That means that you can capture parts of the authorised amount,
instead of the full amount. You may also be enabled to carry out multiple partial captures of a
partially captured payment. Your Sandbox environment will reflect your production setup.
Please check if you have received relevant notifications. You can view and amend your
notifications setup in the Merchant Interface (MI). You can also use the MI to view the details
of a captured/cancelled payment. We recommend that you familiarise yourself with the MAI
and how to view, capture and cancel payments. We suggest you also verify that your own
systems have reacted as expected to those payment events.
17
Settling a Payment
Overview: Settling a Payment
After you have captured a payment, WorldPay communicates your capture request to the
card issuer, who will transfer the authorised (‘reserved’) funds to WorldPay (or your acquirer).
We will confirm when we have received those funds by updating the status of CAPTURED
payments to SETTLED. Payments marked as SETTLED can be paid out to you via bank
transfer.
Settlement Simulation
The Settlement process will take several days in the production environment and varies
between countries, acquirers, card issuers and card holders. To enable you to test this
process in Sandbox, we have created a settlement simulation option in the Merchant
Interface (MI) for you.
Multi-Currency
For multi-currency payments, your SETTLED amount will converted from the authorisation
currency to your settlement currency.
Settling a Single Payment
Locate the payment in the MI and use the Settlement button displayed on the Payment
Details screen to simulate the settlement of a CAPTURED payment.
Performing Bulk Settlement
Use the Bulk Settlement option on the left hand navigation panel to select several payments
to settle. You can settle up to 100 CAPTURED payments at once.
of a settled payment. We recommend that you familiarise yourself with the MI and how to
view payments. We suggest you also verify that your own systems have reacted as expected
to the new payment event.
Refunding a Payment
Overview: Refunding a Payment
You can return funds to your customer by initiating a refund. You can only refund payments
that have reached either the CAPTURED or SETTLED status. You cannot refund payments
with a status of REFUSED, CANCELLED or AUTHORISED (and not yet captured). You
cannot refund more than the total CAPTURED amount of the transaction.
18
Your refund request will create a new payment event of SENT_FOR_REFUND, which is
added to the payment history of a payment.
For real payments in the production environment, WorldPay passes on your refund request to
the card issuer, who will confirm this refund through the settlement process. The settlement
process will move payments from SENT_FOR_REFUND to REFUNDED.
This means that the standard settlement rules also apply for refunds, including timing. You
can use the settlement simulators available in Sandbox to simulate this step and move a
payment from SENT_FOR_REFUND to REFUNDED. This simulation is not available in the
Production environment.
Multi-Currency
The SENT_FOR_REFUND amount will always be in the same currency as the
SENT_FOR_AUTHORISATION amount. The REFUNDED amount will always be in the same
currency as the SETTLED amount.
Methods for Refunding a Payment in Sandbox
Sandbox provides two ways to refund a payment:
XML
Merchant Interface (MI)
XML
You can submit an XML order modification request to capture a payment. Refer to Order
Modifications and Order Inquiries Guide for details.
MI
You can login to the Merchant Interface (MI) to refund a payment. Locate the payment in the
MI and use the Refund button displayed on the Payment Details screen to refund the
payment.
Submitting Partial Refunds in Sandbox
You can submit partial refunds for real payments in the production environment. That means
that you can refund parts of a captured amount, instead of the full amount. Sandbox will allow
you to test this feature as well.
of a refunded payment. We suggest you also verify that your own systems have reacted as
expected to those payment events.
19
Alternative Payment Methods (APMs)
About Testing APMs
You can test supported alternative payment methods (APMs) up to the SETTLED and
REFUNDED statuses. Sandbox supports testing for both the direct and redirect integration
methods.
This section covers the following topics:
Testing the payment journey
Types of APMs
Testing the Payment Journey
You can test the following parts of the payment journey:
Order submission
You can submit orders for a variety of APMs and verify different aspects of the order
submission process. For example, after you submit an APM order in Sandbox, you
can check whether the shopper's browser was correctly redirected to a result URL.
Authorisation
You can simulate the authorisation of an APM test payment by a payment service
provider. The simulated authorisation takes place immediately. In the production
environment, authorisation may be delayed for some APMs. For example, an online
bank at which the shopper makes the payment may only authorise payments during
working hours. With Sandbox, you can simulate this scenario, but authorise the
payment immediately.
Capture
You can verify that an APM payment was captured. For most APMs, the capture of a
payment takes place automatically. A background process runs every 15 to 30
minutes and captures payments that have reached a payment status of
AUTHORISED.
You can optionally expedite the capture process in Sandbox. Using the bulk capture
feature in the Merchant Interface (MI), you can capture a payment with the
AUTHORISED status right away.
For more information about payment statuses, see Payment Statuses.
Settlement
You can simulate the settlement of a payment. The payment is settled immediately in
Sandbox.
Refund
You can test the full or partial refund of a payment, as well as multiple partial refunds
20
of the same payment. You can request a refund and then simulate the completion of
the refund in Sandbox.
APMs are provided by payment service providers (PSPs). A PSP offers merchants a variety
of payment methods, including alternative payment methods and bank transfers, for
accepting ecommerce payments.
Types of APMs
Most APMs fall into one of four categories. For a given category, the order submission and
capture process is the same. There are also other APMs with more unique payment flows
that do not fall into one of the four categories. For example, China Union Pay and GiroPay
have unique payment flows.
Many APMs belong to one of the following four categories:
APM Category
Definition
Real-Time Hybrid
When using a real-time hybrid payment method, shoppers must perform
additional tasks or interact with the PSP before they can complete the
payment. The payment is authorised in real-time. You receive immediate
notification of the payment's status.
Delayed Hybrid
With delayed hybrid APMs, shoppers may need to interact directly with
the PSP or bank during the shopper payment journey. There is a delay
from the end of the shopper payment journey to the payment being
authorised. The payment remains in the SHOPPER_REDIRECTED
status for hours or days, depending on the payment method used.
Real-Time Non-Hybrid
With real-time non-hybrid payment methods, shoppers do not need to
interface with the payment service provider (PSP) to complete the
payment. The payment is authorised in real-time and you receive
immediate notification.
Delayed Non-Hybrid
When a shopper makes a payment by using a delayed non-hybrid
payment method, the PSP completes the payment without prompting the
shopper for any further information. The payment pages of the PSP are
invisible to the shopper.
Delayed non-hybrid payments are not authorised immediately. Funds are
transferred into your account depending on the payment processing
policies of the PSP.
For more information refer to the Alternative Payment Methods Guide.
Differences Between APMs
During your testing, keep in mind that alternative payment methods may have different
characteristics and validation criteria. APMs can differ in the following ways:
Additional APM-specific shopper data may need to be collected.
APMs can have transaction value validation involving minimum and maximum
amounts.
APMs may have currency restrictions.
Only certain currencies can be used with specific APMs.
21
Pre-authorisation checking provided through the Risk Management Module or
RiskGuardian may or may not be supported for a particular APM.
For more information on the characteristics of each APM, refer to the Alternative Payment
Methods Guide.
Supported APMs
Sandbox supports the following APMs:
Alternative payment
method
Abaqoos
direct, redirect
AliPay
direct, redirect
AstroPay Card
direct, redirect
Baloto
direct, redirect
BankAxess
direct, redirect
Banklink NORDEA
direct, redirect
Boleto
direct, redirect
CashU
direct, redirect
China Union Pay
redirect only
Dineromail (OLBT)
direct, redirect
Dineromail (Servipag)
direct, redirect
DineroMail 7eleven
direct, redirect
Dineromail OXO
direct, redirect
eKonto*
direct, redirect
eNETS
22
Integration method
redirect only
Fast bank transfer
direct, redirect
ePay
direct, redirect
Alternative payment
method
EPS
Integration method
redirect only
EUteller
direct, redirect
eWireDK
direct, redirect
eWireNo
direct, redirect
eWireSE
direct, redirect
GiroPay
direct, redirect
InstaDebit
direct, redirect
Konbini
direct, redirect
Mister Cash
direct, redirect
Moneta
direct, redirect
MultiBanco
direct, redirect
NeoSurf
direct, redirect
Paga Wallet
direct, redirect
PaySafeCard
direct, redirect
POLi
direct, redirect
POLi (NZ)
direct, redirect
PostePay
direct, redirect
Przelewy24*
direct, redirect
Qiwi*
direct, redirect
SafetyPay*
direct, redirect
SOFORT
direct, redirect
23
Alternative payment
method
Integration method
Sporopay
direct, redirect
TeleIngreso
direct, redirect
ToditoCash
direct, redirect
TrustPay (CZ, EE, SK)
direct, redirect
WebMoney
direct, redirect
Yandex.Money
direct, redirect
* This is a conditional APM.
For more information see Conditional APMs.
About Submitting APM Test Orders
Simulated Activities in Sandbox
When you submit a test order in Sandbox, Sandbox simulates activities that would take place
in the production environment.
Activity in the production environment
Represented in Sandbox
The redirection of the shopper to a payment
service provider’s payment pages.
The Sandbox simulator is displayed.
The redirection of the shopper to a result URL.
Your browser is redirected to a result URL.
For certain types of payments, called delayed
alternative payment methods, the shopper
completes a payment after a delay.
To simulate a delay in payment, you can specify a
payment outcome of Pending.
Once the shopper has completed the payment,
the PSP authorises it.
You use the Authorise feature in the test Merchant
Interface to manually move the payment to the
AUTHORISED status.
For more information on payment statuses, see
Payment Statuses.
For more information on types of alternative payment methods (APMs), see About Testing
APMs.
24
Payment Statuses
The following payment statuses apply to alternative payment method (APM) payments in
Sandbox:
Not all alternative payment methods (APMs) use all payment statuses.
Payment status
SHOPPER_REDIRECTED
Definition
Direct model: The shopper has selected a payment method and
made the payment.
Redirect model: The order is created and the shopper has selected
the required payment method and provided any additional payment
information on the WorldPay website.
SHOPPER_CANCELLED
WorldPay has received notification from a payment service provider
that the shopper has cancelled the transaction without making a
payment.
SENT_FOR_AUTHORISATION
WorldPay has sent a request for authorisation of the payment to the
payment service provider (PSP).
AUTHORISED
The PSP has authorised the payment.
REFUSED
The PSP has refused to authorise the payment. Possible reasons
for refusal are an exceeded credit limit or insufficient balance.
WorldPay is not always informed of the refusal reason by the PSPs.
When WorldPay does receive a reason for refusal, this is visible to
you in the Merchant Interface.
CAPTURED
WorldPay has received the pay-in notification and the payment from
the PSP.
SETTLED
A payment with the status SETTLED is ready to be paid out to your
bank account.
SENT_FOR_REFUND
This status indicates that you have instructed WorldPay to refund a
transaction and that WorldPay's system has accepted this
instruction. However, the refund has not yet been carried out.
REFUNDED
This status indicates that WorldPay has successfully completed its
processing activities for the refund and has submitted the
transaction to the financial institution for final processing. Applies to
payments previously having a status of SENT_FOR_REFUND.
Note: A payment with the REFUNDED status does not indicate that
the shopper has received the funds. The shopper may receive the
funds at a later time, depending on the financial institution's
processing.
REFUND_FAILED
The payment status changes to REFUND_FAILED if one
25
Payment status
Definition
of the following occur:
The refund is rejected immediately.
The refund validation fails, for example, if the
bank details of the shopper are incorrect or have
changed.
The refund is reversed or returned.
Payment Outcomes and Result URLs
As part of your system testing, you should understand the use of payment outcomes and
result URLs.
Payment Outcomes
When you submit test orders in Sandbox, you need to specify a desired payment outcome.
For example, you can specify a payment outcome of AUTHORISED to simulate a payment
flow in which a payment service provided (PSP) approves a payment.
There are two ways to specify a payment outcome:
Simulator
The Sandbox simulator is automatically displayed during the payment process,
typically after you submit an order. You can select a payment outcome from a dropdown list on the simulator.
For more information see Sandbox Features for Submitting APM Orders.
Magic value
For some APMs, you can specify a magic value directly in the XML of your order. A
magic value is a term that represents a supported payment outcome. To specify a
magic value, you place it in the lastName element of the billing address in your XML
order. When you specify a magic value, the simulator is bypassed.
For more information see Sandbox Features for Submitting APM Orders.
26
Sandbox supports the following payment outcomes for APMs:
Not all alternative payment methods use all payment outcomes.
AUTHORISED. The payment service provider has indicated that the shopper
payment has been made correctly.
PENDING. Our systems have detected that the payment has not been authorised in
real-time or cancelled. There are four additional parameters associated with the
pending payment result. They give more information as to why a shopper has been
redirected to the pendingURL.
ERROR. Our systems have detected that the transaction did not complete
successfully. Currently, there is limited use of this payment outcome.
EXPIRED. Our systems have detected that the transaction has timed out and
did not complete successfully. Currently, there is limited use of this condition.
FAILURE. Our systems have detected that the transaction did not complete
successfully. Currently, there is limited use of this payment outcome.
OPEN. Our systems have detected that the transaction may reach a status of
AUTHORISED in the future. However, an authorised status has not been
achieved at this point in the transaction life cycle.
CANCELLED. Our systems have detected that the payment process has been
cancelled by the shopper.
REFUSED. Our systems have detected that the request for the payment to be
authorised has been refused. It is possible that a payment attempt is refused by the
WorldPay Risk Management Module, a built-in tool used to reduce the risk of fraud. If
a payment is refused for this reason, WorldPay sets the status to REFUSED with the
refusal reason of fraud suspicion.
A payment outcome of Not authorised is available for the China Union Pay payment
method. For more information, see China Union Pay (Redirect).
Result URLs
After a shopper has entered their payment details, the payment service provider provides a
payment result. WorldPay returns the payment result to you in the form of a result URL. You
should use the result URL to redirect the shopper's browser to a web page where the
shopper can get information about the status of the order.
In Sandbox, as in the production environment, you should provide redirect URLs as follows:
In the direct model, you must provide redirect URLs in your XML order.
In the redirect model, it is strongly recommended that you provide result URLs. You
can specify result URLs by appending them to the initial redirect URL. In most cases,
if you do not provide result URLs, the shopper's browser is redirected to WorldPay's
default result URLs.
27
For alternative payment methods, one of the following result URLs is returned:
successURL: The URL that is returned if the payment is successful.
cancelURL: The URL that is returned if the payment is cancelled.
pendingURL: The URL that is returned if the payment is neither successful nor
cancelled. This URL is commonly returned for delayed payment methods. The
pendingURL typically contains one of the following additional pending parameters:
ERROR
EXPIRED
FAILURE
OPEN
failureURL: The URL that is returned for some payment methods where the
payment attains a REFUSED status.
The China Union Pay payment method can also have a 'Not authorised' result URL.
For more information, see China Union Pay (Redirect).
MAC Authentication in the Redirect Message to the Result URL
For the redirect model, you can opt to have a Message Authentication Code (MAC)
appended to redirect messages. Appending a MAC gives you a way to verify the authenticity
of the redirect message. For APMs, the MAC is appended to the redirect message for the
successURL only. You can use the MAC in this case to verify that a payment has reached a
payment status of AUTHORISED.
You can enable the MAC feature in the Merchant Interface under Profile > Merchant
Environment. For more information, refer to the Hosted Payment Page (XML Redirect)
Guide.
Sandbox Features for Submitting APM Orders
When you submit test orders for APMs in Sandbox, you use the same XML as you would in
the production environment. In addition, you can specify a desired payment outcome in
Sandbox. For example, you can submit a test order where you specify an initial payment
outcome of Pending - open. Use either of the following Sandbox features to specify a desired
outcome:
Simulator
Magic value
28
Simulator
When you use the simulator, a dialog box is displayed from which you can select a desired
payment outcome.
Figure: Secure Test Simulator page
You can use the simulator to do the following:
Test the redirection of the shopper's browser.
Simulate different payment outcomes, such as Authorised or Pending - failure.
Not all payment service providers (PSPs) support all browsers. The simulator
may support a browser that is not supported by a PSP.
Submitting an Order Using the Simulator
1. Submit an XML order.
WorldPay sends an XML reply containing a URL to redirect your browser.
Direct model: The Secure Test Simulator Page is displayed. Go to Step 3.
Redirect model: The payment method selection page is displayed, unless the
payment method mask for the APM has been appended.
2. Redirect model only: If the payment method selection page is displayed, select the
desired payment method.
The Secure Test Simulator Page is displayed.
29
3. Select the desired outcome from the Payment Outcome list and click Continue.
Your browser is redirected to a result page.
Do not use your browser's Back button to return to the simulator for the
purpose of submitting another payment. Always submit unique orders using
XML. Returning to the simulator page to submit a new payment may cause
errors and result in reporting problems.
Magic Values
A magic value represents a supported payment outcome. When you provide a magic value,
the simulator is skipped. The shopper's browser is typically redirected to a payment result
page. You can use magic values for both the direct or redirect integration methods.
Magic values are supported for the following APMs in Sandbox:
SOFORT
AliPay
WebMoney
Paysafecard
China Union Pay
You can specify one of the following payment outcomes as magic values:
AUTHORISED
CANCELLED
PENDINGERROR
PENDINGEXPIRED
PENDINGFAILURE
PENDINGOPEN
REFUSED - The REFUSED magic value can only be used with China Union Pay.
For a list of APM magic values, refer to the Sandbox Magic Values Spreadsheet. Select the
MV | APM Pay Result worksheet.
Specifying a Magic Value
To provide a magic value in the order XML, specify it in the lastName element of the billing
address. Magic values are not case sensitive.
For a pending magic value, you need to specify two parts:
PENDING + the type of pending outcome
For example, to simulate a pending outcome where the transaction is awaiting action by the
shopper, you specify PENDINGOPEN in the XML order message.
30
Example
The following XML order example shows a magic value of PENDINGERROR in an XML
order for the redirect integration method.
<?xml version="1.0"?>
<!DOCTYPE paymentService PUBLIC "-//Bibit//DTD Bibit PaymentService v1//EN"
"dtd/paymentService_v1.dtd">
<paymentService merchantCode="DEMO" version="1.4">
<submit>
<order orderCode="T0211010">
<description>Shopper order description</description>
<amount currencyCode="EUR" exponent="2" value="7500"/>
<orderContent>Order Content Here</orderContent>
<paymentMethodMask>
<include code="ALL"/>
</paymentMethodMask>
<shopper>
<shopperEmailAddress>j.shopper@myprovider.int</shopperEmailAddress>
</shopper>
<shippingAddress>
<address>
<firstName>John</firstName>
<lastName>PENDINGERROR</lastName>
<address1>Shopperstreet</address1>
<address2>Shopperaddress2</address2>
<address3>Shopperaddress3</address3>
<postalCode>1234</postalCode>
<city>Shoppercity</city>
<countryCode>DE</countryCode>
<telephoneNumber>0123456789</telephoneNumber>
</address>
</shippingAddress>
<statementNarrative>STATEMENT NARRATIVE TEXT</statementNarrative>
</order>
</submit>
</paymentService>
Verifying Payment Creation
In general, when testing the order submission of alternative payment methods (APMs),
ensure that:
WorldPay accepts the XML order as valid.
Your system is able to accept the WorldPay XML response and redirect the
shopper's browser to one or both of the following:
Redirect model only: The payment method selection page, if used.
The simulator, if used.
If you submit an order with a magic value, the simulator is
bypassed.
After the simulation of a payment outcome, such as AUTHORISED, your system
provides a result URL for shopper redirection.
31
Your system is able to securely determine that the WorldPay transaction status has
reached a particular payment status by accepting the WorldPay order notification
message and acknowledging it.
It is recommended that you configure and use order notifications.
Best Practice Guidelines
To help ensure the effectiveness of your testing, we recommend that you make use of the
following:
Order notifications
Test scripts provided by WorldPay
Order Notifications
It is recommended that you configure and use order notifications. You can use this feature to
receive notification that the status of a payment has changed.
Order notifications are available for APM payments for the following payment statuses:
Payment status
SHOPPER_REDIRECTED
SHOPPER_CANCELLED
AUTHORISED
REFUSED
SETTLED
CAPTURED
SENT_FOR_REFUND
REFUNDED
32
Order
notification
available?
Payment status
Order
notification
available?
REFUND_FAILED
You can configure order notifications in the Merchant Interface (MI). For more information
about payment statuses, see Payment Statuses.
Test Scripts
To ensure successful integration of your system with alternative payment methods, it is
strongly recommended that you complete the relevant test scripts provided by WorldPay.
The test scripts are made up of a number of test cases. A test case represents an individual
scenario in which an order is submitted. Each test case provides:
The specific parameters to use when submitting the test order for the test case.
Pass requirements that detail the successful completion of the test case.
To get obtain test scripts, please contact your relationship manager.
Conditional APMs
Some APMs are in more than one APM category. For example, an APM may be in the realtime category or the delayed category; the category depends on how the shopper pays. For
example, a transaction for the Qiwi APM can take place in one of two ways:
if the shopper uses an EWallet to pay, the authorisation of the payment takes place
in real-time. We call this payment a real-time APM.
If the shopper pays at a kiosk, the payment authorisation is delayed. We call this
payment a delayed APM.
Testing Conditional APMs in Sandbox
To test the payment flow of a conditional APM in Sandbox, select a realistic payment
outcome that is consistent with the way the APM transaction takes place.
For example, to simulate the real-time version of the APM, select a payment outcome of
Authorised. To simulate the delayed version of the APM, select a payment outcome of
Pending-open.
33
Conditional APMs
This section lists the conditional APMs and indicates the payment outcomes that apply.
APM Name
eKonto
Przelewy24
SAFETYPAY
QIWI WALLET
Shopper's
Payment
Method
APM Category
Payment
Outcome to
Select
Bank transfer (24
hour service)
Real-time hybrid
Authorised
Bank transfer
(business hours)
Delayed hybrid
Pending-open
Bank transfer (24
hour service)
Real-time hybrid
Authorised
Bank transfer
(business hours)
Delayed hybrid
Pending-open
Bank transfer
Real-time hybrid
Pending-open
Pay by post pay
voucher at kiosk
Delayed hybrid
Pending open
Pay by post-pay
voucher at kiosk
Delayed hybrid
Pending-open
ewallet
Real-time hybrid
Authorised
Banking Hours - 24 Hours or Office Hours
Some banks only provide online transfers during business hours (for example, 9am to 5pm),
or some other restricted time period (for example 8am to 8pm). This can result in a mixture of
real-time authorised transfers and authorised but delayed transfers, depending on the time of
day the transaction takes place. We recommend you test both cases: online and offline for
these conditional APMs.
Intermediate Data Collection Pages (Redirect)
If you use the redirect model but do not collect details required by a payment method,
WorldPay displays an intermediate data collection page to the shopper.
Intermediate data collection pages typically collect information for one or more of the
following elements of an XML order:
payment
shopper
shippingAddress
Where you can, try to provide this information with your original XML order. Providing it with
your order eliminates the need for the shopper to re-enter it on an intermediate data
collection page.
34
Field Validation
When an intermediate data collection page is displayed, WorldPay validates each field by
checking that the field is populated.
For the phone number field, the following additional validation is performed:
Field
Validation performed
Phone
number
The field must contain at least three digits. The following characters are permitted: 0 1 2
3456789()+-/
Example
As an example, the Teleingreso payment method requires the firstName and lastName
child elements of the shippingAddress element. If this information is provided with the
XML order, the intermediate data collection page is bypassed. If this information is not
provided, WorldPay displays an intermediate data collection page to the shopper. The
shopper must enter this information before continuing with the payment.
Figure: Example intermediate data collection page
APMs with Intermediate Data Collection Pages
The following table shows APMs that use intermediate data collection pages when required
data is not provided in the XML order.
APM Name
Data Collected
For the redirect model only: The value
for the CPF/CNPJ number cannot be
included in your XML order. As a result, an
intermediate data collection page for Boleto
Bancário is mandatory and cannot be
bypassed.
Boleto Bancário
First name
Last name
Address 1
Town/city
State
Post code
Phone number
Email address
CPF/CNPJ number
35
APM Name
Data Collected
DineroMail Bank Transfer
First name
Last name
Email
Telephone number
(includes Servipag, OXXO and
7-Eleven)
MisterCash
First name
Last name
Address 1
Post code
City
Country code
Email address
Teleingreso
First name
Last name
ToditoCash
Email
PAN (Primary Account Number)
PIN (Personal Identification Number)
Submitting APM Test Orders - Direct Integration
Real-Time Hybrid APMs (Direct)
When using a real-time hybrid payment method, shoppers must complete additional tasks or
interface with the payment service provider (PSP) before they can complete the payment.
With this method, the payment is authorised in real-time. You receive immediate notification
of the payment's status.
Supported APMs
The following real-time hybrid APMs are supported in Sandbox for the direct integration
method:
Abaqoos
AliPay
Mister Cash
PaySafeCard
Qiwi
SOFORT
WebMoney
Yandex.Money
36
For a subset of real-time hybrid APMs, you can submit orders using either the simulator or
magic values:
AliPay
Paysafecard
SOFORT
WebMoney
For all other real-time hybrid APMs, use the simulator
Submitting a Test Order Using the Simulator
The simulator is displayed automatically during the test payment flow in Sandbox. It contains
a drop-down list from which you can select a desired payment outcome.
Authorised Outcome
Direct integration > Real-time hybrid > Simulator > Authorised outcome
Step
Action
Result
1.
Submit an XML order.
Payment
status=SHOPPER_REDIRECTED.
Messaging
The simulator is displayed.
2.
At the simulator, select a
payment outcome of
Authorised from the
Payment Outcome list.
Payment status=AUTHORISED.
Your browser is redirected to a
result URL.
An order notification is
generated, if
configured in the
Merchant Interface.
37
Pending Outcome
Direct integration > Real-time hybrid > Simulator > Pending outcome
Step
Action
Result
Messaging
1.
Payment
2.
At the simulator, select one of
the following outcomes from
the Payment Outcome list:
Pending - error
Pending - expired
Payment
pendingURL. The pendingURL
contains one of the following
additional pending parameters:
Pending - failure
ERROR
Pending - open
EXPIRED
FAILURE
OPEN
Cancelled Outcome
Direct integration > Real-time hybrid > Simulator > Cancelled outcome
Step
Action
Result
1.
Payment
2.
38
payment outcome of
Cancelled from the Payment
Outcome list.
Payment
status=SHOPPER_CANCELLED.
cancelURL.
Messaging
Submitting a Test Order Using Magic Values
A magic value is a term that can be used to represent a payment outcome.
You can submit orders using the magic values for the following real-time hybrid APMs:
AliPay
Paysafecard
SOFORT
WebMoney
When you submit an order using a magic value, the simulator is bypassed.
For more information about magic values, see Sandbox Features for Submitting APM Orders.
Authorised Outcome
Direct integration > Real-time hybrid > Magic value > Authorised outcome
Step
Action
Result
Messaging
1.
Submit an XML order. Ensure
the lastName element of the
billing address contains the
AUTHORISED magic value.
The payment status is moved from
SHOPPER_REDIRECTED to
AUTHORISED.
generated, if
configured in the
Merchant Interface.
successURL.
Pending Outcome
Direct integration > Real-time hybrid > Magic value > Pending outcome
Step
Action
Result
1.
billing address contains one of
the following PENDING magic
values:
Payment
PENDINGERROR
Messaging
PENDINGEXPIRED
ERROR
PENDINGOPEN
EXPIRED
PENDINGFAILURE
FAILURE
OPEN
39
Cancelled Outcome
Direct integration > Real-time hybrid > Magic value > Cancelled outcome
Step
Action
Result
1.
CANCELLED magic value.
SHOPPER_CANCELLED.
Messaging
cancelURL
Delayed Hybrid APMs (Direct)
In the production environment, when payments are made using delayed APMs, there is a
delay from the end of the shopper payment journey to the payment being authorised. The
payment remains in the SHOPPER_REDIRECTED status until the shopper completes
additional payment steps. At that point, the payment service provider advises WorldPay that
the shopper has completed the payment and the payment status changes to AUTHORISED.
Supported APMs
The following delayed hybrid APMs are supported in Sandbox for the direct integration
method:
Boleto
Konbini
Przelewy24
Qiwi
Some delayed hybrid payment methods may also operate as real-time hybrid
payment methods. For more information, see Conditional APMs.
Delayed Hybrid APMs in Sandbox
For delayed hybrid APMs, an Authorised outcome is not available from the Sandbox
simulator, reflecting the delayed nature of these payments. As in the production environment,
the delay in payment completion means that an initial payment outcome of Pending is highly
likely. Similarly, the payment status remains at SHOPPER_REDIRECTED.
40
Because of an error in Sandbox, the Authorised outcome is incorrectly shown as
available for the following APMs:
Przelewy24
Qiwi
This error will be corrected in a future release.
In Sandbox, to advance the payment beyond the SHOPPER REDIRECTED status, you can
use the Authorise button in the test MI. Clicking the Authorise simulates WorldPay's
authorisation of the payment.
In the production environment, you cannot authorise your own transactions.
To advance a payment to the AUTHORISED state in Sandbox, you need to perform the
following two steps:
Step
Action
How
Order/Payment Status
1.
Submit an order.
Submit an XML order and use
the simulator to select a
Pending outcome.
SHOPPER_REDIRECTED
2.
Set the payment status to
AUTHORISED.
Click the Authorise button in
the Merchant Interface (MI)
application to change the
status from
AUTHORISED.
AUTHORISED
41
Submitting a Test Order
Pending Outcome
Direct integration > Delayed hybrid > Pending outcome
Step
Action
Result
Messaging
1.
Payment
2.
Pending - error
Pending - expired
Payment
Pending - failure
ERROR
Pending - open
EXPIRED
Then click Continue.
FAILURE
OPEN
Cancelled Outcome
Direct integration > Delayed hybrid > Cancelled outcome
Step
Action
Result
1.
Payment
2.
42
payment outcome of
Outcome list.
Payment
cancelURL.
Messaging
Authorising a Delayed APM Order
For delayed APMs in Sandbox, you can use the Merchant Interface (MI) application to
simulate the authorisation of the payment by the payment service provider.
Direct integration > Delayed hybrid > Manual simulation of authorisation
Step
Action
Result
1.
In the MI, navigate to the
Payments (Test) page.
The Payment and Order Details
(Test) window is displayed.
Messaging
Select a payment with a
Payment
status=SHOPPER_REDIRECTE
D.
2.
Under Payment Authorisation
Simulation, select Authorise.
When prompted to confirm the
authorisation, click OK.
successURL.
An order notification
is generated, if
configured in the
Merchant Interface.
Real-Time Non-Hybrid APMs (Direct)
With real-time non-hybrid payment methods, shoppers do not need to interface with the
payment service provider (PSP) to complete the payment. The payment is authorised in realtime and you receive immediate notification.
Supported APMs
The following real-time non-hybrid APM is supported in Sandbox for the direct integration
method:
Moneta
43
Authorised Outcome
Direct integration > Real-time non-hybrid > Simulator > Authorised outcome
Step
Action
Result
Messaging
1.
Payment
2.
payment outcome of
Authorised from the
result URL.
generated, if
configured in the
Merchant Interface.
Pending Outcome
Direct integration > Real-time non-hybrid > Simulator > Pending outcome
Step
Action
Result
Messaging
1.
Payment
2.
Pending - error
Pending - expired
Payment
Pending - failure
ERROR
Pending - open
EXPIRED
FAILURE
OPEN
44
Cancelled Outcome
Direct integration > Real-time non-hybrid > Simulator > Cancelled outcome
Step
Action
Result
1.
Payment
Messaging
2.
payment outcome of
Outcome list.
Payment
cancelURL.
Delayed Non-Hybrid APMs (Direct)
When a shopper makes a payment using a delayed non-hybrid payment method, the
payment service provider (PSP) completes the payment without prompting the shopper for
any further information. The payment pages of the PSP are not shown to the shopper.
Delayed non-hybrid payments are not authorised immediately. Funds are transferred into
your account according to the payment processing policies of the PSP.
Supported APMs
Multibanco
Delayed Non-Hybrid APMs in Sandbox
In Sandbox, after you submit a test order for a delayed non-hybrid APM, you are redirected to
the simulator where the following activities are simulated:
WorldPay sends a payment request to the PSP.
WorldPay receives the status of the payment from the PSP and returns a result URL
to you.
The Sandbox simulator displays only one possible payment outcome, Pending - open,
reflecting the delayed nature of this payment type.
Testing Multibanco Payments
This section describes the transaction flows for Multibanco payments in the production
environment and in Sandbox.
Production Environment Behaviour
For Multibanco payments, a pendingURL is the most likely result URL returned to you by
WorldPay.
45
In addition, WorldPay appends parameters that are specific to Multibanco payments to the
result URL. For example, Multibanco reference and entity numbers are appended.
In a live environment, you must display this information to the shopper. The shopper uses this
information to compete the payment. To complete the payment, the shopper logs into online
banking or uses an ATM. For more information about the specific parameters that are
appended, refer to the Alternative Payment Methods Guide.
Testing Multibanco Payments in Sandbox
For Multibanco test payments in Sandbox, Sandbox appends the additional Multibanco
information to the result URL. However, Sandbox does not simulate the display of Multibanco
reference and entity details to the shopper.
Submitting a Multibanco Test Order
Direct integration > Delayed non-hybrid > Simulator > Pending outcome
Step
Action
Result
Messaging
1.
Sandbox provides a redirect URL.
You are redirected to the simulator. The
simulator is displayed.
Payment
2.
At the simulator, select
following outcome from the
Payment Outcome list:
Pending - open
Payment
pendingURL. The pending type is OPEN. In
addition, the following parameters are
appended and must be communicated to
the shopper:
multibancoReference
multibankoEntity
multibancoPaymentAmount
multibancoPaymentCurrency
For more information about these
parameters, refer to the Alternative
Payment Methods Guide.
46
Fast Bank Transfers (Direct)
When you provide fast bank transfer as a payment option, the shopper pays for the goods
and services by making a bank transfer into the account of a participating bank.
The following steps describe a typical payment flow for fast bank transfers.
1. On the payment page, the shopper selects the fast bank transfer payment method.
2. You determine the country of the shopper and display a list of banks which accept
fast bank transfer payments in that country.
You can retrieve this information from WorldPay. For more information, see About
Retrieving a List of Banks.
3. The shopper selects a bank.
4. You submit an XML order to WorldPay. At this point, the following occurs:
WorldPay creates a payment with a payment status of
SHOPPER_REDIRECTED and sends an XML response to you. The
response contains a unique payment reference. The response also confirms
the payment amount and currency.
5. You display payment details to the shopper and also provide instructions for
completing the payment.
To initiate a bank transfer, the shoppers can log into their online bank or manually
complete a bank transfer form at their bank.
To provide this payment method, you need to:
Display a list of banks to shopper. The shopper selects a bank from the list and
later transfers money to the bank to complete the payment.
To display an up-to-date list of banks, you should retrieve and store a list of banks for
each shopper country. You can request a list of banks from WorldPay using XML.
Provide instructions on how to complete the bank transfer. The instructions
should contain a unique payment reference provided by WorldPay.
This section covers the following topics:
About Retrieving a List of Banks
Submitting Fast Bank Transfer Payments in the Production Environment
Testing Bank List Retrieval
Submitting Test Orders in Sandbox
About Retrieving a List of Banks
As part of the payment journey, you need to display a list of banks to the shopper that is
based on the shopper's country. To provide your shoppers with the most up-to-date list of
banks, you should send an XML request to WorldPay once a day. Send one XML request for
each shopper country. For example, if you provide fast bank transfers for shoppers in France
and Belgium, you need to send two XML requests, one for each country, every day.
47
Data Required
The following data is required in your XML request:
XML Element/attribute
Description
source
The account source. Currently, envoy is the only source available.
shopperCountryCode
The shopper's country.
Request XML
To retrieve a list of banks by country, use the following syntax for your XML request:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN"
"http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4">
<inquiry>
<bankAccountInquiry source="envoy" shopperCountryCode="FR"/>
</inquiry>
</paymentService>
Response XML
The following sample XML shows WorldPay's response. In this case, the
shopperCountryCode is FR for France.
This example XML response has been shortened.
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
<reply>
<bankDetails>
<accountName>Envoy Services Limited</accountName>
<accountNumber>60067T</accountNumber>
<accountType/>
<bankAccountCountry>FR</bankAccountCountry>
<bankAccountCurrency>EUR</bankAccountCurrency>
<bankCode>30002</bankCode>
<bankGiro/>
<bankName>LCL - Le Credit Lyonnais</bankName>
<branchAddress>Paris</branchAddress>
<branchCode>06295</branchCode>
<checkDigits>41</checkDigits>
<iban>FR32 3000 2062 9500 0006 0067 T41</iban>
<note1/>
<note2/>
<note3/>
<swift>CRLYFRPPXX </swift>
</bankDetails>
48
<bankDetails>
<accountName>WorldPay AP Limited.</accountName>
<accountNumber>00200791559</accountNumber>
<accountType/>
<bankAccountCountry>FR</bankAccountCountry>
<bankAccountCurrency>EUR</bankAccountCurrency>
<bankCode>18739</bankCode>
<bankGiro/>
<bankName>THE ROYAL BANK OF SCOTLAND N.V. (FRANCE)</bankName>
<branchAddress>Paris</branchAddress>
<branchCode>00001</branchCode>
<checkDigits>11</checkDigits>
<iban>FR7618739000010020079155911</iban>
<note1/>
<note2/>
<note3/>
<swift>ABNAFRPPXXX</swift>
</bankDetails>
</reply>
The following elements are always present for all banks:
accountName
accountNumber
bankAccountCountry
bankAccountCurrency
bankCode
bankName
Other elements (for example, IBAN) may be present for some banks but not others.
This section provides examples of the XML order and response for fast bank transfers in the
production environment.
Mandatory Order Information
You must provide the following information with your XML order:
Description
currencycode
The currency of the order.
ENVOY_TRANSFER_XXX_BANK
The payment method mask, where XXX is a supported currency.
shopperCountryCode
The shopper's country code. The country code must correspond to one
of the countries which supports the selected payment mask.
shopperEmailAddress
The email address of the shopper.
49
XML Order Code
The following XML code shows a sample XML order for a shopper country of GB or Great
Britain:
<?xml version='1.0' ?>
<!DOCTYPE paymentService PUBLIC
'-//Bibit//DTD Bibit PaymentService v1//EN'
'http://dtd.bibit.com/paymentService_v1.dtd'>
<paymentService merchantCode="MERCHANT_CODE" version='1.4'>
<submit>
<order orderCode="Fast_Bank_Transfer_Example">
<description>description</description>
<amount currencyCode="GBP" value="100" exponent="2"/>
<orderContent>order content</orderContent>
<paymentDetails>
<ENVOY_TRANSFER_GBP-BANK shopperCountryCode="GB"/>
</paymentDetails>
<shopper>
<shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
</shopper>
</order>
</submit>
</paymentService>
XML Response from WorldPay
WorldPay sends an XML response similar to the following:
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
<reply>
<orderStatus orderCode="Fast_Bank_Transfer_Example">
<reference id="2525676008">WPMGB6355966</reference>
<paymentAmount>100</paymentAmount>
<paymentCurrency>GBP</paymentCurrency>
<orderAmount>100</orderAmount>
<orderCurrency>GBP</orderCurrency>
</orderStatus>
</reply>
</paymentService>
The XML response from WorldPay contains important information which you must display to
the shopper:
Description
OrderCode
It is recommended that you show the shopper the order code or some other
identifier that can be traced to your system and also matched to the WorldPay
order code.
reference
The shopper uses the reference to make the payment. The reference always
starts with the letters 'WPM'. In this example, the unique payment reference is
WPMGB6355966.
paymentAmount
The amount the shopper must pay.
50
Testing Bank List Retrieval
When you request a list of banks in Sandbox, WorldPay returns a list of banks for testing
purposes only. Although Sandbox returns information about real banks, the details about one
or more banks may not be up to date. In, addition, for a specified shopper country, the list of
banks may be incomplete.
Submitting Test Orders in Sandbox
When you send a test fast bank transfer payment to Sandbox, Sandbox sends an XML
response that contains a test payment reference and real bank details.
In the production environment, never give shoppers a Sandbox test payment
reference. Providing shoppers with this reference can result in the loss of live
payments.
To submit a fast bank transfer payment in Sandbox:
Direct integration > Fast bank transfer
Step
Action
Result
1.
Payment
Messaging
GiroPay (Direct)
Overview
GiroPay lets shoppers pay for online goods and services using direct online transfers from
their bank accounts.
51
Authorised Outcome
Direct integration > GiroPay > Authorised outcome
Step
Action
Result
1.
Payment
status=SENT_FOR_AUTHORISATION.
Messaging
2.
payment outcome of
Authorised from the
Your browser is redirected to a result
URL.
An order
notification is
generated, if
configured in the
Merchant
Interface.
Refused Outcome
Direct integration > CiroPay > Refused outcome
Step
Action
Result
1.
Payment
Messaging
2.
payment outcome of
Refused from the Payment
Outcome list.
Payment status=REFUSED.
failureURL.
An order
notification is
generated, if
configured in the
Merchant
Interface.
Submitting APM Test Orders - Redirect Integration
Real-Time Hybrid APMs (Redirect)
When using a real-time hybrid payment method, shoppers must complete additional tasks or
interact with the payment service provider (PSP) before they can complete the payment. With
this method, the payment is authorised in real-time. You receive immediate notification of
payment status.
52
Supported APMs
The following real-time hybrid APMs are supported in Sandbox for the redirect integration
method:
Abaqoos
AliPay
Mister Cash
Paysafecard
Qiwi
SOFORT
WebMoney
Yandex.Money
Submitting a Test Order Using the Simulator
53
Authorised Outcome
Redirect integration > Real-time hybrid > Simulator > Authorised outcome
Step
Action
Result
1.
the APM is specified.
If mandatory APM information is
required and is provided with the
order or if no additional information
is required for the APM, the
payment status is set to:
Messaging
Payment
Go to Step 2.
required and is not provided with the
order, an intermediate data
collection page is displayed.
1a.
If an intermediate data
collection page is displayed,
provide the required
information and click Submit.
Go to Step 2.
2.
payment outcome of
Authorised from the
result URL.
generated, if
configured in the
Merchant Interface.
If a Message
Authentication Code
(MAC) is used, a
secure ‘authorised’
message is appended
to the shopper redirect
URL.
54
Pending Outcome
Redirect integration > Real-time hybrid > Simulator > Pending outcome
Step
Action
Result
Messaging
1.
Payment
Go to Step 2.
required and is not provided with
the order, an intermediate data
1a.
Go to Step 2.
2.
Pending - error
Pending - expired
Payment
Pending - failure
ERROR
Pending - open
EXPIRED
FAILURE
OPEN
55
Cancelled Outcome
Redirect integration > Real-time hybrid > Simulator > Cancelled outcome
Step
Action
Result
1.
Messaging
Payment
Go to Step 2.
1a.
Go to Step 2.
2.
payment outcome of
Outcome list.
Payment
If a custom URL has been
appended, your browser is
redirected to the cancelURL.
Otherwise, your browser is
redirected to the payment selection
page.
Submitting a Test Order Using Magic Values
A magic value is a term that can be used to represent a payment outcome.
You can submit orders using the magic values for the following real-time hybrid APMs:
AliPay
Paysafecard
SOFORT
WebMoney
When you submit an order using a magic value, the simulator is bypassed.
For more information about magic values, see Sandbox Features for Submitting APM Orders.
56
Authorised Outcome
Redirect integration > Real-time hybrid > Magic value > Authorised outcome
Step
Action
Result
Messaging
1.
that the APM is specified. In
addition, ensure that the
lastName element of the
AUTHORISED magic value.
AUTHORISED.
generated, if
configured in the
Merchant Interface.
successURL.
Pending Outcome
Redirect integration > Real-time hybrid > Magic value > Pending outcome
Step
Action
Result
Messaging
1.
addition, ensure that the
billing address contains one of
the following PENDING magic
values:
Payment
PENDINGERROR
ERROR
PENDINGEXPIRED
EXPIRED
PENDINGOPEN
FAILURE
PENDINGFAILURE
OPEN
Cancelled Outcome
Redirect integration > Real-time hybrid > Magic value > Cancelled outcome
Step
Action
Result
1.
addition, ensure the
CANCELLED magic value.
SHOPPER_CANCELLED.
Messaging
Otherwise, your browser is redirect
to the payment selection page.
57
Delayed Hybrid APMs (Redirect)
With delayed hybrid APMs, shoppers may need to interact directly with the payment service
provider (PSP) or bank during the shopper payment journey. In addition, there is a delay from
the end of the shopper payment journey to the payment being authorised. The payment
remains in the SHOPPER_REDIRECTED status for hours or days, depending on the
payment method used.
Supported APMs
The following delayed hybrid APMs are supported in Sandbox for the redirect integration
method:
Boleto
Konbini
Przelewy24
Qiwi
Redirect occurs automatically when certain XML fields such as firstName are not
populated. The exception is Boleto, which always redirects to the intermediate data
collection pages, regardless of whether the fields in the XML code are populated or
not.
Delayed Hybrid Payment APMs in Sandbox
For delayed hybrid APMs, an Authorised outcome is not available from the Sandbox
simulator, reflecting the delayed nature of these payments. As in the production environment,
the delay in payment completion means that an initial payment outcome of Pending is highly
likely. Similarly, the payment status remains at SHOPPER_REDIRECTED.
Because of an error in Sandbox, the Authorised outcome is incorrectly shown as
available for the following APMs:
Przelewy24
Qiwi
This error will be corrected in a future release.
In Sandbox, to advance the payment beyond the SHOPPER REDIRECTED status, you can
use the Authorise button in the test MI. Clicking the Authorise simulates WorldPay's
authorisation of the payment.
In the production environment, you cannot authorise your own transactions.
58
To advance a payment to the AUTHORISED state in Sandbox, you need to perform the
following two steps:
Step
Action
How
Order/Payment Status
1.
Submit an order.
Submit an XML order and use
the simulator to select a
Pending outcome.
SHOPPER_REDIRECTED
2.
Set the payment status to
AUTHORISED.
Click the Authorise button in
the Merchant Interface (MI)
application to change the
status from
AUTHORISED.
AUTHORISED
Some delayed hybrid payment methods may also operate as real-time hybrid
payment methods. For more information, see Conditional APMs.
59
Pending Outcome
Redirect integration > Delayed hybrid > Pending outcome
Step
Action
Result
Messaging
1.
Payment
Go to Step 2.
1a.
Go to Step 2.
2.
the following payment
outcomes:
Pending – error
Pending – expired
Payment
Pending – failure
ERROR
Pending - open
EXPIRED
Then click Continue.
FAILURE
OPEN
60
Cancelled Outcome
Redirect integration > Delayed hybrid > Cancelled outcome
Step
Action
Result
1.
Messaging
Payment
Go to Step 2.
1a.
Go to Step 2.
2.
payment outcome of
Outcome list.
Payment
page.
61
Authorising a Delayed APM Order
For delayed APMs in Sandbox, you can use the Merchant Interface (MI) application to
simulate the authorisation of the payment by the payment service provider.
Direct integration > Delayed hybrid > Manual simulation of authorisation
Step
Action
Result
1.
In the MI, navigate to the Payments
(Test) page.
The Payment and Order
Details (Test) window is
displayed.
Messaging
Select a payment with a Payment
2.
Under Payment Authorisation
Simulation, select Authorise.
Payment
status=AUTHORISED.
When prompted to confirm the
authorisation, click OK.
Your browser is redirected to
a successURL.
An order notification
is generated, if
configured in the
Merchant Interface
For redirect
integration only: If a
Message
Authentication Code
(MAC) is used, a
message is
appended to the
shopper redirect
URL.
Real-Time Non-Hybrid APMs (Redirect)
With real-time non-hybrid payment methods, shoppers do not need to interface with the
payment service provider (PSP) to complete the payment. The payment is authorised in realtime and you receive immediate notification of the payment's status.
Supported APMs
The following real-time non-hybrid APM is supported in Sandbox for the redirect integration
method:
Moneta
62
Authorised Outcome
Redirect integration > Real-time non-hybrid > Authorised outcome
Step
Action
Result
1.
Messaging
Payment
Go to Step 2.
1a.
Go to Step 2.
2.
payment outcome of
Authorised from the
result URL.
generated, if
configured in the
Merchant Interface.
If a Message
Authentication Code
(MAC) is used, a
message is appended
URL.
63
Pending Outcome
Redirect integration > Real-time non-hybrid > Pending outcome
Step
Action
Result
Messaging
1.
Payment
Go to Step 2.
1a.
Go to Step 2.
2.
Pending - error
Pending - expired
Payment
Pending - failure
ERROR
Pending - open
EXPIRED
FAILURE
OPEN
64
Cancelled Outcome
Redirect integration > Real-time non-hybrid > Cancelled outcome
Step
Action
Result
1.
Messaging
Payment
Go to Step 2.
1a.
2.
payment outcome of
Outcome list.
Payment
page.
Delayed Non-Hybrid APMs (Redirect)
When a shopper makes a payment using a delayed non-hybrid payment method, the
payment service provider (PSP) completes the payment without prompting the shopper for
any further information. The payment pages of the PSP are not shown to the shopper.
Delayed non-hybrid payments are not authorised immediately. Funds are transferred into
your account according to the payment processing policies of the PSP.
Supported APMs
Multibanco
Testing Multibanco Payments
To complete a Multibanco payment, a shopper logs into online banking or uses an ATM.
65
During the shopper journey for a Multibanco payment, WorldPay displays a payment details
page containing Multibanco payment details and instructions for the shopper. The shopper
must use the payment details to complete the payment. WorldPay displays the following
payment details:
Reference
The nine-digit bill and customer reference number. For example: 574 210 144. The
shopper must provide this number when completing the payment.
Entity
The identifier of the company to which the payment is being made. For example:
80908. The shopper must provide this number when completing the payment.
Amount to pay
The amount that the shopper should pay.
The payment details page can be displayed in one of two ways, depending on whether you
provide a custom pendingURL with your order:
custom
pendngU
RL
provided?
Yes
Shopper journey
The payment details page is displayed with a
Continue button.
The shopper clicks Continue and is redirected to your
custom pendingURL.
No
The payment details page is displayed without a
Continue button.
Notes
Providing your own custom
pendingURL is a way to bring
the shopper back to your
webshop.
The shopper journey ends at the
payment details page.
The following figure shows possible payment flows depending on whether a custom
pendingURL is provided.
66
Figure: Possible payment flows for Multibanco payments
For more information about the Multibanco alternative payment method, refer to the
Alternative Payment Methods Guide.
Testing Multibanco Payments in Sandbox
When you submit test Multibanco payments, Sandbox simulates the live environment
payment flow as follows:
If you submit an order with a custom pendingURL appended, a Continue button is
displayed on the payment details page.
If you submit an order without a custom pendingURL appended, the payment details
page is displayed without a Continue button and the shopper journey ends here.
67
Submitting a Multibanco Test Order
Redirect integration > Delayed non-hybrid > Pending outcome
Step
Action
Result
Messaging
1.
Sandbox provides a redirect URL.
2.
Click the redirect URL.
You are redirected to the payment method
selection page.
Note: If you appended the payment method
mask for Multibanco, the payment method
selection page is bypassed.
3.
Click Multibanco.
Your browser is redirected to the payment
details page. Instructions for completing the
payment and Multibanco payment details are
provided.
Payment status=SHOPPER_REDIRECTED
If you appended a custom pendingURL to
your XML order, a Continue hyperlink is
displayed. Go to Step 4.
If you did not append a custom pendingURL
the shopper journey ends here.
4.
Click Continue.
Your browser is redirected to the custom
pendingURL. The pending type is OPEN. In
addition, the following parameters are
appended and must be communicated to the
shopper:
multibancoReference
multibankoEntity
multibancoPaymentAmount
multibancoPaymentCurrency
For more information about these
parameters, refer to the Alternative
Payment Methods Guide.
Fast Bank Transfers (Redirect)
When you provide fast bank transfer as a payment option, the shopper pays for the goods
and services by making a bank transfer into the account of a participating bank.
The following steps describe a typical payment flow for a fast bank transfer payment:
1. You submit an XML order to WorldPay. The order appears in the MI under Orders.
68
2. WorldPay sends you an XML response. Using the redirect URL contained in the
response, you redirect the shopper to the WorldPay payment pages.
3. At the WorldPay payment pages, the shopper selects Fast Bank Transfer.
WorldPay redirects the shopper to a URL where banks for the shopper's country are
displayed.
4. The shopper selects a bank to which they will transfer money to complete the
payment. At this point, the following occurs:
A payment is created with a status of SHOPPER_REDIRECTED. You can
view the payment in the MI under Payments.
WorldPay redirects the shopper to a URL that displays instructions for
completing the bank transfer.
The instructions contain a unique payment reference that the shopper must reference
when they perform the bank transfer.
To initiate a bank transfer, the shoppers can log into their online bank or manually
complete a bank transfer form at their bank.
You submit fast bank transfer payments in the same way as other APM payments.
For more information about submitting payments using the redirect model, refer to the
Alternative Payment Methods Guide.
Sample XML Response in Sandbox
In the production environment, when you submit an XML order for a fast bank transfer
payment, WorldPay sends an XML response containing a unique payment reference and
other payment details. The XML response in Sandbox contains a test version of the unique
payment reference as well as other payment details. The following XML code shows a
sample XML response provided in Sandbox.
<paymentService version="1.4" merchantCode="XXXX">
<reply>
<orderStatus orderCode="Fast_Bank_Transfer_Example">
<reference id="2525676008">WTEST1136612</reference>
<paymentAmount>100</paymentAmount>
<paymentCurrency>GBP</paymentCurrency>
<orderAmount>100</orderAmount>
<orderCurrency>GBP</orderCurrency>
</orderStatus>
</reply>
</paymentService>
In this example, the unique payment reference is WTEST1136612.
In the production environment, never give shoppers a Sandbox test payment
reference. Providing shoppers with this reference can result in the loss of live
69
payments.
To submit a fast bank transfer payment in Sandbox:
Redirect integration > Fast bank transfer
Step
Action
Result
1.
the payment method code for
the bank is specified.
Payment
2.
3.
70
payment outcome of Pending
- Open from the Payment
Outcome list.
Payment
Click Close window.
Payment status=PENDING_OPEN.
payment details page. The payment
details page displays the unique
payment reference and other order
details. It also provides instructions
to the shopper on how to complete
the payment.
Messaging
China Union Pay (Redirect)
China Union Pay is currently supported for the redirect model only.
In the production environment, there are two payment statuses associated with China Union
Pay:
AUTHORISED
Indicates that WorldPay has received notification from China Union Pay that the
payment has been authorised.
An authorised payment outcome is the only payment outcome WorldPay receives
from China Union Pay. Any other outcome is represented by a lack of response from
China Union Pay.
REFUSED
Indicates that two hours have elapsed since the order was submitted and WorldPay
has not received an authorisation notification from China Union Pay.
After two hours, if WorldPay does not receive an AUTHORISED payment outcome
from China Union Pay, it sets the payment status to REFUSED.
Confirming That a Payment Is Authorised
In the production environment, China Union Pay informs WorldPay when a payment has
been authorised. WorldPay then sets the payment status to AUTHORISED and sends an
order notification to you.
You can confirm that the payment has reached the AUTHORISED status when you
have received an AUTHORISED order notification.
Redirecting the shopper to the successURL without a MAC is not a secure
confirmation that the payment has reached an AUTHORISED state.
It is strongly recommended that you use order notifications. For more information,
refer to the Order Notifications Guide.
71
Testing China Union Pay Payments in Sandbox
Testing China Union Pay Payments in Sandbox
There are two ways to specify the payment outcome for China Union Pay test orders. You
can:
Select an outcome from the simulator.
Specify an outcome using a magic value.
Simulator
The simulator is displayed when you submit an order that does not contain a magic value.
When the simulator is displayed, you can select one of the following values:
Authorised
After you select Authorised, your browser is redirected to a successURL.
Verification using a Message Authentication Code (MAC) is not supported
for China Union Pay.
Not authorised
After you select Not authorised, your browser is redirected to a NotAuthorisedURL.
This URL appears in the Sandbox test environment only. It does not occur in the
production environment. The payment status remains SHOPPER_REDIRECTED for
two hours, at which point it changes to REFUSED.
Magic Values
You can use a magic value to specify a desired payment outcome for a China Union Pay test
order.
To use a magic value, enter it in the lastName element of the billing address in the XML
order code. The following two magic values are available for China Union Pay:
AUTHORISED
REFUSED
Each magic value corresponds to the like-named payment status.
When you use a magic value, the simulator is bypassed. In addition, when you use the
REFUSED magic value, Sandbox changes the payment’s status from
SHOPPER_REDIRECTED to REFUSED in real time, bypassing the standard two-hour
waiting period.
Magic values are not case sensitive.
The following table shows the payment outcomes you can select and the corresponding
result URLs and payment statuses for China Union Pay:
72
Simulator
Magic value
Result URL
Payment status
Authorised
AUTHORISED
successURL
AUTHORISED
Not authorised
REFUSED
NotAuthorisedURL
SHOPPER_REDIRECTED
moves to REFUSED
Authorised Outcome
Redirect integration > China Union Pay > Simulator > Authorised outcome
Step
Action
Result
1.
Payment
Messaging
2.
payment outcome of
Authorised from the
result URL.
generated, if
configured in the
Merchant Interface.
73
Not Authorised Outcome
Redirect integration > China Union Pay > Simulator > Not authorised outcome
Step
Action
Result
1.
Payment
Messaging
2.
payment outcome of Not
authorised from the
Payment
NotAuthorisedURL.
Note: The NotAuthorisedURL is for
testing purposes only. It does not
appear in the production
environment.
After two hours, if the payment has
not reached the AUTHORISED
status, the payment’s status is
changed from
REFUSED.
A REFUSED order
notification is
generated, if
configured in the
Merchant Interface.
Submitting an Order Using Magic Values
Authorised Outcome
When a magic value is used, the simulator is bypassed. Magic values are not case sensitive.
Redirect integration > China Union Pay > Magic value > Authorised outcome
Step
Action
Result
Messaging
1.
Ensure:
AUTHORISED.
generated, if
configured in the
Merchant Interface.


74
The APM is specified.
The lastName
element of the billing
address contains the
AUTHORISED magic
value.
successURL.
Not Authorised Outcome
When you use the REFUSED magic value, the following takes place in Sandbox:
The simulator is bypassed.
The payment status is moved to REFUSED in real time. (The two-hour delay is
bypassed in Sandbox.)
Your browser is redirected to a failureURL.
Redirect integration > China Union Pay > Magic value > Not authorised outcome
Step
Action
Result
Messaging
1.
Ensure:
Payment status is moved from
REFUSED.
A REFUSED order
notification is
generated, if
configured in the
Merchant Interface.
The APM is
specified.
failureURL.
The lastName
element of the
billing address
contains the
REFUSED magic
value.
eNETS (Redirect)
Shoppers can use the eNETS alternative payment method (APM) to make internet purchases
through the direct debit of their savings or current accounts (with participating banks).
eNETS is supported for the redirect model only.
The following steps describe a typical payment flow for eNETS. In this example, the payment
is authorised.
1. You submit an XML order to WorldPay. The order appears in the MI under Orders.
2. WorldPay sends you an XML response. Using the redirect URL contained in the
response, you redirect the shopper to the WorldPay payment pages.
3. At the WorldPay payment pages, the shopper selects eNETS Debit.
4. WorldPay redirects the shopper to eNETS. eNETS initiates the steps for the shopper
to make the payment. Once the payment has been completed, eNETS redirects the
shopper back to WorldPay.
5. WorldPay requests the transaction outcome from eNETS. At this point the following
occurs:
75
A payment is created with a status of SENT_FOR_AUTHORISATION. You
can view the payment in the MI under Payments.
6. WorldPay receives the transaction outcome from eNETS.
The payment status changes to AUTHORISED.
WorldPay sends an order notification, if configured for your account.
Payment Statuses
In the production environment, the following payment statuses are supported for eNETS:
No status available
During the shopper journey, when the shopper is redirected to eNETS, the
transaction does not yet attain a payment status. A payment is created when
WorldPay receives a payment outcome from eNETS.
If the shopper cancels the order before the order has received a payment status, the
shopper is redirected to the pending result URL.
WorldPay has requested the transaction outcome from eNETS. This is the first
payment status for an eNETS transaction. This payment appears in Payments in the
MI.
AUTHORISED
WorldPay has received notification from eNETS that the payment has been
authorised. WorldPay receives a pay-in notification.
REFUSED
The request for payment authorisation has been refused. A possible reason for
refusal is an insufficient balance. A REFUSED payment status is not likely to occur.
Instead, the shopper may be given the option to select another bank.
eNETS does not support a PENDING payment status.
76
Result URLs
The following table shows the payment statuses for eNETS and the corresponding result
URLs, where applicable.
Payment status
Result URL
Notes
There is no result URL for this payment status.
AUTHORISED
successURL
REFUSED
failureURL
pendingURL
When a shopper cancels a transaction that has
not yet attained a payment status, the shopper's
browser is redirected to the pending result URL.
There is no payment status associated with this
event.
Testing eNETS Payments in Sandbox
Initial Steps
Step
Action
Result
1.
Optionally provide the
payment method mask
ENETS-SSL.
simulator is displayed.
Messaging
Go to step 2 for one of the desired
transaction outcomes below.
1a
1b.
information and click
Submit.
Go to step 2 for one of the
desired transaction
outcomes.
77
Payment Outcomes
Authorised Outcome
Redirect integration > EPS > Authorised outcome
Step
Action
Result
Messaging
2.
payment outcome of
Authorised from the
The payment has the following statuses:
An order
notification is
generated for the
AUTHORISED
payment status, if
configured in the
Merchant Interface.


AUTHORISED
Your browser is redirected to the
successURL.
If a Message
Authentication
Code (MAC) is
used, a secure
‘authorised’
message is
appended to the
shopper redirect
URL.
Pending Outcome
Redirect integration > EPS > Pending outcome
Step
Action
Result
Messaging
2.
payment outcome of Pending
from the Payment Outcome
list.
pendingURL.
Refused Outcome
Redirect integration > EPS > Refused outcome
Step
Action
Result
Messaging
2.
payment outcome of
Refused from the
The payment has the following statuses:
An order
notification is
generated for the
REFUSED
payment status, if
configured in the
Merchant Interface.


REFUSED
failureURL.
78
EPS (Redirect)
The EPS alternative payment method is a real-time bank transfer service. During the
payment journey, the shopper logs into online banking and completes a bank transfer. The
payment is authorised in real time.
The following steps describe a typical payment flow for EPS. In this example, the payment is
authorised.
1. You submit an XML order request to WorldPay. WorldPay sends an XML response
that contains a redirect URL to the WorldPay payment method selection page.
2. You extract the redirect URL and redirect the shopper to the WorldPay payment
method selection page. The shopper selects EPS.
3. WorldPay redirects the shopper to a summary page that displays the order code for
the order. This page is hosted by WorldPay.
Figure: Summary page
The shopper clicks Submit on the summary page. At this point the following occurs:
A payment request is created with a status of SHOPPER_REDIRECTED.
WorldPay redirects the shopper to the bank selection page hosted by EPS.
4. At the bank selection page, the shopper selects the bank from which they want to
transfer money. Then the shopper logs into online banking, where they are
authenticated. They select the bank account they wish to pay from and confirm the
payment.
5. The bank confirms the payment to EPS. EPS sends confirmation to WorldPay. At this
point the following occurs:
WorldPay returns a successURL.
The payment status changes from SHOPPER_REDIRECTED to
AUTHORISED.
WorldPay sends you an order notification of the payment status, if you have
opted to receive notifications.
Testing EPS Payments in Sandbox
This section covers the following topics about testing EPS payments:
Pages Displayed During Testing
Selecting a Payment Outcome
Characteristics of EPS Payments
79
Pages Displayed During Testing
As part of the test payment flow for EPS, Sandbox displays the following pages requiring your
interaction.
Payment method selection page
Sandbox displays the payment method selection page where you can select EPS.
This page is bypassed if you append a payment method mask for EPS (EPS-SSL) to
your initial order.
Summary page
The summary page displays the order code for the order and indicates that EPS is
the payment method. To continue the payment process, click Submit.
Simulator
This page simulates the generation of a payment outcome. You can select from the
following three possible payment outcomes: Authorised, Pending, Refused.
Selecting a Payment Outcome
In Sandbox, you can simulate a payment outcome by selecting it from the simulator. The
following table shows the three possible payment outcomes and the corresponding result
URLs and payment statuses.
Payment
outcome
Result URL
Payment status
Payment status description
Authorised
successURL
AUTHORISED
The payment was successful.
Pending
pendingURL
SHOPPER_REDIRECTED
WorldPay cannot confirm the
payment and is waiting for you
or the financial institution to
receive information about your
payment.
Refused
failureURL
REFUSED
The payment has been refused
by the financial institution.
The following figure shows the Sandbox simulator.
80
Figure: Sandbox simulator
Characteristics of EPS Payments
The EPS alternative payment method (APM) differs from other APMs as follows:
Additional parameters are not appended to the pendingURL.
For more information about result URLs, see Payment Outcomes and Result URLs.
This section provides the steps for submitting a test order for EPS.
Initial Steps
Step
Action
Result
1.
Optionally provide the
payment method mask EPSSSL.
If the payment method mask is
appended, the summary page for
EPS is displayed. Go to Step 1b.
Messaging
Otherwise, click the redirect URL to
display the payment method
selection page.
1a.
If the payment method
selection page is displayed,
select EPS.
A summary page for EPS is
displayed.
1b.
At the summary page, click
Submit.
Payment
Go to step 2 for one of the
desired transaction
outcomes.
Go to Step 2.
81
Payment Outcomes
You can select one of the following payment outcomes from the simulator:
Authorised
Pending
Refused
Authorised Outcome
Redirect integration > EPS > Authorised outcome
Step
Action
Result
Messaging
2.
Authorised from the
If a Message
Authentication Code
(MAC) is used, a
message is appended
URL.
result URL.
generated for the
AUTHORISED
payment status, if
configured in the
Merchant Interface.
Pending Outcome
Redirect integration > EPS > Pending outcome
Step
Action
Result
2.
Pending from the Payment
Outcome list.
Payment
pendingURL.
82
Messaging
Refused Outcome
Redirect integration > EPS > Refused outcome
Step
Action
Result
Messaging
2.
Outcome list.
If a Message
Authentication Code
(MAC) is used, a
secure signature is
appended to the
shopper redirect URL.
failureURL.
generated for the
REFUSED payment
status, if configured in
the Merchant
Interface.
GiroPay (Redirect)
Overview
GiroPay lets shoppers pay for online goods and services using direct online transfers from
their bank accounts.
Authorised Outcome
Redirect integration > GiroPay > Authorised outcome
Step
Action
Result
1.
Ensure the APM is specified.
required and is provided with the order
or if no additional information is required
for the APM, the payment status is set
as follows:
Messaging
Payment
Go to Step 2.
order, an intermediate data collection
page is displayed.
83
Redirect integration > GiroPay > Authorised outcome
Step
Action
1a.
Submit.
Result
Messaging
An order
notification is
generated, if
configured in the
Merchant
Interface.
Go to Step 2.
2.
payment outcome of
Authorised from the
successURL.
If a Message
Authentication
Code (MAC) is
used, a secure
‘authorised’
message is
appended to the
shopper redirect
URL.
Refused Outcome
Redirect integration > GiroPay > Refused outcome
Step
Action
Result
1.
Ensure the APM is specified.
required and is provided with the order
of if no additional information is required
for the APM, the payment status is set
as follows:
Payment
Go to Step 2.
order, an intermediate data collection
page is displayed.
1a.
84
Messaging
Redirect integration > GiroPay > Refused outcome
Step
Action
Result
Messaging
Submit.
Go to Step 2.
2.
payment outcome of
Outcome list.
failureURL.
Authorising APM Test Payments (Direct and Redirect)
You can simulate the authorisation of a payment immediately in Sandbox. Simulating
authorisation in Sandbox can help you speed up your testing. For example, you might choose
a Pending payment outcome from the Sandbox simulator to simulate the delay caused when
a shopper settles a payment at an outlet. To authorise the test payment immediately, you can
use the Authorise button in the test version of the Merchant Interface (MI).
You can use the Authorise button for payments that have a payment status of
SHOPPER_REDIRECTED. In addition, they must fall into one of the following four APM
categories:
Real-time hybrid
Delayed hybrid
Real-time non-hybrid
Delayed non-hybrid
For more information on the four categories of APMs, see About Testing APMs.
Authorising an APM Test Payment
1. In the test MI, go to Payments.
2. Select the transaction ID for a payment that has a status of
SHOPPER_REDIRECTED.
3. Under Payment Authorisation Simulation, click Authorise. When the dialog box
asks whether you want to authorise the payment, click OK. The payment status
changes to AUTHORISED.
85
Capturing APM Test Payments (Direct and Redirect)
In Sandbox, there are two ways to capture payments made using alternative payment
methods (APMs):
Automatic background process
A background process runs every 15 to 30 minutes and captures APM payments that
have reached a payment status of AUTHORISED. Captures of APM payments take
place in this way in the production environment.
Immediate capture using bulk capture
You can use the bulk capture feature in Sandbox to capture APM payments
immediately. Use this feature to bypass the 15-to-30 minute wait before the
background capture process runs. Bulk capture is available in the test Merchant
Interface (MI).
Bulk capture is a Sandbox only feature. In tests it allows you to quickly
change the payment status from AUTHORISED to CAPTURED. Bulk
capture is NOT present in the live system.
Capturing Payments Using Bulk Capture
To capture a payment using bulk capture:
1. In the test MI, click Payments and then click Bulk Capture. Any APM payments that
have a status of AUTHORISED are displayed in the list of payments.
2. Select the check boxes for the payments that you would like to capture. Then click
Capture. The status of the selected payments changes immediately from
AUTHORISED to CAPTURED.
3. To view all payments, click Payments.
To verify that a payment has reached the CAPTURED state, you can do either of the
following:
Check the Merchant Interface (MI).
Look at one of the following fields for a status of CAPTURED:
Under Payment Details, check the status field.
Under Payment history, check the Event Type field.
Check your order notifications.
Confirm that your system is able to securely determine that the payment has reached
CAPTURED status by accepting and acknowledging the WorldPay order notification
message.
86
Settling APM Test Payments (Direct and Redirect)
To help reduce testing time, you can simulate the immediate settlement of funds for APM test
payments. A payment with the status SETTLED is ready to be paid out.
In the production environment, WorldPay settles funds according to your settlement cycle. In
Sandbox, however, you can use the Simulate settlement button in the test Merchant
Interface to settle an APM payment immediately.
You can settle APM test payments that have one of the following payment statuses:
CAPTURED
SENT_FOR_REFUND
For more information on payment statuses, see Payment Statuses.
Settlement Currencies
In the production environment, the payment service provider (PSP) settles the payment to
WorldPay in the WorldPay settlement currency. WorldPay then transfers the funds to you in
the merchant settlement currency. In Sandbox, the default merchant settlement currency is
Euros.
Settling an APM Test Payment
To settle an APM test payment:
1. In the test MI, go to Payments.
2. Select the transaction ID for a payment that has a status of CAPTURED OR
SENT_FOR_REFUND.
3. Under Payment settle simulation, click Simulate settlement. When the dialog box
asks whether you want to reconcile this payment, click OK.
The payment status changes from either CAPTURED or SENT_FOR_REFUND to
SETTLED.
For more information about refunding APM test payments, see About Refunding APM Test
Payments (Direct and Redirect).
87
Refunding APM Test Payments
About Refunding APM Test Payments (Direct and Redirect)
You can test the refund of payments made using alternative payment methods (APMs). You
can refund a payment that has a payment status of SETTLED.
Types of Refunds in Sandbox
Sandbox supports two types of refunds:
Automatic refunds
You can use automatic refunds in Sandbox to initiate and complete refunds for some
alternative payment methods (APMs). With automatic refunds, you do not need to
manually enter additional shopper information as part of the refund process. In the
production environment, when the automatic refund is completed, the refund
payment is transferred directly to the shopper's ewallet or account.
To see if an APM is eligible for automatic refunds, see Sandbox APM Features at a
Glance.
For more information on using Sandbox to test automatic refunds, see Automatic
Refunds.
Bank transfer refunds
Bank transfer refunds require the manual entry of some shopper data as part of the
refund process. Use the bank transfer refund method to refund an APM payment
when:
The payment method does not support automatic refunds.
The payment method supports automatic refunds, but attempts to refund the
payment using this method have failed.
Shopper details have not been saved in the system.
You can initiate and complete bank transfer refunds in Sandbox.
To see which APMs can only be refunded through bank transfers, see Sandbox APM
Features at a Glance.
for more information on using Sandbox to test bank transfer refunds, see Bank
Transfer Refunds.
Common Characteristics
For both types of refunds, you can test the following:
Full refunds, partial refunds and multiple partial refunds.
Order notifications for the SENT_FOR_REFUND and REFUNDED statuses, if order
notifications are set up.
88
Refunding a Payment Made in a Different Currency
As in the production environment, if you are refunding a payment that was made in a
currency that is different from your settlement currency, the appropriate exchange rate is
applied when the amount is refunded. The refund amount might therefore be higher or lower
than the original payment.
Automatic Refunds
You can test the automatic refunds of payments made with alternative payment methods
(APMs). With automatic refunds, you do not need to manually enter additional shopper
information as part of the refund process.
In Sandbox, you can initiate and complete automatic refunds. You can test full refunds, partial
refunds and multiple partial refunds.
In the production environment, you can request an automatic refund, but you
cannot complete the refund yourself.
If you support China Union Pay payments, you can test a scenario in which a refund request
fails.
For a list of APMs that support automatic refunds, see Sandbox APM Features at a Glance.
Payment Flow
Sandbox supports the following payment flows for automatic refunds:
AUTHORISED > CAPTURED > SETTLED > SENT_FOR_REFUND > REFUNDED
AUTHORISED > CAPTURED > SENT_FOR_REFUND > SETTLED > REFUNDED
Use Sandbox's Simulate settlement feature to immediately change the status of a payment
from SENT_FOR_REFUND to REFUNDED. This feature is available in the test Merchant
Interface. For the procedure, see Testing Automatic Refunds Using the Test Merchant
Interface (MI).
Methods for Performing Automatic Refunds
Sandbox supports the following methods for refunding APM payments:
Merchant Interface (MI). You can use the test Merchant Interface (MI) to initiate and
complete the automatic refund of APM test payments.
Order modifications. You can use order modifications to request the automatic
refund of APM test payments.
Testing Automatic Refunds Using the Test Merchant Interface (MI)
This section provides the procedure for testing an automatic refund using the test MI.
89
To refund all or part of a payment in Sandbox:
1. In the test MI, go to Payments. The Payments page displays a list of payments.
2. From the list of payments, click the Transaction ID of a payment that has a status of
SETTLED (or CAPTURED). The Payment and Order Details (Test) window is
displayed.
Figure: Payment and Order Details (Test) window
3. Under Direct Refund, enter the amount to be refunded. You can enter a partial
amount. Then click Refund. When the dialog box asks whether you really want to
refund this payment, click OK.
Under Payment history, the amount specified for refund is shown with a status of
SENT_FOR_REFUND.
Note: You can repeat this step to specify additional partial amounts for refund.
90
4. To complete the refund, click the Transaction ID for the payment to display its
payment and order details. Under Payment settlement simulation, click Simulate
settlement. When the dialog box asks whether you really want to reconcile this
payment, click OK.
The payment status changes as follows, depending on the current status of the
payment:
Current payment status
Payment status after settlement
SETTLED
REFUNDED
CAPTURED
SETTLED and
REFUNDED
Testing Automatic Refunds Using Order Modifications
In Sandbox, you can submit order modifications to request automatic refunds for payments.
As in the production environment, WorldPay sends a response to acknowledge that it has
received the request successfully. In the production environment, WorldPay processes the
order modification offline.
Request
The following sample order modification shows a request for a refund of EUR 1.00.
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTDWorldPay PaymentService v1//EN"
"http://dtd.wp3.rbsworldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="EXAMPLE" version="1.4">
<modify>
<orderModification orderCode="order12345">
<refund>
<amount value="100" currencyCode="EUR" exponent="2"/>
</refund>
</orderModification>
</modify>
</paymentService>
91
Response
Sandbox sends an XML response confirming that the request has been received
successfully.
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD
WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="DEMO">
<reply>
<ok>
<refundReceived orderCode="order12345">
<amount value="100" currencyCode="EUR" exponent="2"
debitCreditIndicator="credit"/>
</refundReceived>
</ok>
</reply>
</paymentService>
For more information, refer to the Refunding Alternative Payments Guide.
Testing Refunds of China Union Pay Payments
You can test both successful and failed refunds for payments made with the China Union Pay
payment method.
Simulating Failed Refunds
The unique payment status REFUND_FAILED can occur with refund requests for China
Union pay payments. This status indicates that the request for a refund has failed. The
REFUND_FAILED status is only valid for payments made with the China Union Pay payment
method.
The following scenario illustrates when the REFUND_FAILED status is triggered:
1. A merchant requests a partial or full refund for a China Union Pay payment. The
payment status changes to REFUND_REQUESTED.
2. After approximately two hours, if WorldPay has not received a response from China
Union Pay, the status of the payment changes from REFUND_REQUESTED to
REFUND_FAILED.
In Sandbox you can simulate this scenario using the Refund failed button, available in the
Merchant Interface.
You can enter a full or partial amount and then click Refund failed. Sandbox changes the
status of the payment from SETTLED (or CAPTURED) to SENT_FOR_REFUND and then
REFUND_FAILED.
To test failed refunds for China Union Pay payments:
1. In the test MI, go to Payments. The Payments page displays a list of payments.
2. From the list of payments, click the Transaction ID of a China Union Pay payment
that has a status of SETTLED (or CAPTURED). The Payment and Order Details
(Test) window is displayed.
92
3. Under Refund failed simulation for CUP, enter a full or partial amount and then
click Refund failed. When the dialog box asks whether you really want to simulate a
refund failed payment, click OK. The status of the payment changes to
SENT_FOR_REFUND and then REFUND_FAILED.
Understanding Merchant Interface Errors for China Union Pay Payments
For China Union Pay payments only, the Merchant Interface (MI) incorrectly displays the
Refund and Refund failed buttons for all payment statuses. These buttons should only be
displayed when a payment has reached a status of CAPTURED or SETTLED.
This error appears in both the production environment and Sandbox.
In the test Merchant Interface, the following errors can occur:
The Refund and Refund failed buttons are incorrectly displayed for the following
payment statuses:
SHOPPER_REDIRECTED
AUTHORISED
If you request a refund or simulate a failed refund at one of these states, the attempted
action fails. The following error message appears:
FAILURE: Refund amount is too high

The interface incorrectly allows you to request a refund or simulate a failed refund
when the payment amount is zero (0). If attempted, both actions fail. Sandbox
displays the following error message:
FAILURE: Cannot refund zero amount.
In both instances, you can click a link to return to the Payment and Order Details (Test) page.
Bank Transfer Refunds
You can test the bank transfer refund of payments made with alternative payment methods
(APM).
About Bank Transfer Refunds in the Production Environment
When you request a refund by bank transfer, you need to enter shopper bank account
information manually. Use bank transfer refunds to initiate the refund of APM payments that
do not support refunds. You can also use bank transfer refunds when:
The required shopper information has not been saved in the payment system.
The payment service provider supports automatic refunds but attempts to refund a
payment using this method have failed.
In the production environment, you can request a bank transfer refund using the Merchant
Interface (MI). Order modifications cannot be used to initiate bank transfer refunds. Bank
transfer refunds can be performed when APM payments have reached a status of
CAPTURED or SETTLED.
93
For more information about initiating bank transfer refunds in the production environment,
refer to the Refunding Alternative Payments Guide.
About Bank Transfer Refunds in Sandbox
This section explains two scenarios for bank transfer refunds and shows you how to test for
each.
Bank Transfer Refund Scenarios
Sandbox gives you the option to test two scenarios for bank transfer refunds. Both relate to
the manual entry of shopper bank account information. You can simulate a scenario where:
Valid shopper information is manually entered.
In this scenario, WorldPay accepts your refund instructions. The payment status
moves from SETTLED (or CAPTURED) to SENT_FOR _REFUND.
Invalid shopper information that is manually entered.
In this scenario, the refund fails. The payment status moves from SETTLED (or
CAPTURED) to SENT_FOR_REFUND and then immediately to REFUND_FAILED.
In Sandbox, these two statuses occur very quickly; in the live system there is a time
delay.
The following payment status flows show two possible scenarios for APM bank
transfer refunds in Sandbox. In this example, the payment has reached a status of
SETTLED.
94
Figure: Possible payment statuses in Sandbox for bank transfer refunds of APM
payments
To see which APMs can be refunded through bank transfers only, see Sandbox APM
Features at a Glance.
Sandbox Features for Testing Bank Transfer Refunds
To test bank transfer refunds, you can use the Refund simulator, available in the test
Merchant Interface (MI).
To access the simulator:
1. Go to the Payments (Test) page and display the details for a payment.
2. Under Refund by Bank Transfer, enter a full or partial amount to be refunded and
then click BT Refund.
The Refund simulator is displayed. It provides the following options:
/
You can click the Valid bank account or the Invalid bank account button to
simulate the correct or incorrect entry of the shopper's bank account details,
respectively.
Repeat simulations
You can click the Valid bank account or Invalid bank account buttons
95
more than once during the refund process.
For example, to simulate the incorrect entry of the shopper's bank account
details twice, first click Invalid bank account. Then, to simulate another
failed attempt, click it again. Finally, you can click Valid bank account to
simulate the correct entry of the shopper's bank account details. For each of
the failed and successful attempts, Sandbox updates the payment's status
accordingly.
The following figure shows possible payment flows during a bank transfer refund. In this
example, the payment has reached a status of SETTLED before a bank transfer refund is
initiated.
Figure: Payment flows for valid and invalid bank account details
96
The figure illustrates both of the following scenarios:
Valid bank account details entered
When valid bank account details are entered, the payment status changes to
SENT_FOR_REFUND. Sandbox sends an HTTP or email notification, if configured
for your account.
If desired, you can immediately perform another valid bank account simulation. For
example, you might need to make a second refund for a partial amount. Each time
you click Valid bank account, another payment status of SENT_FOR_REFUND is
generated.
Invalid bank account details entered
When invalid bank account details are entered, the payment status changes
immediately to SENT_FOR_REFUND and then REFUND_FAILED. Sandbox sends
an HTTP or email notification for the SENT_FOR_REFUND status, if configured for
your account.
If desired, you can immediately perform another invalid bank account simulation. For
example, the shopper's payment details might be entered incorrectly on the first
attempt. Sandbox generates the SENT_FOR_REFUND and REFUND_FAILED
statuses. If the second attempt is also incorrect, Sandbox again generates the same
pair of statuses. Each time you click Invalid bank account, a pair of
SENT_FOR_REFUND and REFUND_FAILED payment statuses is generated.
In the production environment, refund notifications are not issued
immediately after a refund has failed. There might be a delay, depending
on how soon the payment service provider (PSP) or bank notifies
WorldPay and the reversal is received.
Testing Bank Transfer Refunds in Sandbox
To request a bank transfer refund in Sandbox:
1. In the test MI, go to Payments. The Payments page appears.
2. From the list of payments, click the Transaction ID of a payment. The Payment and
Order Details (Test) window is displayed.
3. Under Refund by Bank Transfer, enter the amount to be refunded. You can enter a
partial amount. Then click BT Refund. The Refund simulation (Test) page is
displayed.
4. To simulate the entry of shopper information, do one of the following:
To simulate the entry of valid shopper information, click Valid bank account.
The status of the payment is changed from SETTLED (or CAPTURED) to
SENT_FOR_REFUND. You are returned to the Payments (Test) page.
Note: Standard refund charges apply to bank transfer refunds.
To simulate the entry of invalid shopper information, click Invalid bank
account. The status of the payment is changed from SETTLED (or
97
CAPTURED) to SENT_FOR_REFUND and REFUND_FAILED. The error
message ERROR: Refund failed is displayed under the page title.
To view details about the payment, do one of the following:
To view the payment details, click Cancel. The Payment Details Test page is
displayed.
To return to the Payments page, click Payments.
5.
Optionally repeat Steps 3 and 4 as needed.
Tracking Refunds
You can track the progress of refunds for test payments made using alternative payment
methods (APMs). To track refunds in Sandbox, you can check:
Test Merchant Interface (MI)
Order notifications
Reports are currently not available in Sandbox.
Test Merchant Interface (MI)
The test MI keeps an ongoing record of a payment's statuses, including statuses about
refunds, under Payments. For more information about payment statuses, see Payment
Statuses.
Order Notifications
If configured, you can receive email or HTTP notifications for the following statuses
associated with refunds: SENT_FOR_REFUND, REFUNDED. You can configure order
notifications in the test Merchant Interface under Profile > Merchant Channel. For more
information, see the User Management Guide.
98
Testing Your Integration
Interaction
Your business model and setup with us may see different types of interaction with customers.
We recommend testing all possible integration types you have with us to ensure you are
satisfied with your connection, setup and the processes you have integrated with WorldPay.
The most common integration types are:
Ecommerce
Standard online credit card payments from your webshop.
Alternative payment methods
Used as an alternative to credit card payments. They often cater to regional customer
payment preferences. Examples are e-wallets, real-time bank transfers, vouchers
and prepaid cards.
MOTO
Mail Order/Telephone Order (MOTO) payments include payments made via
telephone, post, fax or similar channels that require no online or physical presence of
your customer.
Recurring (Pay as Order)
Payments that see the same card debited again without any further cardholder
interaction. Examples include subscription services or ‘debit same card as before’
services.
Shopper Experience
To ensure the quality standards of the shopper experience you offer, we suggest you verify
the end-to-end shopping experience of your customers. This will depend mostly on your
customer base and business model and we have listed some of the more frequent
experience aspects:
Standard online
A standard payment through your website.
Devices and browsers
We suggest testing on various devices and browsers. For example, include both
tablets and smart phones in our testing. We recommend testing the most popular
internet browsers: MS Internet Explorer, Mozilla Firefox and Google Chrome. Testing
for iPhones can be equally important, as well as a selection of various Android smart
phones. Tablets and the various games machines are also increasingly popular with
consumers.
Demographic
You know your customers and their shopping behaviour. Some websites find it useful
to differentiate not only by target customer group, but also by website user
demographic, for example, age, timing or location. For more details on online
shopping behaviour, please visit our online shopper report:
http://www.worldpay.com/globalshopper
99
Products
One payment might involve the integration of multiple products and it is advisable to test
them in isolation and in combination with each other. Some of the WorldPay products you
might make use of are listed below - you might of course also subscribe to different products
with us.
Merchant Interface (MI)
Hosted Call Centre
Risk Management Module
RiskGuardian
Pay As Order
Multi-Currency Processing (Forex)
Payment methods, cards
Payment methods, alternative payment methods
Call Back
Batch processing
100
Appendix
Appendix
Test Card Numbers
You can use the following card numbers to test transactions in Sandbox. When using test
cards, you can specify an expiry date up to seven years in the future. The test cards do not
have a card verification code or issue number.
Card Type
Card Number
Airplus
122000000000003
American Express
34343434343434
Cartebleue
5555555555554444
Dankort
5019717010103742
Diners
36700102000000
36148900647913
Discover card
6011000400000000
JCB
3528000700000000
Laser
630495060000000000
630490017740292441
Maestro
6759649826438453
6799990100000000019
Mastercard
5555555555554444
5454545454545454
Visa
4444333322221111
4911830000000
491761000000000
Visa Debit
4462030000000000
4917610000000000003
Visa Electron (UK only)
4917300800000000
Visa Purchasing
Note: Visa Purchasing
transactions are treated
as Visa credit card
transactions.
4484070000000000
101
German ELV
To test German ELV payments in the test environment, a correctly formatted account number
(Kontonummer) and valid bank code (Bankleitzahl) should be used, for example:
Account number: 12345678
Bank code: 10000000
Bank name: Bundesbank
Bank residence: Berlin
Payment
Method
Bank Code
Account
Number
ELV
20030000
92441196
ELV
43050001
122108525
ELV
30070024
5929120
ELV must be activated in the production environment before you can test
ELV transactions.
102
Sandbox APM Features at a Glance
This table shows features supported in Sandbox for each alternative payment method (APM).
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
Abaqoos
Real-time hybrid
Alipay
Real-time hybrid
AstroPay Card
Real-time hybrid
Baloto
BankAxess
Delayed hybrid
Real-time hybrid
103
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
Banklink
NORDEA
Real-time hybrid
Boleto
Delayed hybrid
CashU
Real-time hybrid
China Union Pay
Other payment method
DineroMail
(OLBT)
Delayed hybrid
DineroMail
OXXO
Delayed hybrid
104
Appendix
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
DineroMail
(Servipag)
Delayed hybrid
DineroMail
7eleven
Delayed hybrid
eKonto
Delayed hybrid
eKonto
Real-time hybrid
ePay
Delayed hybrid
eNETS
105
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
EPS
EUteller
Real-time hybrid
eWireDK
Real-time hybrid
eWireNO
Real-time hybrid
eWireSE
Real-time hybrid
Fast bank
transfers
Delayed Non-hybrid
106
Appendix
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
Giropay
InstaDebit
Real-time hybrid
Konbini
Delayed hybrid
Mister Cash
Real-time hybrid
Moneta
Real-time Non-hybrid
MultiBanco
Delayed Non-hybrid
107
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
NeoSurf
Real-time hybrid
Paga Wallet
Real-Time hybrid
Paysafecard
Real-time hybrid
POLi
Real-time hybrid
POLiNZ
Real-time hybrid
PostePay
Real-time hybrid
108
Appendix
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
Przelewy24
Real-time hybrid
Przelewy24
Delayed hybrid
Qiwi
Real-time hybrid
Qiwi
Delayed hybrid
SafetyPay
Real-time hybrid
SafetyPay
Delayed hybrid
109
Authorise
APM Name
button
available
in MI
Autorefunds
supported
Bank
transfer
refunds
supported
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
SOFORT
Banking
Real-time hybrid
Sporopay
Real-time hybrid
TeleIngreso
Delayed hybrid
ToditoCash
Real-time - Non-hybrid
TrustPay (CZ,
EE, SK)
Real-time hybrid
WebMoney
Real-time hybrid
110
Appendix
Authorise
APM Name
button
available
Autorefunds
supported
Bank
transfer
refunds
supported
in MI
Yandex.Money
Intermediate
Data
Collection
Page
available
Conditional
APM
Redirect
model
only
APM Type
Real-time hybrid
* For this APM, Sandbox does not have functionality for refunds.
111

WorldPay Sandbox User Guide

Transcription

Similar documents

High Voltage Maintenance

Social Clienteling

where`s my refund?

Gunwharf Quays Leasing Brochure

the money lesson - North Alabama Educators CU

Where`s My Refund- ACES Tutorial

Whole Watermelon

floor directory - Veelzijdig Maleisie