Openborder

Open Border Medusa payment plugin

Medusa payment and tax provider bridge for Open Border. Medusa owns the storefront, cart, order, and fulfillment flow; Open Border owns Merchant-of-Record tax, duty, payment-intent, entity-routing, and ledger state.

This package is intentionally thin. It stores no authoritative money state and calls the Open Border API through the Node SDK.

Setup instructions are canonical at /guides/medusa. That published page is the step-by-step setup guide; this README stays the detailed integration reference for package consumers. When the two disagree about a setup step, the published guide wins — update it in the same change.

Package pages

• npmjs public package: @open-border/medusa-payment-openborder
• Browser checkout element: @open-border/js
• Node SDK: @open-border/node
• Public demo source: OpenBorder/openborder-medusa-demo

Upgrading from 0.7.x

A tax quote is now required on every charge. Open Border rejects a payment intent with no tax_quote_id as a validation_error, so a cart that reaches payment-session creation without a quote id fails closed in the plugin rather than charging an untaxed total. Run the Open Border tax provider on the cart before creating the payment session, and keep the server-issued amount_breakdown alongside the quote id.

If your storefront relied on creating a session for an unquoted cart, that path no longer produces a charge — quote first. This narrows the published input contract, so the first release containing it is a breaking 0.x minor (0.8.0), never a 0.7.x patch.

Upgrading from 0.6.x

The unified Medusa major-unit boundary is a breaking change for the sibling money fields. The first release containing it must be a new 0.x minor (0.7.0 or later), never a 0.6.x patch.

In 0.6.x, the provider already treated Medusa's payment amount as major units, but shipping_amount and line_items[].unit_amount were documented and forwarded as Open Border minor units. Starting with 0.7.0, pass all three as Medusa major-unit values:

Update the payment-session and tax-provider inputs atomically before upgrading. Integer major and minor values are ambiguous, so the plugin cannot safely auto-detect a mixed old/new payload. Quoted payment sessions must also retain the server-issued amount_breakdown alongside the quote id so the provider can reconcile Medusa's payment total before authorization. Keep that breakdown exactly as returned; its fields remain integer minor units.

Install

Install the public npm packages. No .npmrc or registry token is required:

Configuration

Configure the Medusa server with an Open Border secret key. Keep this key server-side only.

Key rules:

• OPENBORDER_API_KEY is the sk_... key. It belongs on the Medusa server and is used by the plugin to quote tax/duty and create payment intents.
• OPENBORDER_PUBLISHABLE_KEY is the pk_... key. It is safe for browser code and is used by @open-border/js to tokenize the buyer's card into a pm_... payment method.
• Test and live rails do not mix. Use sk_test_... with pk_test_..., and sk_live_... with pk_live_....
• OPENBORDER_API_URL is optional outside local development because the SDK can choose the API host from the key rail. Pass it explicitly for local or internal staging environments.

Register the payment provider

Add the Open Border provider to the Medusa v2 Payment Module.

The provider identifier is openborder. With the provider id also set to openborder, Medusa stores the resolved provider id as pp_openborder_openborder.

Checkout flow

The integration is quote-before-pay:

1. Build Open Border line items from the Medusa cart.
2. Quote tax/duty for the buyer's ship-to destination.
3. Mount the browser checkout element with the quoted landed-cost total.
4. Send the resulting pm_... payment method back to the Medusa server.
5. Create or update the Medusa payment session with the payment method and quote id.
6. The Open Border provider creates the payment intent server-side.
7. Store the Open Border payment intent id and show the buyer the receipt/order ids.

1. Build quote line items

Use Medusa's major-unit values at the plugin boundary (for example, 25.00 for USD). The plugin converts every amount to Open Border's integer minor-unit contract after exactness checks. Each line item also needs an HS tariff code before the tax quote can be created.

If your catalog does not already store HS codes, classify products with Open Border before quoting and persist the resulting code back to your product/variant metadata.

2. Quote tax and duty

The plugin exposes a thin Open Border client seam for testable Medusa integrations:

US and CA destinations require at least one of destination_region or destination_postal_code. Forward the Medusa shipping address values as shown; other destinations may omit both.

quote.amount_breakdown.total is the landed-cost total to display before card collection. quote.tax_quote_id must travel with the payment session so Open Border can revalidate the quote when creating the payment intent.

3. Collect the payment method in the browser

Use the publishable key with @open-border/js. The browser element only tokenizes the card. It does not charge the buyer and never receives the secret key.

Only expose OPENBORDER_PUBLISHABLE_KEY and, when needed, a non-secret browser API URL. Do not serialize OPENBORDER_API_KEY into HTML, JavaScript, logs, analytics, or error telemetry.

4. Create or update the payment session

When the buyer submits the card element, put the Open Border payment method and quote data into the Medusa payment-session data. The provider reads these fields:

Required values:

• cart_id, session_id, or medusa_session_id - a persisted Medusa identity that remains stable across retries of the same payment session.
• payment_method or openborder_payment_method - the pm_... token from the browser element.
• openborder_tax_quote_id or tax_quote_id - the server-issued quote id. Required: Open Border prices every charge from a revalidated quote, so a cart with no quote is refused before any authorization.
• amount_breakdown - the server-issued quote breakdown, retained in minor units so the provider can reconcile Medusa's payment-collection total before authorization.
• line_items - the same item fingerprint used for the quote.
• shipping_amount - a Medusa major-unit value, when shipping was included in the quote.
• customer.email
• billing_address.line1 and billing_address.country
• shipping_address.line1 and shipping_address.country

Optional values:

• merchant_reference - usually the Medusa cart, order, or payment collection id. When omitted, the provider uses the required stable session identity.

Provider behavior

The payment provider maps a Medusa-shaped payment-session request into a manual-capture createPaymentIntent, so Medusa can authorize first and capture or cancel through its later payment lifecycle. Medusa passes money in major units (for example, 160.30 for USD), so the payment and tax providers exactness-check and convert the payment-collection total, shipping amount, and every line-item unit amount to Open Border minor units. The payment provider derives Open Border's merchandise subtotal from sum(quantity * unit_amount) because Medusa's amount is the full payment-collection total, including shipping and quoted tax or duty. Every payment requires the server-issued amount_breakdown; the provider checks its total, subtotal, shipping, and currency before authorization. The tax provider maps the normalized line items and destination context into createTaxQuote, returning the Open Border quote id and aggregate quote response. The plugin does not allocate tax or duty per line locally; Open Border remains the authoritative pricing source.

The Medusa wrapper derives operation-scoped Open Border idempotency keys. Initiate and update use the persisted payment-session identity, prior intent id, and canonical request body; capture and cancel use the persisted Open Border payment-intent id. A changed context.idempotency_key on a retry does not change those keys. Refunds keep their existing behavior: a stable Medusa refund reference is preferred, with the request context key used only when no refund reference exists. Status lookup reads the current Open Border payment-intent status and does not own local money state. An update cancels a live authorization before creating its replacement, and a canceled intent can be replaced. An update against a captured intent fails closed before cancellation or re-authorization so a completed payment cannot produce a second buyer hold.

If the provider is called before a payment method exists, it returns a pending session with openborder_requires_payment_method: true. After the browser returns a pm_... token, update the session and the provider will create the Open Border payment intent.

Receipt fields

After a successful payment-intent create, persist the returned Open Border ids alongside the Medusa order/payment collection:

• openborder_payment_intent_id
• openborder_status
• entity - the Open Border entity resolved from charge currency.
• amount_breakdown - subtotal, shipping, tax, duty, total, and currency.
• tax_quote_id
• client_secret, when returned by the payment processor flow.

These fields let support staff reconcile Medusa orders to Open Border transactions without making Medusa the source of truth for money.

Local and staging test mode

Local development:

Sandbox or internal staging:

Use test card numbers from the payment processor account attached to the resolved Open Border entity. The publishable key must belong to the same test rail as the secret key.

Demo preview vs public package guide

The demo source is maintained publicly in OpenBorder/openborder-medusa-demo. Its deterministic, keyless static build is hosted as a public preview and does not submit a real payment.

This README is the public integration guide for package consumers. Do not document the private demo-only helper routes in Scalar or treat the hosted preview as the required package integration path. External developers should install the package, register the provider, quote tax/duty server-side, collect a browser payment method with the publishable key, and let Open Border create the payment intent with the secret key on the Medusa server.

Current limitations

• The browser payment element comes from @open-border/js; this plugin does not render checkout UI by itself.
• Medusa webhook action handling currently returns not_supported. Wire provider webhooks and async reconciliation in a separate integration slice.
• Capture, cancel, refund, and payment-status lookup delegate to Open Border APIs. Capture and cancel keys are intent-derived; refunds need a stable refund reference or a request context key.
• The plugin does not allocate tax or duty per line locally. Open Border's quote and transaction snapshot are authoritative.
• The plugin does not persist Open Border ids into Medusa order metadata for you; do that in your checkout/order completion workflow.
• OpenBorderApiClient.reportFulfillment(...), correctFulfillment(...), and getFulfillment(...) are explicit server-side fulfillment seams. Responses keep OpenBorder's fulfillment state separate from nullable advisory Ship24 state in tracking_provider. The tracking_number is required; carrier is optional and may be omitted for Ship24 auto-detection. reportFulfillment also requires { idempotencyKey } because accepted tracking can release held funds. The package does not install an automatic Medusa lifecycle subscriber or guess fulfillment events.

Security checklist

• Keep sk_... keys server-side.
• Expose only pk_... keys to browser code.
• Use test keys and sandbox URLs until production activation is approved.
• Send payment-method tokens from the browser to your backend over HTTPS.
• Never log full API keys, payment method ids, card data, or customer addresses in public logs.
• Treat Open Border's payment intent, transaction snapshot, and amount breakdown as the authoritative money record.