Paytrail

Paytrail Payment Provider Plugin

Paytrail payment provider plugin for Medusa v2.

This package is published to NPM as Copy to clipboard@solteq-excom/medusa-payment-paytrail.

Install

Add the package to your Medusa backend:

1
yarn add @solteq-excom/medusa-payment-paytrail

Register the plugin and payment provider in your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
plugins: [
  {
    resolve: "@solteq-excom/medusa-payment-paytrail",
    options: {},
  },
],
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@solteq-excom/medusa-payment-paytrail/providers/paytrail",
          id: "paytrail",
          options: {
            merchantId: Number(process.env.PAYTRAIL_MERCHANT_ID),
            secretKey: process.env.PAYTRAIL_SECRET_KEY,
            platformName: process.env.PAYTRAIL_PLATFORM_NAME ?? "MedusaJS",
            callbackBaseUrl: process.env.PAYTRAIL_CALLBACK_BASE_URL,
            callbackDelay: process.env.PAYTRAIL_CALLBACK_DELAY

Configuration

Required and supported environment variables:

• Copy to clipboardPAYTRAIL_MERCHANT_ID
• Copy to clipboardPAYTRAIL_SECRET_KEY
• Copy to clipboardPAYTRAIL_PLATFORM_NAME (optional)
• Copy to clipboardPAYTRAIL_CALLBACK_BASE_URL (recommended, must use HTTPS)
• Copy to clipboardPAYTRAIL_CALLBACK_DELAY (optional, seconds, 0-900, default Copy to clipboard0)
• Copy to clipboardPAYTRAIL_REDIRECT_URL_HOST_WHITELIST (required, comma-separated Copy to clipboardhost[:port] values; Copy to clipboard* wildcard supported)
• Copy to clipboardPAYTRAIL_LANGUAGE (Copy to clipboardFI, Copy to clipboardSV, or Copy to clipboardEN)

Example:

1234567
PAYTRAIL_MERCHANT_ID=375917
PAYTRAIL_SECRET_KEY=SAIPPUAKAUPPIAS
PAYTRAIL_PLATFORM_NAME=MedusaJS
PAYTRAIL_CALLBACK_BASE_URL=https://your-backend.example.com
PAYTRAIL_CALLBACK_DELAY=0
PAYTRAIL_REDIRECT_URL_HOST_WHITELIST=localhost:8888,store.example.com,*.foo.bar.baz,pr-*.foo.bar.baz
PAYTRAIL_LANGUAGE=EN

If Copy to clipboardPAYTRAIL_CALLBACK_BASE_URL is set, the provider sends Paytrail Copy to clipboardcallbackUrls automatically as:

• success: Copy to clipboard{PAYTRAIL_CALLBACK_BASE_URL}/hooks/paytrail
• cancel: Copy to clipboard{PAYTRAIL_CALLBACK_BASE_URL}/hooks/paytrail

Copy to clipboardPAYTRAIL_CALLBACK_DELAY maps to Paytrail Copy to clipboardcallbackDelay (seconds). According to Paytrail, when callback URLs are provided, callback delay can be Copy to clipboard0 to Copy to clipboard900 seconds and defaults to Copy to clipboard0.

Paytrail requires HTTPS callback URLs for both success and cancel callbacks. Example uses Paytrail test credentials

When creating payment sessions, Copy to clipboardinput.data.redirect_success and Copy to clipboardinput.data.redirect_cancel must use Copy to clipboardhttp or Copy to clipboardhttps, include only host/path (no query/hash/auth), and the host must match Copy to clipboardPAYTRAIL_REDIRECT_URL_HOST_WHITELIST.

Copy to clipboardPAYTRAIL_REDIRECT_URL_HOST_WHITELIST supports wildcard host patterns with Copy to clipboard*, for example:

• Copy to clipboard*.foo.bar.baz
• Copy to clipboardpr-*.foo.bar.baz

Features

• Payment session initiation via Paytrail API
• Payment status check for authorization flow
• Refund support
• Callback action parsing and HMAC signature verification
• Custom GET callback route for Paytrail redirect and callback query params

Callback Route

The plugin exposes Copy to clipboardGET /hooks/paytrail for Paytrail redirect and callback handling.

The route forwards callback payloads into Medusa's payment webhook pipeline by emitting Copy to clipboardPaymentWebhookEvents.WebhookReceived after validating the signature.

Behavior

• Currency support is limited to Copy to clipboardEUR by Paytrail.
• Payment sessions are created in Copy to clipboardpending status until Paytrail authorizes them.
• Cart completion fails before third-party authorization.
• Standard Paytrail flow is treated as auto-captured after authorization.

Payment Flow

1. Store creates a payment session with provider Copy to clipboardpp_paytrail_paytrail.
2. Paytrail returns a redirect URL and Copy to clipboardtransactionId.
3. Customer authorizes the payment in Paytrail checkout.
4. Callback updates the payment status to authorized or captured.
5. Cart completion succeeds after authorization.

Troubleshooting

No payment providers available in store

• Ensure the Paytrail provider is linked to the region.

Cart completion returns 400 not authorized

• This is expected before the Paytrail authorization callback is processed.
• Complete the payment in Paytrail before completing the cart.

Callback is not triggered

• Verify Copy to clipboardPAYTRAIL_CALLBACK_BASE_URL is configured with an HTTPS URL.
• Paytrail requires HTTPS callback URLs for both success and cancel callbacks.

Contributing

Bug reports and feature requests are welcome.

When submitting an issue, include:

• A clear description of the problem or requested change
• Steps to reproduce, if applicable
• Relevant configuration details, logs, or screenshots

When submitting a pull request:

• Open an issue first for larger changes so the approach can be discussed
• Keep the PR focused on a single fix or feature
• Include tests or updates to existing tests when behavior changes
• Update the README or other documentation if the public behavior changes

Disclaimer

This package is provided as-is, without warranty of any kind. You are responsible for validating the integration, security, and compliance requirements before using it in production.

References

• Official Paytrail API documentation