solution25/bluesnap

BlueSnap payment method for Shopware 6

1.1.0 2026-07-31 14:28 UTC

Requires

• shopware/core: ^6.6 || ^6.7
• shopware/storefront: ^6.6 || ^6.7

Requires (Dev)

• squizlabs/php_codesniffer: ^3.7

proprietary

• solution 25

Published on Packagist.org on 2026-08-03 13:17 UTC

README

Bluesnap Payment

Introduction

The Bluesnap Shopware 6 Plugin is a reliable payment solution that connects Bluesnap’s gateway with your Shopware store. It supports a variety of payment methods such as credit cards, Apple Pay, Google Pay, hosted checkout, and pay-by-link. Merchants can manage full or partial refunds, enable 3D Secure for added safety, and offer customers the option to save, update, or delete their card details. With a clear setup process and secure transactions, the plugin helps businesses offer a smooth and flexible payment experience.

Key Features

• Credit Card Capture: Accept card payments through Bluesnap’s secure gateway.
• Hosted Checkout: Redirect customers to a secure Bluesnap-hosted payment page.
• Apple Pay & Google Pay: Offer fast, device-based payment options.
• Pay by Link: Send customers a link to complete their payment.
• Refunds: Support for full and partial refunds from the order view.
• Save Card: Let customers store card details for future use.
• Update Card: Allow customers to change saved card information.
• Delete Card: Give users control to remove stored cards.
• 3D Secure: Add an extra layer of protection to card transactions.
• Payment Surcharge: Optionally add a configurable surcharge to credit card payments, calculated dynamically at checkout and shown to the customer before the order is placed.

Compatibility

• ✅ Shopware 6.6.x

Get Started

Installation & Activation

1. Download

• Clone the Plugin Repository:

• Open your terminal and run the following command in your Shopware 6 custom plugins directory (usually located at custom/plugins/):

  git clone https://github.com/solution25com/bluesnap-payment-shopware-6-solution25.git
  

1. Install the Plugin in Shopware 6

• Log in to your Shopware 6 Administration panel.
• Navigate to Extensions > My Extensions.
• Locate the newly cloned plugin and click Install.

1. Activate the Plugin

• After installation, click Activate to enable the plugin.
• In your Shopware Admin, go to Settings > System > Plugins.
• Upload or install the “Bluesnap” plugin.
• Once installed, toggle the plugin to activate it.

1. Verify Installation

• After activation, you will see Bluesnap in the list of installed plugins.
• The plugin name, version, and installation date should appear as shown in the screenshot below.

Plugin Configuration

1. Access Plugin Settings

• Go to Settings > System > Plugins.
• Locate Bluesnap and click the three dots (...) icon or the plugin name to open its settings.

1. General Settings
   Before using the plugin, configure the API keys and payment settings:

• API Key for Live: Required for live transactions.

• API Public Key Live: Public key for authentication in the live environment.
  

• API Key for Sandbox: Required for testing transactions in the sandbox environment.

• API Public Key Sandbox: Public key for authentication in sandbox mode.

• 3D Secure (Activate/Deactivate): When enabled, 3D Secure authentication will be required for all credit card transactions.
  

• Vaulted Customer

• Enable/Disable Surcharge: When enabled, a payment surcharge is calculated and shown to the customer during credit card checkout before the order is placed.

• Ensure you configure these settings before enabling payment methods in your store.

1. Save Configuration

• Click Save in the top-right corner to store your settings.

Features & Usage

1. Credit Card Capture

This feature allows customers to complete transactions via Bluesnap’s PCI-compliant payment gateway using their credit card.

How It Works:
Customers enter their credit card details in a secure form.
The payment is processed via Bluesnap’s gateway.

Steps:

1. Select "Bluesnap Credit Card" as the payment method.
2. Enter the customer’s credit card details into the Bluesnap form.
3. Submit payment.

2. Hosted Checkout

Bluesnap’s Hosted Checkout provides a secure checkout page hosted by Bluesnap, removing the need for merchants to handle sensitive payment information directly.

How It Works:
Customers are redirected to a secure hosted checkout page.
Payments are securely processed through Bluesnap.

Steps:

1. Select "Bluesnap Hosted Checkout" as the payment method.
2. The customer is redirected to the hosted checkout page.
3. The customer completes the transaction on the hosted page.

3. Apple Pay Integration

Bluesnap supports Apple Pay, enabling customers to pay using their Apple devices with a single tap.

How It Works:
Customers use their Apple device to authenticate the transaction via Face ID, Touch ID, or Apple Watch.

Steps:

1. Select "Apple Pay" as the payment method.
2. Confirm payment through Face ID, Touch ID, or an Apple Watch.

4. Google Pay Integration

Customers can use Google Pay to complete transactions securely and quickly.

How It Works:
Customers authenticate the payment using their Google Pay account.

Steps:

1. Select "Google Pay" as the payment method.
2. Authenticate the payment via the customer’s Google Pay account.

5. Refunds (Full & Partial)

The Bluesnap plugin supports both full and partial refunds for transactions.

How It Works:

• Full refunds return the entire payment.
• Partial refunds return a portion of the payment.

Steps for Full Refund:

1. Navigate to the Orders section.
2. Select the order to be refunded.
3. Click "Create Refund."
4. Change the status to "In Progress."

Steps for Partial Refund:

1. Navigate to the Orders section.
2. Select the order to be partially refunded.
3. Specify the refund amount.
4. Click "Create Refund."
5. Change the status to "In Progress."

6. Save Card Feature

This feature allows customers to securely save their card details for future transactions.

How It Works:
A Vaulted ID is created to store the customer’s payment details securely.
Customers can select saved cards for future transactions.

Steps:

1. During checkout, select "Save my card for future use."
2. The card is securely stored and available for future use.

7. Update Card Feature

Allows customers to update their saved card details securely for future transactions.

How It Works:
Customers can modify their saved card information directly within the payment gateway.

Steps:

1. Navigate to checkout.
2. Update the saved card details.
3. Save the updated card information.

8. Delete Card Feature

This feature allows customers to delete their stored card details when they no longer wish to use them.

How It Works:
Customers can remove their stored card information from the system.

Steps:

1. Navigate to checkout.
2. Select the card to be deleted.
3. Click "Delete" to remove the card from the system.

9. 3D Secure Authentication

Enabling 3D Secure adds an extra layer of authentication to credit card transactions, reducing fraud.

How It Works:
After the customer enters their credit card details, they will be redirected to their bank’s authentication page to complete the transaction.

Steps:

1. Enable 3D Secure in the plugin configuration.
2. Customers will automatically be prompted for 3D Secure authentication during checkout.

10. Payment Surcharge

Merchants can add a configurable surcharge to credit card payments. The surcharge is calculated dynamically through Bluesnap and shown to the customer for confirmation before the order is placed.

How It Works: Once enabled, entering credit card details on the checkout confirmation page shows a "Calculate surcharge and proceed to payment" button instead of submitting immediately. Calculating the surcharge shows the customer the additional amount, which is added to the order as a separate line item. This works both for a newly entered card and for a customer's saved/vaulted card, including when switching cards mid-checkout.

Steps:

1. Enable Surcharge in the plugin configuration.
2. During checkout, the customer enters their credit card details (or uses a saved card).
3. The customer clicks "Calculate surcharge and proceed to payment" to see the surcharge amount.
4. The customer confirms and completes the order with the surcharge included.

BlueSnap Plugin - API Documentation

This document provides detailed information about the API endpoints available in the BlueSnap Plugin for Shopware 6. These endpoints allow secure integration with BlueSnap’s payment services, enabling the generation of payment tokens and facilitating hosted payment field rendering within your Shopware storefront.

Generate Payment Field Token

Endpoint:
POST /services/2/payment-fields-tokens

Description:
This endpoint is used to generate a payment field token, which is required to securely render BlueSnap's hosted payment fields on the frontend.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>

Successful Response:

HTTP/1.1 201 Created  
Location: https://sandbox.bluesnap.com/services/2/payment-fields-tokens/eyJhbGciOiJIUzI1NiJ9...

Example Error Response:

{
  "errorCode": "401",
  "errorDescription": "Unauthorized Error"
}

Capture Transaction

Endpoint:
POST /services/2/transactions/

Description:
This endpoint is used to capture a payment (authorize and capture funds) for a transaction using BlueSnap. It is typically called after the tokenization of payment data via BlueSnap's hosted fields.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json

Example Request Body:

{
  "amount": 39.98,
  "softDescriptor": "Card Capture",
  "currency": "EUR",
  "cardHolderInfo": {
    "firstName": "asd",
    "lastName": "asd",
    "zip": "12345",
    "country": "us",
    "city": "test",
    "email": "[e-mail]"
  },
  "pfToken": "token",
  "cardTransactionType": "AUTH_CAPTURE",
  "transactionInitiator": "SHOPPER"
}

Successful Response:

{
  "transactionId": 100123456,
  "transactionType": "AUTH_CAPTURE",
  "amount": 39.98,
  "currency": "EUR",
  "card": {
    "cardLastFourDigits": "1111",
    "cardType": "VISA"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS",
    "authCode": "XYZ123"
  }
}

Example Error Response:

{
  "errorCode": "401",
  "errorDescription": "Unauthorized Error"
}

Apple Pay Wallet

Endpoint:
POST /services/2/wallets/

Description:
This endpoint is used to create or update an Apple Wallet entry associated with a customer. It typically requires authorization and a JSON payload describing the wallet data. The request sends payment or pass-related information to BlueSnap's Apple Wallet service.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json

Example Request Body:

{
  "walletType": "APPLE_PAY",
  "validationUrl": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
  "domainName": "merchant.com"
}

Successful Response:

{
  "walletType": "APPLE_PAY",
  "walletToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5ISk1pSm9RbXhCMFd"
}

Example Error Response:

{
  "message": "Invalid wallet request",
  "code": 400
}

Retrieve Vaulted Shopper

Endpoint:
GET /services/2/vaulted-shoppers/{vaultedShopperId}

Description:
This endpoint retrieves the details of a vaulted shopper from BlueSnap using their unique ID. Vaulted shoppers store payment details and personal data for future transactions (e.g. subscriptions or saved payment methods). This is typically used to manage or reuse stored shopper data securely.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json
• Accept: application/json

Example Request:
GET /services/2/vaulted-shoppers/123456789

Successful Response:

{
  "vaultedShopperId": 123456789,
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "paymentSources": {
    "creditCardInfo": [
      {
        "cardLastFourDigits": "1111",
        "cardType": "VISA",
        "expirationMonth": "12",
        "expirationYear": "2025"
      }
    ]
  },
  "billingContactInfo": {
    "zip": "12345",
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "123 Main St"
  }
}

Example Error Response:

{
  "error": true,
  "code": 15001,
  "message": "Vaulted shopper not found."
}

Hosted Checkout

Endpoint:
POST /services/2/bn3-services/jwt

Description:
This endpoint is used to generate a JWT (JSON Web Token) for initiating a BlueSnap Hosted Checkout session.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json

Successful Response:

HTTP/1.1 201 Created  
Location: https://sandbox.bluesnap.com/services/2/payment-fields-tokens/12345abcde*********

Example Error Response:

{
  "message": "Invalid credentials",
  "code": 401
}

Update Vaulted Shopper

Endpoint:
PUT /services/2/vaulted-shoppers/

Description:
Updates an existing vaulted shopper's payment or personal information.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json

Example Request Body:

{
  "paymentSources": {
    "creditCardInfo": [
      {
        "creditCard": {
          "expirationYear": 2023,
          "securityCode": 837,
          "expirationMonth": "02",
          "cardNumber": 4263982640269299
        }
      }
    ]
  },
  "firstName": "FirstName",
  "lastName": "LastName",
  "softDescriptor": "MYCOMPANY"
}

Successful Response:

{
  "vaultedShopperId": 19549048,
  "firstName": "FirstName",
  "lastName": "LastName",
  "country": "us",
  "zip": "02453",
  "phone": "1234567890",
  "shopperCurrency": "USD",
  "paymentSources": {
    "ecpDetails": [
      {
        "billingContactInfo": {
          "firstName": "FirstName",
          "lastName": "LastName"
        },
        "ecp": {
          "accountType": "CONSUMER_CHECKING",
          "publicAccountNumber": "99992",
          "publicRoutingNumber": "75150"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:59:40"
      },
      {
        "billingContactInfo": {
          "firstName": "FirstName 2",
          "lastName": "LastName 2"
        },
        "ecp": {
          "accountType": "CONSUMER_SAVINGS",
          "publicAccountNumber": "99992",
          "publicRoutingNumber": "75150"
        },
        "dateCreated": "09/30/2020",
        "timeCreated": "05:59:40"
      }
    ]
  },
  "fraudResultInfo": {
    "deviceDataCollector": "Y"
  },
  "dateCreated": "09/22/2020",
  "timeCreated": "13:41:10"
}

Example Error Response:

{
  "error": true,
  "code": 14002,
  "message": "Invalid credit card details."
}

Refund Transaction

Endpoint:
POST /services/2/transactions/refund/

Description:
Processes a refund for a transaction. Can include metadata and options to cancel subscriptions.

Request Headers:

• Authorization: Basic <base64-encoded API credentials>
• Content-Type: application/json

Example Request Body:

{
  "reason": "Refund for order #1992",
  "cancelSubscriptions": false,
  "transactionMetaData": {
    "metaData": [
      {
        "metaValue": "1552,8832",
        "metaKey": "refundedItems",
        "metaDescription": "Refunded Items"
      },
      {
        "metaValue": "Value 2",
        "metaKey": "metaKey2",
        "metaDescription": "Metadata 2"
      }
    ]
  }
}

Successful Response:

{
  "refundTransactionId": 1039288153,
  "transactionMetaData": {
    "metaData": [
      {
        "metaKey": "refundedItems",
        "metaValue": "1552,8832",
        "metaDescription": "Refunded Items"
      },
      {
        "metaKey": "metaKey2",
        "metaValue": "Value 2",
        "metaDescription": "Metadata 2"
      }
    ]
  },
  "reason": "Refund for order #1992",
  "cancelSubscriptions": false
}

Example Error Response:

{
  "errorCode": "400",
  "errorDescription": "Transaction not eligible for refund"
}

Best Practices

• Use Sandbox for Testing: Always test your payment methods and flows in sandbox mode before going live.
• Enable 3D Secure: Improve fraud protection by turning on 3D Secure for all credit card transactions.
• Keep API Keys Secure: Never share your API keys publicly. Rotate them regularly if needed.
• Inform Customers About Saved Cards: Be transparent about card-saving features and offer easy ways to manage or delete saved cards.
• Monitor Transactions: Regularly check your Bluesnap dashboard to track transactions, monitor refunds, and handle any failed payments.
• Stay Updated: Keep the plugin updated to the latest version to ensure compatibility and security improvements.

Troubleshooting

Issue: Payment method not appearing at checkout

• Ensure the plugin is properly configured with the correct API keys.
• Verify that the desired payment methods are activated in your Shopware settings.
• Check that your store is in the correct mode (sandbox or live) matching the keys.

Issue: 3D Secure not triggering

• Confirm 3D Secure is enabled in the plugin settings.
• Ensure the credit card used supports 3D Secure.
• Test with different cards if needed.

Issue: Saved cards are not displaying

• Verify that the Vaulted Customer feature is enabled.
• Ensure the user is logged into their account during checkout.

Issue: Refund fails or doesn’t reflect in order status

• Make sure the transaction was successfully captured before initiating a refund.
• Confirm you are using the correct order and amount, especially for partial refunds.
• Check Bluesnap’s dashboard for more details on failed refund attempts.

FAQ

What payment methods does the Bluesnap Shopware 6 Plugin support?

• The plugin supports Credit Card, Apple Pay, Google Pay, Hosted Checkout, and Pay by Link.

Can customers save their card details for future use?

• Yes, customers can securely save card details and manage them (update or delete) within their account.

How do I enable 3D Secure?

• You can activate 3D Secure in the plugin configuration settings under the API section.

Is sandbox testing supported?

• Yes, the plugin supports sandbox mode for safe testing. Use the Sandbox API keys in the configuration section.

Can I issue partial refunds?

• Yes, both full and partial refunds are supported via the order management interface.

Can I add a surcharge to credit card payments?

• Yes, enable the Surcharge option in the plugin configuration. The surcharge is calculated at checkout and shown to the customer before the order is placed.

Wiki Documentation

Read more about the plugin configuration on our Wiki.