Implementing a Browser Payment Integration
Browser payment methods allow a payer to pay for goods and services online on the browser payment provider's website. The Mastercard Gateway redirects the payer's browser to the browser payment provider's website where the payer logs in, selects the card details, reviews the payment, and completes the interaction.
The Mastercard Gateway supports the following browser payment methods:
- Alipay
- Bancontact
- Boleto Bancário
- iDEAL
- Klarna Financing
- Klarna Pay Later
- Klarna Pay Now
- Multibanco
- PayPal
- POLi
- SEPA
- UnionPay SecurePay
- WeChat Pay
Prerequisites
To implement browser payments via the Mastercard Gateway, you need:
- An account with the browser payment provider.
- A page on your shop site to which the Mastercard Gateway returns the payer's browser on completing the interaction.
It is recommended that you subscribe to the Notifications service to receive notifications (email/Webhook) if the payment is successful. The Mastercard Gateway (on behalf of you) can also send email notifications to the payer.
Browser Payments through Hosted Checkout integration
If you have an existing Hosted Checkout integration, the browser payment method will automatically be available once your payment service provider has successfully configured your merchant profile on the Mastercard Gateway with the acquirer link for the browser payment provider.
The following diagram illustrates the browser payment flow in a Hosted Checkout model:
- You initiate a Hosted Checkout interaction when the payer is ready to checkout at your shop site. The Mastercard Gateway displays the payment interface as chosen by you: a Lightbox or Hosted Payment Page.
- The payer is presented with the payment interface where the browser payment method displays as a payment option.
- When the payer selects the browser payment method, the Mastercard Gateway redirects the payer's browser to the browser payment provider's website to log in and select the payment details or perform the payment.
- Once the payer interaction on the browser payment provider's website is complete, the payer is presented with the payment result via:
- Hosted Receipt: The payment result is displayed on the Hosted Payment Page/Lightbox. This is the default behavior.
- Receipt on Your Shop Site: You can choose to display the payment result to the payer on your shop site. For integration guidelines, see Returning the Payer to Your Shop Site.
The payer can also obtain the result of a successful payment via email notifications sent by the Mastercard Gateway — you must subscribe to payer notifications in Merchant Administration.
Retrieving the transaction result
You can use Merchant Administration or perform a Retrieve Order/Retrieve Transaction operation to find out about the success or otherwise of the payment. See section "How to Interpret the Transaction Result" in the integration page specific to the browser payment.
You can also find out about the success of the payment through your integration (only if you choose to return the payer to your shop site) or via the Notifications service (email/Webhook).
Browser payments through Direct Payment integration
The following diagram illustrates the browser payment flow in a Direct Payment model:
Here are the integration steps for a browser payment via Direct Payment integration:
When the payer selects a browser payment method, perform an Initiate Browser Payment operation to provide information about the order and to obtain the Redirect URL for the browser payment method. You need to provide the following in the Initiate Browser Payment operation request:
order.amount: The amount of the order.order.currency: The currency in which the order is being paid.sourceOfFunds.type: The browser payment method. For example, PAYPAL, UNION_PAY.browserPayment.returnUrl: The Return URL is a page on your website. The payer's browser is redirected to this page on completing the payment at the browser payment provider's website. You may wish to include information in the Return URL to identify the payer order on your website.browserPayment.operation: The type of transaction you want to create when the payer completes the interaction. You have two options:
Authorize— A transaction where the payment is authorized with the payer's underlying funding source(s), but not immediately captured.Pay— A transaction where the payment is authorized and, if successful, immediately captured.
Note that the Mastercard Gateway ignores the privileges configured on your merchant account with the Mastercard Gateway.
PayPal and UnionPay SecurePay support both Authorize and Pay operations; the other browser payment methods (BancaNet) only support Pay.
You may also provide additional details about the order, for example, billing address, shipping address, customer details, etc.
Use the browserPayment.redirectUrl provided in the Initiate Browser Payment response to redirect the payer's browser to the browser payment provider's website.
Once the payer interaction at the browser payment provider's website is complete, the Mastercard Gateway returns the payer's browser back to your shop site using the browserPayment.returnUrl supplied in the Initiate Browser Payment request. Your shop site needs to identify the order through information provided in the return URL.
If you don't get the payer's browser back within an expected time frame, perform a Retrieve Transaction operation (see Step 4) to find out about the status of the interaction and/or success or otherwise of the payment.
After you have received the payer's browser, use Retrieve Transaction to find out about the success or otherwise of the payment.
The Retrieve Transaction response will contain order details, and depending on the payment method, may contain details about the payer as returned by the browser payment provider.
Use the information provided to display the transaction result to the payer. See section "How to Interpret the Transaction Result" in the integration page specific to the browser payment.
If the transaction was not successful, perform Step 1 through to Step 4 again using the same Order ID.
Testing a browser payment integration
For details on how to test the supported browser payment methods, see Testing Browser Payments.
Troubleshooting and FAQs
You can track the progress of a browser payment using the browserPayment.interaction.status field and the respective time fields returned in the Retrieve Transaction/Retrieve Order response.
browserPayment.interaction.status=INITIATEDbrowserPayment.interaction.timeInitiated=<the date and time the payment was successfully initiated is set>browserPayment.interaction.status=REDIRECTED_TO_PROVIDERbrowserPayment.interaction.timeRedirected=<the date and time the payer's browser was received from your shop site and redirected to the browser payment provider's website is set>browserPayment.interaction.status=RETURNED_TO_MERCHANTbrowserPayment.interaction.timeReturned=<the date and time the payer's browser was received from the browser payment provider's website and redirected back to your shop site is set>browserPayment.interaction.status=COMPLETEDbrowserPayment.interaction.timeCompleted=<the date and time the payment was completed is set>
These fields may be useful for troubleshooting purposes.