Payment Request API (W3C)

The Payment Request API is a W3C standard that eliminates checkout forms by creating a fast, simple, and consistent payment experience for shoppers using supported browsers. Using this solution, BlueSnap securely captures and tokenizes the shopper’s data obtained from the browser, allowing you to process card payments with our Payment API while keeping your PCI burden to a minimum. This solution is especially useful for streamlining guest checkouts and minimizing friction for returning shoppers who want to pay with a new card. The shopper selects a saved payment method and confirms the purchase in the payment UI provided by the browser.

Step 3: Create the PaymentRequest instance

Check to make sure the shopper's browser supports the Payment Request API using bluesnap.isSupported('PaymentRequest'). If so, create a new PaymentRequest instance by calling bluesnap.paymentRequest with these arguments:

token - The token you created in Step 1.

function(instance) {...} - A callback function that BlueSnap invokes after the instance is created.

If the Payment Request API is not supported, it is recommended to set up a traditional checkout flow that uses BlueSnap's Hosted Payment Fields.

Step 4: Add a div element to your page

Step 5: Initialize the PaymentRequest instance

Initialize paymentRequest by calling its init method with these arguments:

detailsObj - The object that holds data about the transaction (such as the transaction total) that will tell the browser what to display in the payment UI, among other things (see Deep dive into defining detailsObj).

attValue - The value of the data-bluesnap attribute from Step 4 so BlueSnap will know where to hold the iFrame.

Step 6: Show the Payment Request button

Check whether the shopper has saved a supported card using canMakePayment(). If they have one present, call showButton() to display the button that BlueSnap provides, which, when clicked, will show the payment UI provided by the browser. If the shopper doesn't have a supported card, it is recommended to set up a traditional checkout flow.

If you would rather use your own button to show the payment UI:

Step 7: Process the payment using the token

Calling showButton() will display the payment UI to the shopper. The shopper will either close the payment UI (causing the promise to reject) or successfully confirm the purchase (causing the promise to resolve), at which time, you'll need to send the token to your server and process the transaction using the Payment API (click here for code samples). Once you receive the response from BlueSnap, you'll need to communicate the result with the browser by calling complete with either 'success' or 'fail', prompting the browser to close the payment UI or display an error message.

// Continued from abovepaymentRequest.showButton()
.then(function(ev) {
// The shopper confirmed the purchase // Send ev.token to your server and process the transaction...// ... Report the transaction result to the browserev.complete('success'); // or ev.complete('fail');
})
.catch(function(err) {
// The shopper closed the payment UIconsole.log(err);
});

Once the callback function triggers, you can then process payments by including the Payment Request API (W3C) token in your API requests. This must be done from your server and requires using your API Credentials.

Additional topics

Deep dive into defining detailsObj

Including the following properties within detailsObj allows you to tell the browser exactly what it should display in the payment UI, define what details it should collect from the shopper (such as email and phone), and specify the cards that you support on your website.

Property

Type

Required

Description

details

object

Required

Allows you to define the transaction total, display line items, and shipping options that the browser should display in the payment UI. At a minimum, the total must be included. (To learn how to handle shipping, see Collecting shipping information.)

options

object

Optional

Allows you to indicate whether email, name, phone, or shipping address should be collected from the shopper in the payment UI. By default, these details are not collected.

methodData

array

Optional

Allows you to tell the browser which cards are supported on your website (as long as those cards are enabled for your BlueSnap configuration). By default, all cards that are enabled for your BlueSnap configuration are supported. (To learn how to enable or disable certain cards in the BlueSnap Console, click here.)

Collecting shipping information

Step 1: Tell the browser to collect the shopper's shipping address

If you sell physical goods that need to be shipped, tell the browser to collect the shopper's shipping address in the payment UI. Do this by including requestShipping: true within options when you initialize paymentRequest. If the shipping options don't depend on the shopper's address (for example, you offer free, worldwide shipping), you may also want to provide shippingOptions at this time.

Step 2: Handle shipping address changes

Listen to the shippingaddresschange event to know when the shopper selects a shipping address, providing you the opportunity to verify that the address meets your requirements and to determine the available shipping options. To update the payment UI, call updateWith with the available shipping options or an error, depending on whether the shopper's address meets your requirements. If no changes need to be made to the payment UI, call noChange().

Step 3: Handle shipping options changes

Listen to the shippingoptionchange event to know when the shopper selects a shipping option, providing you the opportunity to mark the shipping option as selected and to update the total and display items. Similiar to the previous step, call updateWith with the updated details (or call noChange if no changes to the payment UI are required).

Styling the Payment Request button

To style the Payment Request button, create a style object using the following properties and pass it to showButton(). To adjust the height and width, style the <div> element from Step 4. The button's minimum height is 32px, its maximum height is 64px, and its width is always 100%.

The images below show a few examples of the Payment Request button. The left button has the default appearance. The right button has the light theme with the default text.

Using your own button to show the payment UI

If you would rather use your own button to show the payment UI, use show() (instead of showbutton()). This method shows the payment UI to the shopper and returns a promise. The shopper will either close the payment UI (causing the promise to reject) or successfully confirm the purchase (causing the promise to resolve).

When the promise resolves, send the token to your server and process the transaction using the Payment API (click here for code samples). Once you receive the response from BlueSnap, communicate the result with the browser by calling complete with either 'success' or 'fail', prompting the browser to close the payment UI or display an error message.