GoblinPay/connectors/medusa/README.md

GoblinPay for Medusa

Accept Grin (GRIN / MimbleWimble) payments in a Medusa v2 store through a self-hosted GoblinPay server. The customer pays from their Goblin Wallet by scanning an nprofile QR code. The payment travels as a gift-wrapped slatepack over Nostr (optionally over the Nym mixnet). GoblinPay receives it, returns the reply slatepack to the payer, watches the chain to confirm, and notifies Medusa through a signed webhook.

This provider is a thin client. All of the Grin and Nostr work happens in GoblinPay; Medusa only talks HTTP to your GoblinPay instance. No BTCPay, no node exposed to the store, no wallet RPC.

What it does

• Registers a goblinpay payment provider in the Medusa v2 payment module.
• On checkout, calls GoblinPay to create an invoice for the payment session and stores the checkout details (pay_url, nprofile, qr_svg) on the session so your storefront can render the QR or redirect to GoblinPay's hosted /pay/<token> page.
• Captures the payment when GoblinPay reports it, via a signed webhook. If a webhook is missed, authorizePayment and getPaymentStatus poll GoblinPay for the invoice status as a fallback.

Requirements

• Medusa v2 (built against @medusajs/framework 2.12; 2.x expected to work).
• Node 20 or newer.
• A running GoblinPay server reachable from the Medusa host.

Options

Set these per-provider in medusa-config.ts (see INSTALL.md):

• baseUrl: base URL of your GoblinPay server, no trailing slash, for example https://pay.example.
• apiToken: the GoblinPay create-invoice bearer token (GP_API_TOKEN on the server).
• webhookSecret: the shared HMAC secret (GP_WEBHOOK_SECRET on the server).
• matchMode (optional): how GoblinPay ties an incoming payment to the order. derived (per-invoice identity, recommended) gives each order its own QR and is the most reliable. memo and amount are also available. Omit to use the server default.
• expirySecs (optional): invoice expiry in seconds from creation.

Webhook

GoblinPay reports payments to the Medusa payment module's built-in webhook route. Point your GoblinPay server's GP_WEBHOOK_URL at:

https://YOUR-MEDUSA-HOST/hooks/payment/goblinpay_goblinpay

The provider verifies the X-GoblinPay-Signature: sha256=<hmac> header against the exact raw body (constant-time) before acting.

Status mapping

GoblinPay	Medusa payment session
invoice open	pending
invoice paid	captured
invoice expired	canceled
webhook payment.received	captured (SUCCESSFUL)
webhook payment.confirmed	captured (SUCCESSFUL, idempotent)

For a receive-only till, a received payment (the reply slatepack is back and the funds are in the merchant wallet) is treated as paid, the same as the WooCommerce connector. The later on-chain confirmation is an idempotent no-op.

Refunds

Refunds are not automated. GoblinPay is receive-only: it never sends Grin. A refund is therefore a manual, out-of-band Grin send by the merchant from a wallet under their control. refundPayment throws to make this explicit, the same caveat the Grin BTCPay connector carries.

Security notes

• The webhook is authenticated by an HMAC-SHA256 signature over the exact raw request body, compared in constant time. A bad or missing signature is rejected and the payment is not flipped.
• The capture amount is read from the Medusa payment session (its own store-currency amount), not from untrusted webhook fields.
• Secrets live in the provider options / environment, never in code.

Credit

Built by Claude (Anthropic) for the Goblin project.