npm package: @paymove-io/sdk
Description: Official Paymove SDK for payment integration
Author: Paymove
Latest version: 0.1.7

# @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',
    externalId: '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

### PaymoveClient

#### 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<PaymentResponse>
```

| Parameter     | Type      | Required | Description                              |
| ------------- | --------- | -------- | ---------------------------------------- |
| `amount`      | `number`  | Yes      | Payment amount in smallest currency unit |
| `currency`    | `string`  | Yes      | Currency code (e.g., 'PLN', 'EUR')       |
| `externalId`  | `string`  | Yes      | Your unique external 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<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.

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

### PaymoveApiError

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

### PaymoveNetworkError

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