=== Blackstone Online Gateway === Contributors: carlosraul7 Donate link: https://blackstoneonline.com/ Tags: woocommerce, payment, gateway, blackstone, credit card Requires at least: 5.8 Tested up to: 6.9 Stable tag: 4.8.1 Requires PHP: 7.4 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Custom payment gateway integration for WooCommerce using Blackstone Merchant. Secure, fast and reliable payments for your online store. == Description == **Blackstone Online Gateway** is a custom payment integration for WooCommerce that allows merchants to process credit card payments through the Blackstone Merchant platform. It provides a seamless checkout experience, secure communication with the API, and supports refund handling directly via WooCommerce. ### Main Features * Full integration with WooCommerce checkout and order management. * Works with both the classic checkout and the Cart & Checkout Blocks (the default checkout on new stores). * Secure API connection to Blackstone Merchant Services. * Supports payment authorization, capture and refund. * 3D Secure (3DS) authentication for fraud prevention. * Saved payment tokens — customers can securely save and reuse credit cards. * Surcharge and dual pricing (card difference) support with configurable labels. * Full and partial refund processing via API with stock management. * Test/sandbox mode for development and staging environments. * Admin settings page for easy configuration of merchant credentials. * Localization support with Spanish (es_ES) translation included. * Compatible with the latest versions of WooCommerce and WordPress. ### How It Works 1. The customer selects Blackstone Merchant as the payment method at checkout. 2. They can enter a new credit card or choose a previously saved card. 3. If 3DS is enabled, the transaction is authenticated via 3D Secure. 4. The payment is processed securely through the Blackstone API. 5. The card can optionally be saved as a token for future purchases. This plugin requires an active merchant account with [Blackstone Merchant](https://www.blackstonemerchant.com/). == External Services == This plugin connects to external services to process payments and perform security verifications. **BMS Pay API** This service is used to process payments and refunds securely. * **Source**: `https://services.bmspay.com/` * **Data Sent**: Transaction details, card information (processed securely), and order amounts. * **Provider**: Blackstone Merchant Services. * **Terms & Privacy**: Please refer to [Blackstone Merchant](https://www.blackstonemerchant.com/) and [Documentation](https://documentation.bmspay.com/). **3DS Integrator** This service is used for 3D Secure (3DS) authentication to prevent fraud. * **Source**: `https://cdn.3dsintegrator.com/` (Script), `https://api.3dsintegrator.com/` (API). * **Data Sent**: Card identifiers and transaction context for risk analysis. * **Provider**: 3DS Integrator (via Blackstone). * **Terms & Privacy**: Usage is covered under your agreement with [Blackstone Merchant](https://www.blackstonemerchant.com/). == Installation == 1. Upload the plugin folder to `/wp-content/plugins/` or install it directly from the WordPress Plugin Directory. 2. Activate the plugin through the *Plugins* menu in WordPress. 3. Go to **WooCommerce → Settings → Payments → Blackstone Merchant**. 4. Enable the gateway and enter your merchant credentials (Username, Password, MID, CID, AppKey, AppType). 5. Optionally enable 3D Secure and configure the 3DS API key and token. 6. Save changes and test the payment process using test mode. == Frequently Asked Questions == = Do I need a Blackstone Merchant account? = Yes. You must have an approved merchant account from [Blackstone Merchant](https://www.blackstonemerchant.com/) to process transactions. = Does this plugin support refunds? = Yes. Full and partial refunds can be processed directly from the WooCommerce order screen. The plugin sends refund requests securely to the Blackstone API and can optionally restock items. = What is 3D Secure (3DS)? = 3D Secure is an additional authentication layer that helps prevent fraudulent transactions. When enabled, the cardholder may be asked to verify their identity during checkout. This plugin integrates with the 3DS Integrator service to handle this process. = Can customers save their credit cards? = Yes. Customers can choose to save their credit card as a payment token during checkout. Saved cards can be reused for future purchases without re-entering card details. No sensitive card data is stored on your server. = Does it support test/sandbox mode? = Yes. The plugin includes a test mode toggle in the settings page. This allows you to test transactions in a sandbox environment before going live. There is also a separate test mode toggle for 3DS authentication. = Is it compatible with WooCommerce Subscriptions or Bookings? = Currently, it supports standard one-time payments. Future versions may include support for recurring billing. = Does it store credit card information? = No. The plugin does **not** store or log any sensitive card data. All transactions are handled securely through the Blackstone Merchant gateway. Saved payment tokens are managed by WooCommerce's built-in token system. = What is the surcharge/dual pricing feature? = The plugin supports adding a surcharge or card difference amount to orders. This can be configured with custom labels in the admin settings and is displayed as a separate line item in the order. == Screenshots == 1. Payment gateway settings — General configuration screen under WooCommerce → Settings → Payments → Blackstone Merchant. 2. Payment gateway credentials — API credentials and 3DS configuration options. 3. Checkout page — The Blackstone Merchant payment option displayed to customers. == Changelog == = 4.8.1 = * The classic checkout's 3D Secure modal, alert titles and card errors now follow the store's language. Previously they were written in Spanish, so English stores showed a Spanish modal. A failed 3D Secure token refresh and 3D Secure provider errors now show a translated message to the customer, and the original text goes to the plugin log. * Added the Spanish translation of the "Save this card for future purchases" checkbox of the payment form, which showed in English on Spanish stores. = 4.8.0 = * Added support for the WooCommerce Cart & Checkout Blocks, the default checkout on new stores. Previously the Checkout Block showed "There are no payment methods available" even with the gateway enabled. The block checkout supports new and saved cards, 3D Secure (frictionless and challenge), and the surcharge / card difference fees, which are listed in the Cart and Checkout blocks and saved on the order. The classic checkout and the pay-for-order page are unchanged. * Payment errors now reach the customer in both checkouts: the gateway returns a failure result instead of an empty one, so the API message (e.g. `INVALID CREDENTIALS (Error code: 1)`) is no longer discarded. = 4.7.9 = * Failed payments now show the message the Blackstone API returns, together with the response code, e.g. `INVALID CREDENTIALS (Error code: 1)`. Previously a generic text replaced the API message whenever the code was in the plugin's table, and only the first message was ever shown. The order note now records the code with its description, the API message and the verbiage. The response code table was replaced with the official one from the Blackstone API reference; the previous table (100-105, 500) did not match the codes the API returns. = 4.7.8 = * Added the `Source` field to refund requests so all transactions sent to Monetra carry the originating-plugin identifier. Sale and SaleWithToken payloads already included it; the refund payload was the only transaction-generating request missing it. Value remains `BPaydPlugin` (mapped to enum 5 by Monetra) — no behavior change for existing sales, no `ConnectionSource` is sent. = 4.7.7 = * Fixed Blackstone Refund buttons not appearing on the order edit screen under High-Performance Order Storage (HPOS). The detector relied on `get_post_type() === 'shop_order'`, which returns `'shop_order_placehold'` when HPOS is active without compatibility sync, so the refund JavaScript was never enqueued. The detector now accepts the placeholder type and falls back to `wc_get_order()` for storage-agnostic resolution, covering Legacy, HPOS+sync, and HPOS-only configurations. = 4.7.6 = * Fixed pay-for-order pages charging the original order amount instead of the current items total when the admin modified items without clicking "Recalculate" — the persisted order total is now refreshed automatically before rendering the customer pay page and again defensively before charging the API. An order note records every recalculation for auditing. Skipped on orders carrying surcharge/card-difference fee metadata to preserve the existing fee flow. = 4.7.5 = * Fixed 3DS verification not triggering on the pay-for-order page on sites with translated WooCommerce slugs — detection now uses the pay_for_order=true query parameter instead of the English-only order-pay URL slug. = 4.7.4 = * Added client-side UUID generation for clientTransactionId using crypto.randomUUID() with Math.random() fallback; each checkout attempt generates a unique identifier. * Added automatic JWT refresh on 401 errors from the 3DS SDK — refreshes server-side token and retries verify() once with a new clientTransactionId. * Added "Force 3DS (Sandbox only)" admin toggle to bypass the merchant API flag during sandbox testing; automatically selects sandbox endpoint when active. * Added billing address, email, city, state, and ISO 3166-1 numeric country code to 3DS form data fields. * Added ISO 4217 numeric currency code conversion with MXN support. * Fixed 3DS challenge iframe sizing — scoped CSS injected in document.head prevents SDK from overriding iframe dimensions; modal width set to 460px, iframe fixed at 390x400. * Fixed