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 Payment 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 Payment Gateway supports the following browser payment methods:

Prerequisites

To implement browser payments via the Mastercard Payment Gateway, you need:

  • An account with the browser payment provider.
  • A page on your shop site to which the Mastercard Payment 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 Payment Gateway (on behalf of you) can also send email notifications to the payer.

Browser Payments via 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 Payment Gateway with the acquirer link for the browser payment provider.

Boleto Bancário, OXXO, SEPA, paysafecard, PayU, and WeChat Pay are currently not supported via Hosted Checkout integration.

The following diagram illustrates the browser payment flow in a Hosted Checkout model:

Browser Payments Workflow for Hosted Checkout

  1. You initiate a Hosted Checkout interaction when the payer is ready to checkout at your shop site. The Mastercard Payment Gateway displays the payment interface as chosen by you: a Lightbox or Hosted Payment Page.
  2. The payer is presented with the payment interface where the browser payment method displays as a payment option.
  3. When the payer selects the browser payment method, the Mastercard Payment 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.
  4. Once the payer interaction on the browser payment provider's website is complete, the payer is presented with the payment result via:
    1. Hosted Receipt: The payment result is displayed on the Hosted Payment Page/Lightbox. This is the default behavior.
    2. 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.

      3. The payer can also obtain the result of a successful payment via email notifications sent by the Mastercard Payment 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 via Direct Payment Integration

The following diagram illustrates the browser payment flow in a Direct Payment model:

Browser Payments Workflow for Direct Payment

Here are the integration steps for a browser payment via Direct Payment integration:

Step 1: Initiate a Browser Payment

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 Payment Gateway ignores the privileges configured on your merchant account with the Mastercard Payment Gateway.

    PayPal and UnionPay SecurePay support both Authorize and Pay operations; the other browser payment methods (Sofortbanking, giropay, BancaNet) only support Pay.

    • You may also provide additional details about the order, for example, billing address, shipping address, customer details, etc.

Initiate Browser Payment API Reference[REST][NVP]

Step 2: Redirect the Payer's Browser to the Browser Payment Provider

Use the browserPayment.redirectUrl provided in the Initiate Browser Payment response to redirect the payer's browser to the browser payment provider's website.

Step 3: Return the Payer's Browser to the Shop Site

Once the payer interaction at the browser payment provider's website is complete, the Mastercard Payment 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.

Step 4: Retrieve the Transaction Result

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.

Retrieve Transaction API Reference [REST][NVP]

Testing a Browser Payment Integration

For details on how to test the supported browser payment methods, see Testing Browser Payments.

Troubleshooting and FAQs

How can I track the interaction status of a browser payment?

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=INITIATED
  • browserPayment.interaction.timeInitiated=<the date and time the payment was successfully initiated is set>
  • browserPayment.interaction.status=REDIRECTED_TO_PROVIDER
  • browserPayment.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_MERCHANT
  • browserPayment.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=COMPLETED
  • browserPayment.interaction.timeCompleted=<the date and time the payment was completed is set>

These fields may be useful for troubleshooting purposes.

Copyright © 2023 Mastercard