MakePay for Medusa

Official MakePay payment provider for Medusa v2. The provider creates hosted MakePay checkout links for Medusa payment sessions and reconciles payment status through signed MakePay webhooks.

Need MakePay credentials? Register your merchant account at makepay.io before configuring this plugin. Your merchant account provides the API key and webhook secret used below.

Install

npm install @makecrypto/medusa-plugin-makepay

Configure

Register MakePay as a provider under the Medusa Payment Module:

// medusa-config.ts
import { defineConfig, Modules } from "@medusajs/framework/utils";

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@makecrypto/medusa-plugin-makepay/providers/makepay",
            id: "makepay",
            options: {
              keyId: process.env.MAKEPAY_KEY_ID!,
              keySecret: process.env.MAKEPAY_KEY_SECRET!,
              webhookSecret: process.env.MAKEPAY_WEBHOOK_SECRET!,
              settlementCurrency:
                process.env.MAKEPAY_SETTLEMENT_CURRENCY || "USDT",
              expirationTime: "12h",
            },
          },
        ],
      },
    },
  ],
});

The default Medusa payment webhook URL for the provider is:

/hooks/payment/makepay_makepay

Configure that URL in MakePay developer settings and store the generated webhook secret as MAKEPAY_WEBHOOK_SECRET.

Options

Option	Required	Description
keyId	yes	MakePay API key ID.
keySecret	yes	MakePay API key secret.
webhookSecret	yes	MakePay webhook signing secret.
baseUrl	no	MakeCrypto API base URL. Defaults to production.
checkoutBaseUrl	no	MakePay hosted checkout base URL. Defaults to production.
settlementCurrency	no	Settlement symbol sent to MakePay. Defaults to USDT.
expirationTime	no	Hosted link expiration. Defaults to 12h.
returnUrl	no	Fallback return URL for MakePay checkout.
successUrl	no	Success return URL for MakePay checkout.
failureUrl	no	Failure return URL for MakePay checkout.
webhookToleranceSeconds	no	Signature timestamp tolerance for MakePay webhooks.

Storefront flow

initiatePayment returns provider data with a hosted checkout URL:

paymentSession.data.next_action
// { type: "redirect", url: "https://makepay.io/payment/..." }

Redirect shoppers to that URL, then use MakePay webhooks to update the Medusa payment session when the payment is completed, canceled, or failed.

If Medusa updates an unpaid payment session because the cart amount or fiat currency changed, the provider archives the old MakePay link and creates a new hosted checkout link for the updated session.

Development

npm ci
npm run check

npm run check builds the TypeScript provider, runs the unit tests, and verifies the npm package contents with npm pack --dry-run.