payload-corvuspay-adapter

CorvusPay payment gateway adapter for PayloadCMS ecommerce plugin.

CorvusPay is a Croatian payment gateway supporting credit cards in Serbia, Croatia, and Slovenia. Currently supports RSD (Serbian Dinar) currency.

Features

• Full integration with @payloadcms/plugin-ecommerce
• HMAC-SHA256 signature verification
• Built-in mock mode for development
• TypeScript support with full type safety
• Test mode support for sandbox payments

Installation

npm install payload-corvuspay-adapter
# or
pnpm add payload-corvuspay-adapter
# or
yarn add payload-corvuspay-adapter

Requirements

• PayloadCMS 3.x
• @payloadcms/plugin-ecommerce ^3.60.0

Quick Start

1. Server Configuration

Add the CorvusPay adapter to your Payload ecommerce plugin configuration:

// payload.config.ts
import { buildConfig } from 'payload'
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { corvuspayAdapter } from 'payload-corvuspay-adapter'

export default buildConfig({
  // ... other config
  plugins: [
    ecommercePlugin({
      payments: {
        paymentMethods: [
          corvuspayAdapter({
            storeId: process.env.CORVUSPAY_STORE_ID!,
            secretKey: process.env.CORVUSPAY_SECRET_KEY!,
            testMode: process.env.NODE_ENV !== 'production',
            lang: 'sr', // or 'en', 'hr', 'sl'
          }),
        ],
      },
      // ... other ecommerce config
    }),
  ],
})

2. Client Configuration

Add the client adapter to your EcommerceProvider:

// providers.tsx
import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client/react'
import { corvuspayAdapterClient } from 'payload-corvuspay-adapter/client'

export function Providers({ children }) {
  return (
    <EcommerceProvider
      paymentMethods={[
        corvuspayAdapterClient({ label: 'Karticom (CorvusPay)' }),
      ]}
    >
      {children}
    </EcommerceProvider>
  )
}

3. Environment Variables

CORVUSPAY_STORE_ID=your-store-id
CORVUSPAY_SECRET_KEY=your-secret-key

Configuration Options

Server Adapter (corvuspayAdapter)

| Option | Type | Default | Description | |--------|------|---------|-------------| | storeId | string | required | CorvusPay Store ID from Merchant Portal | | secretKey | string | required | CorvusPay Secret Key for HMAC signatures | | testMode | boolean | false | Enable CorvusPay sandbox environment | | lang | string | 'sr' | Payment page language (sr, en, hr, sl) | | requireComplete | boolean | false | Enable two-phase (auth + capture) transactions | | label | string | 'CorvusPay' | Display label | | serverUrl | string | auto | Base URL for return redirects |

Client Adapter (corvuspayAdapterClient)

| Option | Type | Default | Description | |--------|------|---------|-------------| | label | string | 'CorvusPay' | Display label for payment method |

Mock Mode (Development)

For development without real CorvusPay credentials, use mock mode by setting:

corvuspayAdapter({
  storeId: 'test-store-id',
  secretKey: 'test-secret-key',
  // ... other options
})

In mock mode:

• No real API calls are made
• Payments are automatically "successful"
• Transaction IDs start with MOCK-
• Perfect for local development and testing

Payment Flow

1. Customer initiates checkout - initiatePayment() is called
2. Transaction created in database with status pending
3. Checkout params built with HMAC-SHA256 signature
4. Customer redirected to CorvusPay payment page
5. Customer completes payment on CorvusPay
6. Customer returns to /checkout/confirm-order?order_number=...
7. Signature verified from callback parameters
8. confirmOrder() called - verifies payment via API
9. Order created if payment approved
10. Cart marked as purchased, transaction updated to succeeded

Webhook Support

CorvusPay sends async payment notifications. Configure the webhook URL in your CorvusPay Merchant Portal:

https://yourdomain.com/api/payments/corvuspay/webhook

Webhook Implementation

// app/api/payments/corvuspay/webhook/route.ts
import { verifySignature } from 'payload-corvuspay-adapter'

export async function POST(request: Request) {
  const formData = await request.formData()
  const params: Record<string, string> = {}

  for (const [key, value] of formData.entries()) {
    params[key] = String(value)
  }

  const signature = params.signature
  const secretKey = process.env.CORVUSPAY_SECRET_KEY!

  if (!verifySignature(params, signature, secretKey)) {
    return new Response('Invalid signature', { status: 400 })
  }

  // Process webhook...
  return new Response('OK')
}

Transaction Fields

The adapter adds a corvuspay group field to transactions with:

• orderNumber - Internal order reference
• transId - CorvusPay Transaction ID
• status - Payment status (approved, etc.)
• approvalCode - Bank approval code
• responseCode - Response code (00 = success)
• maskedPan - Masked card number
• cardBrand - Card brand (Visa, Mastercard, etc.)

Getting CorvusPay Credentials

1. Register at CorvusPay Merchant Portal (production) or Test Portal (sandbox)
2. Complete merchant verification
3. Get your Store ID and Secret Key
4. Configure success/cancel/webhook URLs

TypeScript

Full TypeScript support with exported types:

import type {
  CorvusPayAdapterArgs,
  CorvusPayAdapterClientArgs,
  CorvusPayLanguage,
  CorvusPayCheckoutRequest,
  CorvusPayCallbackParams,
  CorvusPayWebhookPayload,
  CorvusPayStatusResponse,
} from 'payload-corvuspay-adapter'

Advanced Usage

Custom Transaction Fields

Override the default CorvusPay group fields:

corvuspayAdapter({
  storeId: '...',
  secretKey: '...',
  groupOverrides: {
    fields: ({ defaultFields }) => [
      ...defaultFields,
      {
        name: 'customField',
        type: 'text',
        label: 'Custom Field',
      },
    ],
  },
})

Direct API Access

For advanced scenarios, you can use the API utilities directly:

import {
  calculateSignature,
  verifySignature,
  buildCheckoutParams,
  getPaymentStatus,
  CORVUSPAY_CHECKOUT_URL,
  CORVUSPAY_CHECKOUT_URL_TEST,
} from 'payload-corvuspay-adapter'

Currency Support

Currently supports RSD (Serbian Dinar) only. The adapter validates currency and throws an error for non-RSD transactions.

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

MIT © blaze IT s.r.o.

Links

• CorvusPay Documentation
• CorvusPay Test Merchant Portal
• PayloadCMS Ecommerce Plugin