Fully Hosted Payments Pages Overview

Fully Hosted Payments

The Hosted Payments Service enables the payment process to be performed on a customisable webpage hosted by MasterCard Payment Gateway Services, rather than capturing sensitive card details on a website or call centre application. Using this method of integration will lessen the responsibilty of complying with PCI DSS, as card details are captured from the outset by MasterCard Payment Gateway Services. Payments can be made using Credit cards, Debit cards and PayPal.

There are four stages to the payment, these are outlined below.

  • re-direct customer to MasterCard Payment Gateway Services Hosted Payment Page

  • authorisation

  • query

  • settlement

Re-direction of Customer


Once the customer is ready to proceed to payment, your application sends a request to MasterCard Payment Gateway Services. This include information that has been collected on the customer (from the website or call centre application).
A Hosted Payment Session will be created for that transaction and an XML response returned containting details which are used to re-direct the customer to the Hosted Payment Page.

Authorisation


Once diverted to the MasterCard Payment Gateway Services Hosted Payment Page, the customer is presented with your payment page.

Card Payment

On the MasterCard Payment Gateway Services Hosted Payment Page, the customer is presented with the opportunity to enter their card details.

Once the customer has entered these details, they will be stored by MasterCard Payment Gateway Services. If the transaction has been flagged as an e-Commerce payment and 3-D Secure is required, MasterCard Payment Gateway Services will manage the cardholder authentication process. If the card is enrolled, the Hosted Page will display the Authentication page (ACS) provided by the Issuing Bank. This page enables the card holder to authenticate themselves directly with their Issuing bank before being returned to a pre-determined URL.

If the card is not not enrolled for 3-D Secure or 3-D Secure has not been requested, MasterCard Payment Gateway Services will mangage the payment through to completion and then re-direct the customer to a pre-determined URL.

Once complete, the cardholder is re-directed back to your website.

PayPal

If the customer chooses to pay via PayPal, the Hosted Page will re-direct them to the PayPal website. The customer authenticates themselves and is re-directed back to the Hosted Page to confirm the payment.

Once complete, the cardholder is re-directed back to your website.

Query


To obtain details of the outcome of the payment, your website may send a followup transaction. This will returns details of each payment attempt.

Settlement


Card Payment

To transfer the money between you and your customer, the authorised transaction needs to be settled by your Acquiring Bank.

Each day, MasterCard Payment Gateway Services collate all the completed authorised transactions and submit them to your Acquiring Bank, who then settle the transactions. This process takes place every working day at midnight, which means that transactions are settled next working day.

Your Acquirer will typically take three to five working days to settle the transaction. Please contact your Acquirer for more information regarding settlement times.

PayPal

Once a successful PayPal transaction has been completed, the funds are automatically transfered from the Payer's account into your PayPal merchant account.

Requirements

Before you can go live with the Hosted Payment Service, you will need the following:

  • A MasterCard Payment Gateway Services account

  • Hosted Payment Service configured on the account

  • For payments via Cards - A merchant account or merchant ID (MID) with one of the Acquiring Banks that MasterCard Payment Gateway Services are integrated with, for each currency you wish to trade in.

  • If using PayPal - a PayPal Merchant account and your MasterCard Payment Gateway Services account to be configured for PayPal

  • A valid secure return URL on your website. Once your customer has entered their payment details, they will be re-directed by MasterCard Payment Gateway Services to this URL

  • One or more customised Payment Pages configured on your MasterCard Payment Gateway Services account. A default page will be used if you do not provide a customised one

  • A customised error page configured on your MasterCard Payment Gateway Services account, to be shown if the customer reaches the maximum payment attempts configured on your account

In addition, you may also wish to have:

  • A valid expired return URL on your website. The user will be re-directed by MasterCard Payment Gateway Services to this URL if they have not completed the payment within three hours

Design of Payment Page


The design of the hosted page is fully customisable. Multiple pages may be configured on a single account, enabling the design of pages for different regions and brandings. Pages could be created in languages other than English and can be designed to return specific errors back to the cardholder in that language. The maximum number of payments attempts may also be configured.

Nine place holders are available to show additional information on the payment page. Examples of information commonly displayed on the payment page via a place holder is Cardholder Name or a Call Centre telephone number. Place holder information is provided in the initial XML request to MasterCard Payment Gateway Services.

Transaction Processing Models


There are two types of Transaction Processing Models which can be used to submit payments to MasterCard Payment Gateway Services.

One Stage processing - the transaction is authorised and then settled automatically. If you are using this model, you do not need to contact the MasterCard Payment Gateway Services servers to initiate settlement.

Two Stage processing - the transaction is authorised, but settlement is delayed until you are ready to proceed. If you are using this model, you will need to contact the MasterCard Payment Gateway Services servers twice - once for authorisation and again for settlement.

Each time a Hosted Payment transaction setup is submitted to the MasterCard Payment Gateway, it contains the information that determines the model to be used for that transaction.

In both models, the authorisation of the payment takes place in real time. The difference between each model lies in the settlement process.

Regardless of the transaction model you employ, each session setup request needs to be flagged with the following transaction type:

Transaction Type

Payment Type

Effect

setup_full

All

Passes transaction information to MasterCard Payment Gateway Services and obtains details used to re-direct the customer to hosted page

Once the cardholder has successfully completed the payment, it can be refunded or cancelled if required. This is available to both processing models without additional account configuration.

One Stage Processing


The One Stage model will send transaction details to your Acquiring Bank for settlement on the next settlement day. This process will charge the card holder without requiring any additional action from yourselves.

Situations in which this could be implemented include:

  • Instant access services - such as software downloads

  • Ticketing systems - such as airline and train reservation services

The transaction types that can be used with the one stage model are:

Transaction Type

Payment Type

Effect

auth

Card Payments

Automatically settles successful card transactions next settlement day

PayPal Payments cannot be made as one stage transactions.

Two Stage Processing


The delayed settlement model enables you to settle the transaction at your convenience. The transaction is authorised, but is not automatically settled. Settlement takes place once the second stage has been initiated by your systems.

Situations in which this could be implemented include:

  • Physical goods that will be shipped same day

  • Ordered Items are not currently available

  • Additional in-house processes need to be completed prior to settlement

The transaction types that can be used with the two stage model are:

Transaction Type

Payment Type

Effect

pre

Card Payments

Reserves funds on the card, but does not settle the transaction until a valid fulfill request is received

fulfill

Card Payments

Initiates settlement of a valid pre transaction

set_express_checkout

PayPal

Reserves funds on the paypal account, but does not settle the transaction until a valid do_capture request is received

do_capture

PayPal

Initiates settlement of a valid PayPal transaction

Query Results


Once the cardholder has been redirected back to your website, you will want to know the outcome of the payments attempted within the session. This can be used with both payment models and payment types. The transaction type to use for this is:

Transaction Type

Payment Type

Effect

query

All

Used to determine the overall outcome of the session. Also used to gain detailed information about the individual payment attempts

Once your system has queried the result of the session, you may also query any of the individual payment attempts to determine more details about those transactions.

Cancelling Payments


Transactions may be cancelled before settlement, if required.

For card payments, one stage transactions and completed two stage transactions can be prevented from debiting (or crediting) the card using the cancel transaction type. This will prevent an authorised transaction from being settled and can therefore only be used before the transaction has been settled.

For PayPal payments, this transaction type also releases the remaining reserved funds.

Situations in which this could be implemented include:

  • Customer cancellations - for systems allowing the customer to cancel an order after placement

  • Physical Shipment - if at shipment the goods are found to be damaged, the payment can be cancelled

  • Partial fulfillment (PayPal only) - if only part of the order can be completed

Transaction Type

Payment Type

Effect

do_void

PayPal

Releases reserved funds back to buyers PayPal account

cancel

Card Payments

Stops one stage and completed two stage transactions from being settled

Refunding Transaction


MasterCard Payment Gateway Services provide a specific transaction type to allow successful transactions to be refunded without needing the full card or customer details. This enables refunds to be performed on existing transactions without the need to store the full card details or PayPal user information.

Transaction Type

Payment Type

Effect

txn_refund

All

Uses an existing transaction to returns funds to a card or PayPal user.

The original transaction can either be completely or partially refunded, and multiple refunds can be performed on one transaction until the full value of the transaction has been refunded.

Performing Transactions


Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.

Session setup


To create a HPS session, the following information needs to be sent to MasterCard Payment Gateway Services:

  • a unique reference number generated by your system - to allow the transactions to be distinguished from each other

  • the value and currency of the transaction

  • the transaction type. Each transaction will contain a transaction type of setup_full, and a transaction type for card payments (auth or pre) and PayPal payments (set_express_checkout) if you offer these

  • details about which of the payment pages configured on your MasterCard Payment Gateway Services account you wish to present to the customer

You may also include additional information to use additional services and trigger or enhance various fraudscreening techniques:

  • 3-D Secure

  • Risk

  • Address and Security Code Verification Service

Query


To obtain details of the outcome of the session, your website may send a query transaction:

  • the MasterCard Payment Gateway Services_reference of the original setup transaction

  • method must be query

If the first payment attempt is unsuccessful, the customer may re-attempt payment up the the maximum configured on the account. When performing the query, your website will receive the MasterCard Payment Gateway Services_reference and return code of each payment attempt. To obtain detailed information about these payment attempts, your website may submit a query for each payment attempt.

Completing the Two Stage Process


To settle a card transaction processed using the Two Stage process, a fulfill is needed. To settle a PayPal transaction, a do_capture is needed. This informs MasterCard Payment Gateway Services that you wish to proceed with the transaction. Once this has been done, the card will be charged. Only successful transactions can be fulfilled.

Card Payments

To fulfill a successful payment attempt, information from the result of the query transaction is required, in addition to the transaction type:

  • the MasterCard Payment Gateway Services_reference of the payment attempt

  • the authorisation code

  • the transaction type - fulfill

Transactions are normally fulfilled for the full value of the original transaction. If you wish to perform a partial fulfill, this can be done by specifying theamount in the fulfill request.

Multiple partial fulfill transactions can be submitted against a single pre, if your MasterCard Payment Gateway Services account is configured for Split Shipment.

PayPal Payments

The transfer funds from your customers PayPal account is initiated by your website. This may be performed immediately, or at a later stage:

  • the MasterCard Payment Gateway Services_reference of the original setup_full transaction

  • the transaction type - do_capture

  • the value and currency of the transaction

Multiple partial do_capture transactions can be submitted.

As PayPal accounts can be restricted by the PayPal fraud department at any time, the capture of funds cannot be guaranteed. It is best practise to capture the funds before the goods are shipped and not after.

Refunding Transactions


The txn_refund transaction type uses a successful transaction to perform a refund without requiring the card or PayPal User details.

Any successful auth or completed two stage transaction can be refunded in this fashion.

To txn_refund a transaction, information from the result of the original transaction is required, in addition to the transaction type:

  • the MasterCard Payment Gateway Services_reference

  • the transaction type - txn_refund

Transactions are normally refunded for the full value of the original transaction. If you wish to refund a lower value, this can be done by specifying the amount in the txn_refund request. Each transaction can be refunded several times, provided the total refunded does not exceed the value of the original.

Cancelling Transactions


Card Payments

To cancel a card transaction prior to settlement, the following information is required:

  • the MasterCard Payment Gateway Services_reference

  • the transaction type - cancel

PayPal Payments

To release reserved PayPal funds back to the buyer, a do_void can be performed, with this information:

  • the MasterCard Payment Gateway Services_reference

  • the transaction type - do_void

Response Codes


When using the HPS Service, there are four basic responses for card transactions and two for PayPal transactions:

  • Accepted

  • Declined - for card payments only

  • Referred - for card payments only

  • Error

Accepted Transactions


Once a transaction is accepted, your system can complete the normal ordering process. If you are using the Two Stage model, please remember that the second stage must be completed to complete the payment.

Declined Transactions

Occasionally, you may find a transaction is declined. There are several general reasons why a card may be declined. These include:

  • The card has been cancelled

  • The card is approaching or is past its limit and does not have enough funds to cover the full value

  • The Issuing bank have noticed unusual patterns of spend on the card

If a transaction is declined, the cardholder may re-attempt payment, assuming the re-try limit configured on your account has not been reached.

Referred Transactions


referral response is part way between an accepted and a declined response. The Issuing Bank does not wish to automatically issue an authorisation code, but is providing you with the opportunity to receive a manual authorisation instead of simply issuing a decline response. If a referral response is received, the Hosted Payment System will treat this as a decline, thereby enabling the cardholder to re-attempt the payment, assuming the re-try limit configured on your account has not been reached.

The main reasons for a referral are:

  • the Issuer is performing a spot check

  • the card is approaching its limit

If none of the remaining payment attempts were successful, you may wish to simply treat these transactions in the same way as a decline. This requires no extra action on your part and enables the system to be fully automated. If you wish to proceed with the payment, you should phone the authorisation centre of your Acquiring Bank - not the cardholders bank - with the card details. The authorisation code should then be submitted to MasterCard Payment Gateway Services in order to proceed with the payment.

Error Messages


There are a small number of error messages which can be displayed to the customer. You may vary the text for each of these using Customised Validation Messages. If a transaction generates an error message, the cardholder may re-attempt payment, assuming the re-try limit configured on your account has not been reached.

A complete list of Response Codes for this service is available here. The Hosted Payment System itself can return a various error codes. In addition, each payment type & fraud screening service utilised during the payment also has it's own error codes.

The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate on how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.

These error codes will not be displayed to the customer, but will be available for you to review if a query transaction is submitted, or via Reporting.

Reporting

Card Payments are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:

  • Summary - gives a summary of the transactions

  • List - shows specific details of the transactions

  • Details - shows full details of each transaction

PayPal Payments are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:

  • Summary - gives a summary of the transactions

  • List - shows specific details of the transactions

  • Details - shows full details of each transaction

The Support Centre contains full hints and tips to help you get the most out of Reporting.