BlueSnap.comDeveloper DocsShopper SupportStatusTalk to Sales

Implementing BlueSnap Checkout

Suggest Edits

Follow the steps in this section to implement BlueSnap Checkout on your website.

Before Getting Started

  • Authentication: You need to create API credentials and define the IP addresses of your server to take advantage of BlueSnap Checkout.
  • Domain: In all steps below, replace the BLUESNAPDOMAINPATH with the relevant domain for either the BlueSnap Sandbox or Production environment, as follows:
    • Sandbox: https://sandpay.bluesnap.com
    • Production: https://pay.bluesnap.com
  • Errors: If you encounter any errors while following the steps below, refer to BlueSnap Checkout Errors.
  • Customization: Find more information about customizing your checkout page on our Page Design and Custom Fields guide.
  • Apple Pay: If you would like to accept Apple Pay, please contact Merchant Support to have it enabled for your account.

Step 1: Add the BlueSnap JavaScript file to your site

Add the following BlueSnap JavaScript file to your site, replacing BLUESNAPDOMAINPATH with:

  • Sandbox: https://sandpay.bluesnap.com
  • Production: https://pay.bluesnap.com
<script type="text/javascript" src="BLUESNAPDOMAINPATH/web-sdk/5/bluesnap.js"></script>

Step 2: Create a Token

When your shopper is ready to complete their purchase, you will create a token for the checkout process with BlueSnap.

This token is a JSON Web Token (JWT) that securely stores data about the transaction and allows BlueSnap to verify your identity. Unauthorized websites will be prevented from creating BlueSnap Checkout pages on your behalf.

To create the BlueSnap Checkout token, first have your client-side application reach out to your server. Next, send a server-to-server POST request to /services/2/bn3-services/jwt of the relevant BlueSnap domain for Sandbox or Production.

📘

API calls require the use of your API credentials, Basic authentication, and headers. See Authentication & Headers for details.

In the request body, you can include Secure Payment Parameters.

Token expiration

Your token will expire in any of the following situations:

  • It has been 2 hours since the token was created.
  • The token has successfully been used to process a transaction.

If a token expires, you'll need to create a new one.

Request Examples

curl -v -X POST https://sandbox.bluesnap.com/services/2/bn3-services/jwt \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "mode": "one_time",
  "onBehalf": "false",
  "currency": "USD",
  "successUrl": "http://www.mySite.com/success",
  "cancelUrl": "http://www.mySite.com/cancel",
  "merchantTransactionId": "myid1234",
  "lineItems": [
    {
      "id": "001",
      "quantity": 2,
      "label": "T-Shirt",
      "description": "T-Shirt with logo",
      "amount": 20
    },
    {
      "id": "002",
      "quantity": 1,
      "label": "Shorts",
      "description": "Green shorts with pockets",
      "amount": 15
    }
  ]
}'

curl -v -X POST https://sandbox.bluesnap.com/services/2/bn3-services/jwt \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "mode": "subscription",
  "successUrl": "http://www.mySite.com/success",
  "cancelUrl": "http://www.mySite.com/cancel",
  "planItems": [
    {
      "id": "001", // the plan id from createPlan API
      "quantity": 1,
      "label": "AAA subscription", // override the plan-name
      "recurringChargeAmount": 20, // override the recurringChargeAmount
      "trialPeriodDays": 14, // override the trialPeriodDays
      "initialChargeAmount": 10 // override the initialChargeAmount
 
    }
  ]
}

Response Example

{
  "jwt": "eyJhbGciOiJIUzI1NiJ9.eyJwYXlsb2FkIjp7ImNvbW1vbkp3dFBheWxvYWQiOnsiaWQiOiI1OTU4NTkxODYxNTgwMDg5OTI3NzEiLCJtZXJjaGFudElkIjo0MDAwNDgsImRhdGVDcmVhdGVkIjoxNjA2OTk2MjI5OTExLCJlbnYiOiJERVY2In0sImN1cnJlbmN5IjoiVVNEIiwic3VjY2Vzc1VybCI6Imh0dHBzOi8vaG9tZS5ibHVlc25hcC5jb20iLCJjYW5jZWxVcmwiOiJodHRwczovL2FwLmJsdWVzbmFwLmludDo0MDA0L2NhbmNlbCIsIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6IjU5NTg1OTE4NjE1ODAwODk5Mjc3MSIsImxpbmVJdGVtcyI6W3siaWQiOiJpZDEiLCJsYWJlbCI6IlJhaW5ib3ciLCJkZXNjcmlwdGlvbiI6IlRvdWNoIHRoZSBSYWluYm93IiwicXVhbnRpdHkiOjEsImFtb3VudCI6MTAuMCwiaW1nVXJsIjpudWxsfV19fQ.Mi4eiNKCsGDTsLHnTXPfe4-UNpQYSY-OvKufwZr2jR0",
  "merchantTransactionId": "myid1234"
}

If successful, the response will include your token, which you can then send back to your client-side application.

document.getElementById('payButton').addEventListener('click', function () {
  // Get the token from your server
  fetch('/token')
    .then((response) => response.json())
    .then((data) => {
    	const token = data.token;
      // Continued below...
    })
    .catch((error) => {
      console.log(error);
    });
});

Step 3: Complete your sale

  1. Now that you have your token, you can initiate and display BlueSnap Checkout page so your shopper can begin the checkout process. Call bluesnap.redirectToPaymentPage with an sdkRequest object containing these properties. This will redirect the shopper and display the BlueSnap checkout page.
document.getElementById('payButton').addEventListener('click', function () {
  // Continued from above
  const sdkRequest = {
    jwt: token
  };
  bluesnap.redirectToPaymentPage(sdkRequest);
});
  1. When your shopper successfully finishes checking out, BlueSnap will process the transaction and direct the shopper back to your website via the successUrl in the JWT token. BlueSnap will append your URL with data about the transaction.

Note: Some payment methods require additional implementation steps. See Additional Implementation Steps.

Verifying Transactions

To ensure transactions are valid, we recommend comparing and validating your transaction details against existing information. You can retrieve transaction details using the URL parameters that have been passed into your successURL.

There are two ways to verify a transaction:

  1. Use the Retrieve API request to confirm the transaction details are valid and that the transaction was successful. Since Bluesnap operates in two different data centers, your code needs to retrieve the transaction from the data center that processed the transaction. Use the Bluesnap invoice ID (returned in the callback URL) to determine which domain to use to call the Retrieve API.
    • If the Bluesnap invoice ID is an even number, call the following domain: ws1.bluesnap.com
    • If the Bluesnap invoice ID is an odd number, call the following domain: ws2.bluesnap.com
  2. Set up IPNs to receive an alert for any event, including a charge.

Payment Methods: Additional Implementation Steps

SEPA

After successfully checking out using SEPA, the shopper is redirected to your successUrl. In your successUrl you should perform the following steps:

  1. Use BlueSnap Checkout Return URL Parameters to perform a Retrieve SEPA DD Transaction request and obtain the transaction details. The response will include the necessary information for the next steps.
  2. Follow the SEPA implementation guide starting from Step 3.

Local Bank Transfer

After successfully checking out using Local Bank Transfer, the shopper is redirected to your successUrl. In your successUrl you should perform the following steps:

  1. Use BlueSnap Checkout Return URL Parameters to perform a Retrieve LBT Transaction request and obtain the transaction details. The response will include the necessary information for the next steps.
  2. Start at Step 3 and follow the Local Bank Transfer Transaction Processing guide. To understand which details should be displayed to the shopper:
    1. Read Step 4 of the Complete the Payment section.
    2. Refer to the image in Step 2 of the Placing the Order section.

Embedding in an iframe

BlueSnap Checkout can be configured to open inside a container in your website using an iframe, instead of redirecting your shopper to a separate page.

Add the attribute data-bluesnap='iframe-container' to a div element on your page like so:

<div data-bluesnap="iframe-container"></div>

Note: you can configure the redirection method of the page using the displayData.iframeOptions.topRedirect flag. By default, topRedirect is false, which will cause only the iframe window to redirect to your success/cancel URLs. If you set the topRedirect parameter to true, BlueSnap Checkout will redirect your entire page to the success/cancel URLs.

🚧

  • ApplePay is not supported in iframe mode.
  • In iframe mode, iDeal Sofort and PayPal always perform top redirection, regardless of the state of the topRedirect flag.

Returning Shoppers

When a transaction is successful, the object in the response of the Retrieve API request includes the shopper ID in the vaultedShopperId property. If you would like to allow returning shoppers to use their saved information for payments, you can save the vaultedShopperId and associate it with your shopper. When the shopper checks out again and you are sending a token creation request, you can then include the vaultedShopperId in the shopperId field.

To leverage this feature, configure the checkout page to display a checkbox that the shopper can use to save their card information after a successful transaction. Here are some examples of how the checkout experience might look:

Next steps

Once you've finished implementing BlueSnap Checkout, explore the docs for additional ways to get the most out of BlueSnap's platform.

→ IPNs Learn about BlueSnap's webhooks and how to stay informed of important events.

Updated 5 months ago