tpay Payment Integration

#tpay Payment Integration

medusa-tpay is a payment provider plugin that integrates tpay payment processing with your Medusa commerce platform.

#Compatibility

This plugin is compatible with Medusa v2.4.0+.

#Installation

Install the plugin using npm or yarn:

npm install medusa-tpay
# or
yarn add medusa-tpay

#Configuration

Add the tpay payment provider to your medusa-config.ts:

modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "medusa-tpay/providers/tpay",
          options: {
            clientId: process.env.TPAY_CLIENT_ID,
            clientSecret: process.env.TPAY_CLIENT_SECRET,
            merchantId: process.env.TPAY_MERCHANT_ID,
            sandbox: process.env.TPAY_SANDBOX === "true",
            returnUrl: process.env.TPAY_RETURN_URL,
            // Webhook callback URL (defaults to APP_BASE_URL + /hooks/payment/tpay)
            callbackUrl: process.env.TPAY_CALLBACK_URL || `${process.env.APP_BASE_URL}/hooks/payment/tpay`,
            title: "Payment for order", // Optional
            refundDescription: "Refund", // Optional
          },
        },
      ],
    }
  }
]

#Environment Variables

You'll need to set the following environment variables:

TPAY_CLIENT_ID=your_client_id
TPAY_CLIENT_SECRET=your_client_secret
TPAY_MERCHANT_ID=your_merchant_id
TPAY_SANDBOX=true # or false for production
TPAY_RETURN_URL=https://yourstore.com/checkout/return
TPAY_CALLBACK_URL=https://yourstore.com/hooks/payment/tpay
APP_BASE_URL=https://yourstore.com

Get these credentials from your tpay dashboard.

#Usage

#Required Data

When initiating a tpay payment session, provide the following customer data:

const tpayData = {
  customer_name: string;  // Customer's full name
  email: string;          // Customer's email address
}

This data should be passed in your checkout flow when calling initiatePaymentSession.

#Webhook Configuration

The webhook endpoint is automatically registered at /hooks/payment/tpay.

Important setup steps:

• Your callbackUrl must point to this endpoint (e.g., https://yourdomain.com/hooks/payment/tpay)
• The endpoint must be publicly accessible
• Configure your firewall to allow incoming requests from tpay's servers
• Add the callback URL to your tpay account settings

#Refunds

The plugin supports partial and full refunds through Medusa's admin panel or API. You can customize the refund description by setting the refundDescription option in configuration.

#Sandbox Mode

For testing, enable sandbox mode:

TPAY_SANDBOX=true

Use test payment methods provided by tpay in sandbox environment.

#tpay Resources

• tpay Homepage
• tpay Developer Documentation
• tpay Test Environment