2Checkout ConvertPlus Hosted Payments — setup and reference

Module and release scope

This guide covers 2Checkout ConvertPlus Hosted Payments 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Order environment	select	Yes	Default: "sandbox" Choices: sandbox = Test orders on the merchant account, live = Live orders
merchant_code — Merchant code	text	Yes	Use the account-specific value described below.
secret_key — API and IPN secret key	secret	Yes	Use the account-specific value described below.
buy_link_secret — Buy-link secret word	secret	Yes	The separate ConvertPlus signing secret under Integrations → Webhooks & API. Dynamic ConvertPlus must be approved for this account.
currencies — Enabled invoice currencies	text	Yes	Default: "USD" Invoice currencies approved for this merchant. Configure tax-inclusive dynamic prices so checkout total remains equal to the invoice.

This module is 2Checkout ConvertPlus with API6 orders and IPN, for eligible 2Checkout accounts. It is not the separate Verifone Checkout API or a legacy 2Sell INS integration. Dynamic hosted ordering must be approved on the account. No card SDK or raw card fields are used.

1. In Integrations → Webhooks & API obtain the merchant code, API/IPN secret key and separate buy-link secret word. Enable REST6 order-read and ConvertPlus signature access.
2. Enter only invoice currencies approved on the account. Dynamic prices must be tax-inclusive and the checkout total must equal the invoice; configure provider tax/promotion settings accordingly. Unexpected totals are held for review rather than silently converted or allocated.
3. Configure IPN to EmailaBiller's exact displayed webhook URL. Enable completed payment notifications with REFNO, REFNOEXT, IPN_PID[], IPN_PNAME[], IPN_DATE and SHA2-256 or SHA3-256 signatures. Legacy MD5 IPN is deliberately unsupported.
4. Test retrieves an unissued external-reference order search without creating an order or charge. Complete a signed ConvertPlus test order to verify signing access and IPN delivery. Test mode uses the same merchant endpoints with test=1; live omits this flag.

Checkout is signed by the official ConvertPlus signature API using a short-lived HS512 merchant-token. It carries a unique order reference, invoice item reference, exact amount/currency and expiring hosted URL. Browser returns, IPN and reconciliation retrieve the current merchant-scoped order using documented SHA3 API authentication. The allocated amount uses GrossDiscountedPrice, the actual shopper total after discounts; the undiscounted GrossPrice is never used as payment. Only COMPLETE, fraud-approved orders without a chargeback and with matching test/live mode are accepted; AUTHRECEIVED is authorization only and remains unpaid. IPN signatures cover all ordered posted values. After successful processing the module emits the provider's signed XML receipt using the original product ID, product name, IPN date and current receipt date. Invalid IPNs receive no signed acknowledgement.

Official references: 2Checkout PHP SDK and API6/ConvertPlus implementations, Current signature API request shapes, ConvertPlus URL parameters, Order response states, IPN signed receipt.

Install this signed package under System → Payment gateways → Install module. New installations are disabled. Create a separate connection, enter your own merchant credentials, run Test, and explicitly enable that connection after completing sandbox checkout and callback testing. No merchant credentials or business settings are included in this package.

The module uses verified HTTPS with fixed official provider endpoints, no redirects or automatic API retries, bounded uncompressed responses, exact two-decimal invoice accounting, and credential-safe errors. Network timeouts leave payment under review: inspect the provider before retrying. Provider methods depend on merchant approval, payer location, currency and device; installing this module does not promise every payment method. The module never collects card numbers, expiry dates or CVV.