nopCommerce Plugin for Bluefin

nopCommerce Plugin Information

Being a payment method plugin, here is its basic information with CNP transactions it supports.

Overview

This nopCommerce plugin combines the Bluefin Checkout Component and REST API, constituting the complete ready-to-use Bluefin payment method for nopCommerce platform.

The checkout component supports Card Payment, ACH, Google Pay, Mastercard Click to Pay, providing an all-in comprehensive eCommerce payment solution.

The plugin requires the merchant integration with the Bluefin Gateway where the integration team sets up your configuration according to your needs. The merchant is free to customize their iframe configuration and configure their payment method options on their own as they have gained enough experience while certifying with their Bluefin integration.

The plugin is built upon the Bluefin® PayConex™ REST API that connects to various PayConex™ services, thus serving as an HTTPS communication bridge to the PayConex™ Gateway.

📘

Note

The merchant using this plugin is not required to understand much of what's happening behind the scenes and how the Bluefin APIs are used.

If you are interested in all the ins and outs, check out our Comprehensive Documentation and Reference Materials and the plugin source code.

Here are some of the key components that the Bluefin payment plugin offers to the merchant.

Bluefin Hosted Checkout Components

• Easy Integration: Use our secure, pre-built Checkout Component UI via our SDK, designed for seamless integration into your existing systems.
• Security: These components are hosted on Bluefin's servers and handle all payment data input through an HTML iframe, ensuring that no sensitive credit card data reaches your servers.
• Flexible Management and Configuration: With a set of API endpoints, you can easily configure and create iframe payment instances, and effectively overwrite the configuration for a specific instance per customer. For more, see Creating an Instance.
• Tokenization: Once the form is completed, it securely tokenizes the information for CNP transactions by communicating with the ShieldConex® tokenization service and utilizes a payment authentication service based on the type of payment method, e.g. 3DS (Credit or Debit Card), Google Authentication Methods (Google Pay), ACH (Bank Information), Mastercard Click to Pay. After tokenization, a transaction is supposed to be processed during the PayConex™ token life-span (within 10 minutes).
• Saved Cards: The Checkout Component enables the customer to securely save their card data by checking the Save payment method. During the initialization of the iframe instance, the merchant supplies the saved token references, which facilitates faster checkout.

Versatile Transaction Processing

• Security: Bluefin ShieldConex® ensures that no sensitive card information is ever stored on your servers, significantly reducing the PCI scope.
• Card Not Present Transactions: Before processing, CNP transactions primarily rely on ShieldConex® for security. ShieldConex® does not store any sensitive cardholder data. Instead, it uses tokenization/detokenization on its vaultless tokens for online PII, PHI, payments and ACH account data. These tokens can be securely utilized or stored on the merchant's server, significantly reducing the vendor's or merchant's PCI footprint. However, if the merchant loses these tokens, they cannot be recovered. For more information, check out PayConex™ and ShieldConex®.
• Transaction Types: Our gateway supports a variety of the most common transaction types used on a day-to-day basis such as sale, authorization, store, capture, refund and credit.

3DS Support

• Security Backbone: Besides the vaultless tokenization solution by ShieldConex®, Bluefin provides one of the security backbones for processing online CNP transactions, with iframe configurations that can fully integrate 3DS as a feature of PayConex™.
• Fraud Prevention: Implement 3DS to enhance fraud prevention and secure customer authentication.
• User Experience: Ensure a smooth user experience while maintaining high security standards.
• 3DS MPI Simulation: Bluefin 3DS Solution can be simulated in the certification environment for testing purposes.

Installing the Plugin

First, download the latest release of our Bluefin Payment Plugin from GitHub.

After downloading the zip of the plugin's binary(Payments.Bluefin.zip), go to Admin -> Configuration -> Local Plugins and upload the zip.

Please follow the Plugins in nopCommerce Guide for installing third-party plugins.

📘

Building is not required

By downloading Payments.Bluefin.zip, you do not need to build the plugin - only install it as mentioned above.

If you are a developer testing, you may as well download the source code and build our solution.

Setting up and Configuring the Plugin

📘

Multi-store Support

The plugin supports configuration overriding for multiple stores of nopCommerce. For more, see nopCommerce | Multi-store.

Once the plugin is installed and is active, the merchant is required to go to the Admin Area -> Configuration -> Payment methods and configure the plugin at the /Admin/PaymentBluefin/Configure route.

📘

Note

Once the merchant is integrated with Bluefin Payment Gateway, the Bluefin Integrations Team provides them with the recommended nopCommerce configuration according to their needs.

For more details on configuring the Bluefin plugin, make sure to check out below and be up-to-date with the Bluefin Checkout Component Documentation.

For example,

There, we can see the Configure Page that consists of the following options.

• Account Identifier (Required)

  • The primary PayConex account ID associated with the API key.

• API Key Identifier (Required)

  • The secret API key ID, used in conjunction with the secret for API authentication. For more information, see API Key Management.

• API Key Secret (Required)

  • The API key secret, used in conjunction with the API key ID for API authentication. For more information, see API Key Management.

    Note
    Keep this secret secure and never expose it in your client-side code.
    API Key Identifier and Secret are both used to generate either Basic Authentication or HMAC Authentication depending on the environment the merchant integrates with.

• iFrame Configuration Identifier (Required)

  • iFrame Configuration used by the Checkout Component. Preconfigure payment methods and their settings

• Use sandbox environment

  • This check box must be selected if the merchant is in the process of conducting thorough testing in the Bluefin certification environment.
  • This also includes
    • Simulating various transaction scenarios to ensure reliability and security.
    • Performing end-to-end testing, from Checkout Component rendering to transaction completion.
  • For going to Production, this option must be unchecked.
  • Note that in the certification environment, the plugin uses the Base64 Basic Authentication whereas for production, it automatically generates the HMAC Authentication.

• Use 3D Secure

  • Use 3D Secure for the Checkout Component, Card Payment Method.
  • With this setting enabled, the threeDSecureInitSettings must be configured according to your needs. Note that this setting is required if cardSettings.threeDSecure is defined as "required". For more information, check out Creating an Instance.
  • While in the certification environment, make sure to use the following 3DS Test Card Numbers where you can simulate real-life scenarios to gain a better understanding of how 3D Secure operates with our Checkout Component and transaction authorization.
  • For the comprehensive information on Bluefin 3D Secure Protocol, check out 3D Secure and Bluefin 3DS Support.

• Authorize only (capture manually in the admin)

  • With this property checked, the merchant is required to capture the payment after customer's confirming the order. Otherwise, the sale is processed with the payment status of Paid.

• Enable Logging

  • Enable Logging for debugging purposes. This setting is primarily used in development. This is nopCommerce built-in logging page primarily for logs coming from the plugin's code. Compare nopCommerce| Log and Trace Logs Page.

Iframe Settings

• Responsive iframe

  • The responsive iframe option enables the Checkout Component to automatically adjust to different screen sizes.

• Iframe Width

  • Specify custom CSS iframe width for the Checkout Component such as 100%, 500px, 50vw

• Iframe Height

  • Specify custom CSS iframe height for the Checkout Component such as 600px, 60vh, 400px

• Iframe Timeout

  • The user interaction limit timeout in seconds.

Payment Methods

Specify the payment methods to be enabled for the Checkout Component.

Available payment method include:

• Credit/Debit Card
• Google Pay
• Click to Pay
• Bank Account / Bank Transfer (ACH)

threeDSecureInitSettings

With Use 3D Secure enabled, the merchant is required to configure the following 3DS Settings accordingly. All of these properties can be found in our Documentation Reference.

• 3DS Transaction Type

  • Each option provides context about the nature of the transaction, helping to ensure accurate processing and risk assessment.

  • Option	Description
    "GOODS_SERVICE_PURCHASE"	Indicates a purchase of goods or services. This is the most common type of transaction for retail or eCommerce.
    "CHECK_ACCEPTANCE"	Refers to the acceptance of a check as a form of payment.
    "ACCOUNT_FUNDING"	Represents a transaction that involves funding an account, such as adding funds to a digital wallet or prepaid card.
    "QUSAI_CASH_TRANSACTION"	Refers to transactions similar to cash withdrawals, such as purchasing traveler's checks, foreign currency, or gambling tokens.
    "PREPAID_ACTIVATION"	Refers to activating a prepaid account or card, often involving an initial funding transaction.

• Delivery Time Frame

  • As the setting name suggests, this is the time for the goods to be delivered. The descriptions are pretty much self-explanatory given the options.

  • Option	Description
    "ELECTRONIC_DELIVERY"	Electronic Delivery.
    "SAME_DAY_SHIPPING"	Same day shipping.
    "OVERNIGHT_SHIPPING"	Overnight shipping.
    "TWO_DAYS_OR_MOSRE_SHIPPING"	Two-day or more shipping.

• 3D Secure Challenge Indicator

  • Option	Description
    "NO_PREFERENCE"	We suggest that our merchants leave this option blank. This option is the most frictionless.
    "PREFER_NO_CHALLENGE"	Preference for no challenge to be presented to the end user.
    "PREFER_A_CHALLENGE"	Preference for the issuing bank to present a challenge to the end user.
    "OVERWRITE_NO_CHALLENGE"	Challenge is never presented to the end user.
    "REQUIRES_MANDATE_CHALLENGE"	This option dictates that a challenge must be presented to the end users.

• Reorder Indicator

  • This setting indicates whether the order is new or was ordered before.

  • Option	Description
    "FIRST_TIME_ORDERED"	First time ordered.
    "REORDER"	Reordered.

• Shipping Indicator

  • Option	Description
    "BILLING_ADDRESS"	Ship to cardholder's billing address. See Transaction Metadata billingAddress.
    "MERCHANT_VERIFIED_ADDRESS"	Ship to another verified address on file with merchant.
    "NOT_BILLING_ADDRESS"	Ship to address that is different than the cardholder's billing address.
    "SHIP_TO_STORE"	Ship to Store / Pick-up at local store (Store address will be populated in shipping address fields).
    "DIGITAL_GOODS"	Digital goods (includes online services, electronic gift cards and redemption codes).
    "TRAVEL_AND_EVENT_TICKETS"	Travel and Event tickets, not shipped.
    "PICK_UP_AND_GO_DELIVERY"	Indicates that the customer will pick up the purchased items in person or that the delivery service is immediate and does not involve standard shipping processes. Often used for express orders or convenience-driven transactions like curbside pickup.
    "LOCKER_DELIVERY"	Indicates that the purchased items will be delivered to a secure locker for the customer to retrieve at their convenience. Commonly used in scenarios like package lockers at residential complexes, stores, or designated pick-up locations.
    "OTHER"	Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.).

Iframe Configuration

Throughout this documentation, we are using the following iframe configuration.

📘

Note

For the cardSettings, we pretty much omit all of the customer-related information since we are passing it all before the checkout from the nopCommerce (current) customer.

Typically, the Bluefin Integrations team create this iframe configuration for the merchant if they don't necessarily prefer to use our APIs directly.

POST /api/v4/accounts/{accountId}/payment-iframe

{
  "label": "Multi-Payment iframe",
  "language": "ENGLISH",
  "timeout": 600,
  "allowedPaymentMethods": [
    "CARD",
    "ACH",
    "GOOGLE_PAY",
    "CLICK_TO_PAY"
  ],
  "allowedParentDomains": [
    "demo.nopcommerce.com"
  ],
  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "omit",
      "address2": "omit",
      "city": "omit",
      "state": "omit",
      "zip": "omit"
    },
    "capturePhone": "omit",
    "threeDSecure": "omit",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "achSettings": {
    "billingAddress": {
      "address1": "omit",
      "address2": "omit",
      "city": "omit",
      "state": "omit",
      "zip": "omit"
    },
    "capturePhone": "omit",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "clickToPaySettings": {
    "srcDpaId": "3fa85f65-6728-4562-b3fd-2c963f66afa6",
    "dpaName": "PayConex",
    "dpaPresentationName": "PayConex App",
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "CHINA_UNION_PAY"
    ]
  },
  "googlePaySettings": {
    "merchantId": "12345678901234567890",
    "merchantName": "Demo Merchant",
    "billingAddressRequired": false,
    "shippingAddressRequired": false,
    "emailRequired": true,
    "billingAddressParameters": {
      "format": "MIN",
      "phoneNumberRequired": false
    },
    "shippingAddressParameters": {
      "allowedCountryCodes": ["US"],
      "phoneNumberRequired": false
    },
    "allowedAuthMethods": [
      "PAN_ONLY",
      "CRYPTOGRAM_3DS"
    ],
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "JCB",
      "INTERAC"
    ],
    "threeDSecure": "omit"
  },
  "currency": "USD",
  "savePaymentOption": "required"
}

For the full breakdown of these settings, dive into Creating a Configuration.

In response, we receive the iFrame Configuration Identifier that is used to configure the plugin.

Upgrading to Newer Plugin version

With the plugin being open-source and maintained, and with new releases actively going out, upgrading to the latest plugin version/release is critical.

The following order of actions must be applied for a successful upgrade.

1. By going to Admin -> Configuration -> Local Plugins, uninstall the existing nopCommerce Bluefin Plugin
2. Upload the latest Payments.Bluefin.zip from GitHub
3. Restart the nopCommerce application to apply the changes
4. Install the uploaded version
5. Finally, restart the nopCommerce application again and you are all set up with the latest plugin version/release

🚧

Note

By uninstalling the plugin, all of its metadata, database entries, and configuration settings are permanently erased as well.

Please, make sure to have backed up your plugin configuration beforehand since this action cannot be undone.

Test Accounts, Cards, and Cases

In the certification environment, verify that transactions are processed correctly and validate that all the response codes are returned correctly based on your needs and the payment processor you integrate with.

For these test cards based on the payment processor, refer to Test Accounts, Cards, and Cases.

With 3DS enabled, make sure to use the following 3DS Test Card Numbers in the certification environment where you can simulate real-life scenarios to gain a better understanding of how 3D Secure operates with our Checkout Component and transaction authorization.

Test ACH Processing

For ACH testing account/routing numbers for your certification, please refer to Test Accounts, Cards, and Cases | Test ACH Processing.

Also see: Getting Started | Integration Steps.

Customer Checkout

After configuring the plugin, we need some Products we can check out with and test the Bluefin payment method.

If you are in the nopCommerce sandbox environment, it is necessary to create some Products so that we have something to check out.

This can be accomplished by going to Admin Area -> Catalog -> Products -> Add new.

Next, we add the Product to the cart and go to the checkout.

Checkout

The Checkout Component securely transmits payment details directly to Bluefin's system, mitigating risk while maintaining a smooth and user-friendly checkout experience. This also reduces PCI compliance scope and enhances security.

For all the examples of the payment methods, various checkout scenarios, and technical details, check out the comprehensive Customer Checkout page.

Even though the Bluefin Checkout Component supports the billing and shipping address form fields, the billing and shipping address is filled out and managed via nopCommerce. These are then passed onto the Checkout Component so that the customer is not required to reinput the same fields.

Omitting Shipping Address

If the shipping address is omitted, the plugin is capable of handling that scenario by completely excluding the shipping address from the Bluefin transaction itself as well.

In nopCommerce, the shipping is enabled per product. Thus, in order to omit it, the merchant needs to go to Admin Area -> Catalog -> Products, select their desired product, and scroll down to Shipping.

🚧

Note

If the merchant configures their plugin not to use the shipping address while using the 3D Secure, then the shippingIndicator is required to be BILLING_ADDRESS.

It is crucial to note that If, at least, one product in the cart requires shipping, the entire checkout will require the shipping address all the same.

Checkout Example

With no shipping address for a product, here is what the nopCommerce checkout looks like.

Order Example

If we fast-forward to Confirming Order, there is no shipping address attached to our order whatsoever.

At the same time, if we get the transaction metadata using the transaction identifier, there is no shipping address in the Bluefin Payment Gateway either.

For example,

{
  "transactionId": "000000060386",
  "status": "CAPTURED",
  "timestamp": "2025-07-16T14:08:47.000000Z",
  "customer": {
    "name": "Josh Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "address2": "21 West 53rd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "208e6efd-838b-4419-a873-453f50d4ee38",
        "correlationId": "4cc1359a-5d87-4160-8d91-439cb8383081",
        "timestamp": "2025-07-16T09:08:18-05:00"
      },
      {
        "action": "transaction",
        "requestId": "ae2bb6d3-46ce-4ce9-b591-e21c2957a289",
        "correlationId": "3d40c1a6-682a-4514-8668-83f826ae71f5",
        "timestamp": "2025-07-16T09:08:44-05:00"
      }
    ],
    "networkTransactionId": "015197023271606G189"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00",
    "requested": "10.00",
    "balance": "10.00"
  },
  "auth": {
    "code": "OK3293",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Josh Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "10.00"
  }
}

Pickup

The plugin also implements the logic where the nopCommerce pickup option is selected as the shipping address.

Selecting Payment Method

Now, we select the Bluefin Payment method.

🚧

Note

This step requires the plugin to be enabled/active from nopCommerce.

Payment Information

This is the nopCommerce built-in page where the customer uses the embedded third-party checkout component that is the Bluefin Checkout Component in our case.

Card Information

The customer then inputs their card information to be tokenized and used for transaction processing. If required, this is where 3DS authentication takes place.

Saved Card

This step is skipped if the customer selected Save payment method in their previous checkouts. The customer is only required to confirm the CVV on their card.

🚧

Note

In the certification environment, we can input just about any CVV since we are using Test Cards.

Review & Confirm

On the checkout completion, the Checkout Component securely returns the Bluefin token reference that is going to be used for subsequent transactions.

🚧

Note

We also make sure that the transaction was previously initialized if a communication error, packet loss, or similar issue occurs. For more information, see Initializing a Transaction.

During this step, we select Save payment method on purpose to showcase that your customers can securely save the card information so that they can reuse it in future. See Card Information above.

After submitting the form, we immediately advance to Confirming Order.

Confirming Order

Depending on the plugin configuration, a sale or authorization transaction is processed with a Bluefin Transaction Identifier attached to the order with the corresponding payment status.

The Bluefin Transaction Identifier is primarily used for capturing or refunding the transaction through nopCommerce in the context of Bluefin Payment Gateway.

🚧

Note

If there are any kind of problems processing your transaction, please contact Bluefin Technical support with the traceId or this transaction id attached to your order. Also see, Trace Logs Page below.

This id can be used for transaction reporting or debugging purposes.

If we get its transaction metadata via GET, we can see the billing and shipping address, the transaction history, etc.

For the comprehensive reference on transaction metadata, check out Get a Transaction Metadata.

For example, this is what we get in response.

{
  "transactionId": "000000061546",
  "status": "CAPTURED",
  "timestamp": "2025-07-22T14:54:51.000000Z",
  "customer": {
    "name": "Josh Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "address2": "21 West 53rd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "shippingAddress": {
    "address1": "21 West 52nd Street",
    "address2": "21 West 53rd Street",
    "city": "New York",
    "state": "NY",
    "zip": "10021",
    "country": "USA",
    "company": "Nop Solutions Ltd",
    "recipient": "John Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "235b6682-8788-463e-8667-7c3822bfd88b",
        "correlationId": "09d39378-1394-42c6-addb-408b87f1d83a",
        "timestamp": "2025-07-22T09:46:37-05:00"
      },
      {
        "action": "transaction",
        "requestId": "c83f4347-14e7-4032-ba95-0eb93351ee28",
        "correlationId": "7b23c6d7-0554-4353-9b9d-292f85aa1d1b",
        "timestamp": "2025-07-22T09:54:49-05:00"
      }
    ],
    "networkTransactionId": "015203206817970G175"
  },
  "amounts": {
    "currency": "USD",
    "approved": "1.00",
    "requested": "1.00",
    "balance": "1.00"
  },
  "auth": {
    "code": "OK4193",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Josh Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "1.00"
  }
}

Transaction Processing

Here is a table of Bluefin transactions with their corresponding payment statues in nopCommerce platform.

Other than the authorization and sale, all the operations require going Admin Area -> Sales -> Orders -> Select Order where the merchant is able to capture, refund, or partially refund their payments.

Sale and Authorization

By confirming the order, we first either process an authorization or sale transaction, depending on the Authorize only (capture manually in the admin) property in the plugin configuration.

With that property checked, the merchant is required to capture the payment after customer's confirming the order. Otherwise, the sale is processed with the payment status of Paid.

Capturing Authorization

As mentioned above, to capture an authorization - the Authorize only (capture manually in the admin) property must be enabled.

Now, if we get the transaction metadata, we can see the order of actions applied to the transaction: init, authorization and capture.

{
  "transactionId": "000000061666",
  "status": "CAPTURED",
  "timestamp": "2025-07-22T16:45:52.000000Z",
  "customer": {
    "name": "Josh Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "address2": "21 West 53rd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "shippingAddress": {
    "address1": "21 West 52nd Street",
    "address2": "21 West 53rd Street",
    "city": "New York",
    "state": "NY",
    "zip": "10021",
    "country": "USA",
    "company": "Nop Solutions Ltd",
    "recipient": "John Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "d2bd45d3-0191-4e74-94fd-c7c7143cab7f",
        "correlationId": "4b77f865-2daa-42b0-955e-13c063e390c1",
        "timestamp": "2025-07-22T11:43:37-05:00"
      },
      {
        "action": "authorization",
        "requestId": "b0ccb23e-41cb-4f00-b5a6-e8ce28e6c6df",
        "correlationId": "0a355f9b-ee14-4982-8548-1f25ac402474",
        "timestamp": "2025-07-22T11:44:59-05:00"
      },
      {
        "action": "capture",
        "requestId": "afab8699-18ad-45e7-9975-f2fb5e19a579",
        "correlationId": "c1323277-8c2e-41ee-8ebd-8dff4f24685c",
        "timestamp": "2025-07-22T11:45:50-05:00"
      }
    ],
    "networkTransactionId": "015203883153555G647"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00",
    "requested": "10.00",
    "balance": "10.00"
  },
  "auth": {
    "code": "OK3113",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Josh Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "10.00"
  }
}

Refunding

🚧

Note

Refund and Partial Refund are only allowed after the payment status is Paid.

By clicking on Refund of your order, we are, in fact, processing a full refund.

For example,

On successful refund, we receive a nopCommerce notification at the top of the page.

If we fetch the transaction metadata with the transaction id via PayConex API, we can see all the metadata of the refunded transaction. For more information, see Transaction Management | Refunding a Transaction.

{
  "transactionId": "000000061546",
  "status": "VOIDED",
  "timestamp": "2025-07-22T14:54:51.000000Z",
  "customer": {
    "name": "Josh Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "address2": "21 West 53rd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "shippingAddress": {
    "address1": "21 West 52nd Street",
    "address2": "21 West 53rd Street",
    "city": "New York",
    "state": "NY",
    "zip": "10021",
    "country": "USA",
    "company": "Nop Solutions Ltd",
    "recipient": "John Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "235b6682-8788-463e-8667-7c3822bfd88b",
        "correlationId": "09d39378-1394-42c6-addb-408b87f1d83a",
        "timestamp": "2025-07-22T09:46:37-05:00"
      },
      {
        "action": "transaction",
        "requestId": "c83f4347-14e7-4032-ba95-0eb93351ee28",
        "correlationId": "7b23c6d7-0554-4353-9b9d-292f85aa1d1b",
        "timestamp": "2025-07-22T09:54:49-05:00"
      },
      {
        "action": "refund",
        "requestId": "25203972-87e7-494f-89f6-b123afb2dd21",
        "correlationId": "21fa29bb-27d6-426d-8417-6f9015e8166b",
        "timestamp": "2025-07-22T11:22:11-05:00"
      }
    ],
    "networkTransactionId": "015203206817970G175"
  },
  "amounts": {
    "currency": "USD",
    "approved": "1.00",
    "requested": "1.00"
  },
  "auth": {
    "code": "OK4193",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Josh Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "REFUND",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000061626"
    ]
  }
}

Partial Refunding

For the partial refund, we input the amount we would like to refund.

Using the transaction id, here is our partially refunded transaction in the context of Bluefin Payment Gateway.

{
  "transactionId": "000000061586",
  "status": "CAPTURED",
  "timestamp": "2025-07-22T15:53:39.000000Z",
  "customer": {
    "name": "Josh Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "address2": "21 West 53rd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "shippingAddress": {
    "address1": "21 West 52nd Street",
    "address2": "21 West 53rd Street",
    "city": "New York",
    "state": "NY",
    "zip": "10021",
    "country": "USA",
    "company": "Nop Solutions Ltd",
    "recipient": "John Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "5e1f63ab-3d91-4fa2-8e22-3da37527b5fe",
        "correlationId": "efa79fe8-e848-4e8c-90c7-1444c2101f02",
        "timestamp": "2025-07-22T10:50:57-05:00"
      },
      {
        "action": "transaction",
        "requestId": "9a375bf8-4df3-4fed-8d0b-900523e703c2",
        "correlationId": "524270e9-d54b-45bd-b8da-9b085fe0cd0a",
        "timestamp": "2025-07-22T10:53:37-05:00"
      },
      {
        "action": "refund",
        "requestId": "429ded4a-b63f-4ae5-90f0-c3c26fe09b3a",
        "correlationId": "c4330b18-8ce7-4182-a74c-a292ed599807",
        "timestamp": "2025-07-22T10:54:53-05:00"
      },
      {
        "action": "refund",
        "requestId": "b73029b7-6514-489f-a402-20822a03593d",
        "correlationId": "73df9016-0ca2-4328-b246-936e018e7534",
        "timestamp": "2025-07-22T11:36:52-05:00"
      }
    ],
    "networkTransactionId": "015203521848298G411"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00",
    "requested": "10.00",
    "balance": "8.00"
  },
  "auth": {
    "code": "OK2103",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Josh Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "8.00",
    "refundIds": [
      "000000061606",
      "000000061646"
    ]
  }
}

Reissue Orders Component

This component introduces the ability for the merchant to charge an additional amount based on the (initial) customer order.

🚧

Admin Access

To access this page, go to the /Admin/PaymentBluefin/ReissueOrders route of your nopCommerce store.

This page requires Admin Access. Otherwise, it is forbidden.

One of the primary use cases of this kind of merchant-initiated transactions is applicable to scenarios where the merchant needs to adjust the total amount after the original authorization, such as adding shipping fees, tips, or other post-purchase charges.

This component allows the merchant to keep track of reissued transactions through the Bluefin Payment Gateway and maintain corresponding records or orders within their nopCommerce store at the same time.

Customer Initiated Transaction

First, there must be a customer initiated transaction in place where the customer has selected Save payment method during the checkout.

After the customer completes the checkout and the order has been processed via Bluefin Payment Gateway, the merchant can make an additional charge based on the reissuing Bluefin token with the customer having selected Save payment method.

🚧

Prior Agreement with Customer

The merchant is not allowed to process subsequent transactions without prior agreement with the customer.

As a security measure, the customer must select Save payment method. Otherwise, the reissuing token will expire within 10 minutes and the reissuing is not possible.

For more information, please refer to Customer and Merchant Initiated Transactions | Merchant Subsequent - Reissuing Transactions.

For the customer to reissue an order, they just have to reuse the Re-Order built-in functionality of the nopCommerce platform.

Merchant Initiated Transaction

By going to the /Admin/PaymentBluefin/ReissueOrders route of your nopCommerce store, you can see the table of all nopCommerce orders.

By clicking on View of a certain order, you are met with the following order metadata:

• Original Order Id

• Original Order Status

• Original Order Guid

• Original Order Payment Status

• Original Order Total

By reissuing the order, the following workflow takes place:

• The merchant selects Reissue Order with the reissuing amount for the new order
• Based on the original (customer) order, the reissued order reuses the exact same billing and shipping customer related information along with other metadata. See Metadata of the Reissued Transaction below.
• The reissued order is processed as a Bluefin sale transaction (authorization + capture)
• The reissued order is saved within the respective nopCommerce store

After the successful reissue, the merchant remains to:

• Go to /Admin/Order/List,
• Select the newly reissued order
• Finally, add the corresponding products to sum up to the order total.
  • The merchant can use their own generic products to specify the purpose or details of the additional charge.

Reissuing Orders | Video Tutorial

All of the above can be demonstrated in the following video step by step:

Metadata of the Reissued Transaction

If we get the metadata of the reissue transaction, it looks like the following:

{
  "transactionId": "000000086468",
  "status": "CAPTURED",
  "timestamp": "2025-11-04T00:23:40.000000Z",
  "customer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+12345678",
    "billingAddress": {
      "address1": "21 West 52nd Street",
      "city": "New York",
      "state": "NY",
      "zip": "10021",
      "country": "USA",
      "company": "Nop Solutions Ltd"
    }
  },
  "shippingAddress": {
    "address1": "21 West 52nd Street",
    "city": "New York",
    "state": "NY",
    "zip": "10021",
    "country": "USA",
    "company": "Nop Solutions Ltd",
    "recipient": "John Smith"
  },
  "trace": {
    "customId": "886cb287-9230-4927-8641-3c8d04a99fd7",
    "source": "nopCommerce Plugin",
    "history": [
      {
        "action": "transaction",
        "requestId": "b13730a6-4a43-453b-ac01-e6dab37a6816",
        "correlationId": "da72ee06-b271-479c-a8ff-29525f0b5a3d",
        "timestamp": "2025-11-03T18:23:37-06:00"
      }
    ],
    "networkTransactionId": "015308526977468G548"
  },
  "amounts": {
    "currency": "USD",
    "approved": "3.00",
    "requested": "3.00",
    "balance": "3.00"
  },
  "auth": {
    "code": "OK3680",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "John Smith",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "3.00"
  }
}

📘

Note

Each Bluefin transaction includes the corresponding nopCommerce order GUID, enabling a bi-directional link between your nopCommerce store/s and the Bluefin Payment Gateway.

This customId is solely used for more effective transaction reporting where the merchant can fetch the respective nopCommerce order in case they need to get its products, product attributes, or similar.

Trace Logs Page

This nopCommerce component of this plugin is enabled at all times in both production and certification so that the merchant can keep track of any errors that might occur to the customer during the checkout process or while confirming the order.

🚧

Admin Access

To access this page, go to the /Admin/PaymentBluefin/TraceLogs route of your nopCommerce store.

This page requires Admin Access. Otherwise, it is forbidden.

Trace Entry Details

If we view the individual entry from the table, we can dissect the full JSON response of the error.

🚧

Note

If the error message and its details are not clear enough or you struggle resolving the error, please reach out to Bluefin Technical support with the respective traceId so we can help resolve the issue.

Troubleshooting nopCommerce Issues

These are some of the most common nopCommerce issues merchants run into.

If you are blocked, we advise trying to resolve the listed issues with the suggested workarounds before reaching out to Bluefin Integrations team with the specifics via [email protected].

Do reach out if none of the workarounds resolve the issue.

Plugin Configuration Not Saving

If your Bluefin plugin shows the "The plugin has been updated successfully" notification during Setting up and Configuring the Plugin, but the configuration fields are not actually updated, you may have encountered this issue.

To resolve this issue, please try the following:

• Clear all server-side caches
  • From the nopCommerce Admin Panel:
    • Go to System → Maintenance → Clear cache
    • This clears all server-side caches, including settings.
• Restart your nopCommerce application/store
  • This clears all memory caches.
• Clear all browser caches
  • Open the Developer Tools (F12) and then right-click the refresh button to select "Empty cache and Hard Reload" from the dropdown menu.