Medusa setup guide

Overview

Install the Medusa payment provider to create hosted MakePay checkout links and reconcile sessions through signed webhooks.

• Connector type: Medusa v2 provider
• Medusa payment module
• Hosted checkout sessions
• Webhook payment status sync
• Source package: github.com/makepay-io/medusa-plugin-makepay

Before you start

Prepare MakeCrypto and the destination platform before installing the connector.

• Create or select the MakeCrypto merchant company.
• Create a MakePay API key for server-side payment-link creation.
• Choose a public HTTPS callback URL for signed MakePay webhooks.
• Confirm Medusa can store the MakePay payment UID or hosted checkout URL on the source record.

Install the connector

Clone or fork the source package, follow the repository README, and deploy it where it can reach both MakePay and Medusa.

git clone https://github.com/makepay-io/medusa-plugin-makepay

Pin the reviewed commit or release tag in production. Keep deployment secrets in the host platform, not in committed files.

Connect MakePay

Store the MakePay key ID and secret in the connector environment. The connector should call MakePay from a trusted server route, function, worker, or app backend.

• Follow the authentication guide for API key headers and rotation.
• Never expose MakePay secrets in browser scripts, templates, mobile clients, or exported platform configuration.
• Use separate credentials for preview, staging, and production.

Create checkout

Map the platform order, invoice, form, workflow, or entitlement request to a MakePay payment link. Include a stable order ID, amount, display currency, customer email when available, return URL, and metadata that lets support teams trace the payment later.

See the payment links API guide for request fields and response handling.

Webhooks and reconciliation

Expose a webhook endpoint, verify the MakePay signature from the raw request body, and update Medusa idempotently.

• Use the webhook guide for signature verification and retry behavior.
• Store MakePay payment UID, platform record ID, amount, currency, and normalized status together.
• Deduplicate by MakePay payment UID and webhook delivery ID before granting access, marking invoices paid, or syncing entitlements.

Test and go live

1. Create a low-value test order, invoice, entry, or entitlement.
2. Confirm the connector opens hosted MakePay checkout.
3. Complete a payment and verify the original platform record updates exactly once.
4. Rotate test credentials before switching production traffic.

Troubleshooting

Checkout does not open

Confirm the API key belongs to the selected merchant company and the connector can reach the MakePay API from its deployed environment.

Webhook is not accepted

Verify the route uses the exact raw body for HMAC verification and that the configured webhook secret matches MakeCrypto.

Duplicate events arrive

Keep updates idempotent by MakePay payment UID and webhook delivery ID. Duplicate delivery is expected during retry-safe payment flows.