Medusa AliPay Payment Provider

@gerbergpt/medusa-alipay is a Medusa V2 payment provider modeled after the official Medusa Stripe integration. It wires the AliPay gateway into the Payment Module so the provider can be selected during checkout, orders can be authorized/captured, and asynchronous updates are delivered through webhooks.

Platforms

• AliPay Business Account
• AliPay Developers
• Computer Client Payment Guidelines

Features

• 🔐 Implements the AbstractPaymentProvider contract with capture, refund, cancel, and status flows aligned with AliPay trade states.
• 💳 Uses alipay.trade.page.pay via the OpenAPI curl interface to create redirect-based payments and stores the AliPay payload on the payment session for later reconciliation.
• 🔁 Surfaces POST /hooks/alipay so AliPay can notify the Medusa backend. The hook feeds the same event-bus pipeline used by the Stripe provider (payment.webhook_received).
• ⚙️ Ships with option validation, sandbox toggles, configurable subjects/notify URLs, and signature verification to guard webhook calls.

Installation

yarn add @gerbergpt/medusa-payment-alipay
# or
npm install @gerbergpt/medusa-payment-alipay

Configuration

Register the provider in medusa-config.ts (or the file where you bootstrap modules):

module.exports = defineConfig({
  modules: [
    {
      key: Modules.PAYMENT,
      resolve: "@medusajs/payment",
      options: {
        providers: [
          {
            resolve: "@gerbergpt/medusa-payment-alipay/providers",
            id: "alipay",
            options: {
              appId: process.env.ALIPAY_APP_ID!,
              privateKey: process.env.ALIPAY_PRIVATE_KEY!,
              alipayPublicKey: process.env.ALIPAY_PUBLIC_KEY!,
              notifyUrl: "https://your-domain/hooks/alipay",
              sandbox: process.env.ALIPAY_ENV !== "production",
            },
          },
        ],
      },
    },
  ],
})

Available options

| Option | Description | | --- | --- | | appId | AliPay App ID (required). | | privateKey | Merchant RSA private key (PKCS8) used to sign requests (required). | | alipayPublicKey | AliPay RSA public key for webhook verification (required). | | notifyUrl | Override for the async notification callback URL. Defaults to the plugin webhook route. | | sandbox | When true, directs traffic to the AliPay sandbox gateway. | | gateway | Custom gateway URL. Useful for regional AliPay entrants. | | timeoutExpress | AliPay trade timeout window (defaults to 30m). | | defaultSubject | Fallback order description sent to AliPay. | | storeId | Optional AliPay store identifier for reconciliation. | | webhookValidation | Set to false to skip signature verification (not recommended). | | debug | Enables extra SDK logging. Defaults to false. |

Webhook setup

The Medusa application has a /hooks/payment/[identifier]_[provider] API route out-of-the-box that allows you to listen to webhook events from third-party payment providers, where:

• [identifier] is the identifier static property defined in the payment provider. For example, stripe.
• [provider] is the ID of the provider. For example, stripe.

For example, when integrating basic Stripe payments with the Stripe Module Provider, the webhook listener route is {store_url}/hooks/payment/alipay_alipay.

You can use this webhook listener when configuring webhook events in your third-party payment provider.

Development

1. Install Yarn

npm i -g yarn

2. Publish Alipay payment locally via yalc:

cd medusa-payment-alipay
yarn install
npx medusa plugin:publish

3. Navigate to your Medusa backend application and install the plugin:

npx medusa plugin:add @gerbergpt/medusa-payment-alipay

After installation, you should see an entry pointing to the local yalc package:

"dependencies": {
  ...,
  "@gerbergpt/medusa-payment-alipay": "file:.yalc/@gerbergpt/medusa-payment-alipay",
  ...
}

4. Configure your Medusa application (backend)

module.exports = defineConfig({
  modules: [
    {
      key: Modules.PAYMENT,
      resolve: "@medusajs/payment",
      options: {
        providers: [
          {
            resolve: "@gerbergpt/medusa-payment-alipay/providers",
            id: "alipay",
            options: {
              appId: process.env.ALIPAY_APP_ID!,
              privateKey: process.env.ALIPAY_PRIVATE_KEY!,
              alipayPublicKey: process.env.ALIPAY_PUBLIC_KEY!,
              notifyUrl: "https://{server}/hooks/payment/alipay_alipay",
              sandbox: process.env.ALIPAY_ENV !== "production",
            },
          },
        ],
      },
    },
  ],
})

5. If you need to move the local npm package bridged by yalc, just run:

npx yalc remove @gerbergpt/medusa-payment-alipay

Usage notes

• AliPay currently expects amounts in CNY. The provider rounds to 2 decimals (0 for JPY) before calling the API.
• The Initiate API stores the payment_url (and any additional payload) returned by alipay.trade.page.pay inside the payment session’s data field so storefronts can redirect customers to AliPay.
• authorizePayment/capturePayment mirror getPaymentStatus. When a webhook reports TRADE_SUCCESS or TRADE_FINISHED, Medusa’s processPaymentWorkflow captures the payment automatically.
• Return URLs are taken from the payment session payload so the storefront can point AliPay back to the active checkout page for the shopper’s current region rather than a static configuration value.
• Payment subjects default to the cart’s product names (joined) to surface a meaningful order title in AliPay; they fall back to a provided subject value, then the configured defaultSubject.

Troubleshooting

• yarn build compiles the plugin to .medusa/server.
• If you see Invalid AliPay webhook signature, confirm that the public key in your configuration matches the one configured on AliPay.
• Use the sandbox gateway (sandbox: true) together with the AliPay playground app to test QR flows locally.