@paymove-io/sdk

Official Paymove SDK for payment integration.

Requirements

• Node.js >= 18.0.0

Installation

npm install @paymove-io/sdk

Usage

import { PaymoveClient, PaymoveApiError } from '@paymove-io/sdk';

// Initialize the client
const client = new PaymoveClient({
  apiKey: 'your-api-key',
  merchantId: 'your-merchant-id',
  environment: 'sandbox', // or 'production'
});

// Create a payment
try {
  const response = await client.createPayment({
    amount: 1000, // amount in smallest currency unit (e.g., cents)
    currency: 'PLN',
    orderId: 'order-123',
    returnUrl: 'https://your-shop.com/success',
    // optional: description
    description: 'Payment for order #123',
    // optional: any additional custom fields
    customField: 'custom-value',
  });

  // Redirect user to payment page
  console.log(response.redirectUrl);
} catch (error) {
  if (error instanceof PaymoveApiError) {
    console.error('API Error:', error.statusCode, error.message);
  }
}

API Reference

PaymoveClient

Constructor

new PaymoveClient(config: PaymoveConfig)

| Parameter | Type | Description | |-----------|------|-------------| | config.apiKey | string | Your Paymove API key | | config.merchantId | string | Your merchant ID | | config.environment | 'sandbox' \| 'production' | API environment |

Methods

createPayment(params)

Creates a new payment and returns the response with redirect URL.

client.createPayment(params: CreatePaymentParams): Promise<PaymentResponse>

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | amount | number | Yes | Payment amount in smallest currency unit | | currency | string | Yes | Currency code (e.g., 'PLN', 'EUR') | | orderId | string | Yes | Your unique order identifier | | returnUrl | string | Yes | URL to redirect after payment | | description | string | No | Payment description | | [key] | unknown | No | Additional custom fields |

Returns: Promise<PaymentResponse> - Response containing redirectUrl and other API fields.

Error Handling

The SDK provides custom error classes for different error scenarios:

PaymoveValidationError

Thrown when input validation fails.

import { PaymoveValidationError } from '@paymove-io/sdk';

try {
  await client.createPayment({ /* invalid params */ });
} catch (error) {
  if (error instanceof PaymoveValidationError) {
    console.error('Validation failed for field:', error.field);
    console.error('Message:', error.message);
  }
}

PaymoveApiError

Thrown when the API returns an error response.

import { PaymoveApiError } from '@paymove-io/sdk';

try {
  await client.createPayment({ /* params */ });
} catch (error) {
  if (error instanceof PaymoveApiError) {
    console.error('Status code:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response body:', error.responseBody);
  }
}

PaymoveNetworkError

Thrown when a network error occurs.

import { PaymoveNetworkError } from '@paymove-io/sdk';

try {
  await client.createPayment({ /* params */ });
} catch (error) {
  if (error instanceof PaymoveNetworkError) {
    console.error('Network error:', error.message);
    console.error('Original error:', error.cause);
  }
}

TypeScript Support

This package is written in TypeScript and includes type definitions.

import type {
  PaymoveConfig,
  CreatePaymentParams,
  PaymentResponse,
  Environment,
} from '@paymove-io/sdk';

License

MIT