@paymove-io/sdk

Official Paymove SDK for payment integration.

Requirements

- Node.js >= 18.0.0

Installation

``bash
npm install @paymove-io/sdk
`

Usage

`typescript
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: locale
locale: 'pl-PL'
//optional: Iban account
bankAccount: 'PL10105000997623123456789123'
// 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

$3

#### Constructor

`typescript
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.

`typescript
client.createPayment(params: CreatePaymentParams): Promise
`

| 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 |
| locale | string | No | Locale |
| bankAccount | string | No | Iban account |
| [key] | unknown | No | Additional custom fields |

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

Error Handling

The SDK provides custom error classes for different error scenarios:

$3

Thrown when input validation fails.

`typescript
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);
}
}
`

$3

Thrown when the API returns an error response.

`typescript
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);
}
}
`

$3

Thrown when a network error occurs.

`typescript
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.

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

License

MIT