medusa-mastercard-payment/README.md

A starter for Medusa plugins.

# Medusa Mastercard Payment Plugin

A payment plugin for Medusa that enables Mastercard payment processing in your e-commerce store.

## Features

- Implements Mastercard Hosted Checkout integration
- Supports AUTHORIZE and CAPTURE payment operations
- Simple configuration through environment variables

## Installation

```bash
yarn add medusa-mastercard-payment
```

## Configuration

1. Add the following environment variables to your `.env` file:

```bash
MERCHANT_NAME=your_merchant_name
MERCHANT_URL=your_merchant_url
RETURN_URL=your_return_url
GATEWAY_URL=your_gateway_url
API_VERSION=your_api_version
MERCHANT_ID=your_merchant_id
MERCHANT_KEY=your_merchant_key
```

2. Add the plugin to your `medusa-config.ts` file:

```js
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "medusa-mastercard-payment",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-mastercard-payment/providers/mastercard",
            id: "mastercard-payment",
            options: {
              merchantName: process.env.MERCHANT_NAME,
              merchantUrl: process.env.MERCHANT_URL,
              returnUrl: process.env.RETURN_URL,
              gatewayUrl: process.env.GATEWAY_URL,
              apiVersion: process.env.API_VERSION,
              merchantId: process.env.MERCHANT_ID,
              merchantKey: process.env.MERCHANT_KEY,
            },
          },
        ],
      },
    },
    // ...
  ],
});
```

## Frontend Integration

You'll need to implement the Mastercard Hosted Checkout in your frontend. The plugin supports both Embedded Page and Payment Page implementations.

### Implementing the Hosted Payment Page

You have two options for implementing the Hosted Payment Page:

1. **Embedded Page**: A component that is activated within your existing checkout page
2. **Payment Page**: A separate page to which the customer is redirected from your checkout page

#### Basic Implementation Steps

1. **Create a Checkout object** by including the Mastercard script:

```html
<script
  src="https://test-gateway.mastercard.com/static/checkout/checkout.min.js"
  data-error="errorCallback"
  data-cancel="cancelCallback"
></script>
```

2. **Configure the checkout object** with the session ID from your backend:

```javascript
Checkout.configure({
  session: {
    id: "<your_initiate_checkout_ID>",
  },
});
```

3. **Start the payment process** using one of these methods:

```javascript
// For Embedded Page
Checkout.showEmbeddedPage("#embed-target");

// For Payment Page
Checkout.showPaymentPage();
```

4. **Implement callbacks** for handling payment events:

```javascript
function errorCallback(error) {
  console.log(JSON.stringify(error));
}

function cancelCallback() {
  console.log("Payment cancelled");
}

function completeCallback() {
  console.log("Payment completed");
  // Redirect to order confirmation page
}
```

For more detailed frontend implementation instructions, please refer to the [Mastercard Hosted Checkout documentation](https://ap-gateway.mastercard.com/api/documentation/integrationGuidelines/hostedCheckout/implementingTheHostedPaymentPage.html?locale=en_US).

## License

MIT