npm package: @mongolian-payment/socialpay
Description: SocialPay payment SDK for Node.js - Invoice by phone/QR, check/cancel transactions, settlement
Latest version: 1.0.0

# @mongolian-payment/socialpay

SocialPay payment SDK for Node.js. Supports invoice creation (phone/QR), transaction check/cancel, and settlement -- all with automatic HMAC-SHA256 checksum generation.

## Installation

```bash
npm install @mongolian-payment/socialpay
```

## Quick Start

```typescript
import { SocialPayClient } from "@mongolian-payment/socialpay";

const client = new SocialPayClient({
  terminal: "YOUR_TERMINAL_ID",
  secret: "YOUR_HMAC_SECRET",
  endpoint: "https://ecommerce.golomtbank.com/api",
});

// Create an invoice via phone push notification
const result = await client.invoicePhone(1000, "INV-001", "99001122");
console.log(result.description, result.status);

// Create an invoice with QR code
const qr = await client.invoiceQr(2500, "INV-002");

// Check a transaction
const tx = await client.checkTransaction(2500, "INV-002");
console.log(tx.approvalCode, tx.responseCode);

// Cancel an invoice
await client.cancelInvoice(2500, "INV-002");

// Cancel a transaction
await client.cancelTransaction(2500, "INV-002");

// Settlement
const settlement = await client.transactionSettlement("SETTLE-001");
console.log(settlement.amount, settlement.count);
```

## Configuration from Environment Variables

```typescript
import { SocialPayClient, loadConfigFromEnv } from "@mongolian-payment/socialpay";

// Reads SOCIALPAY_TERMINAL, SOCIALPAY_SECRET, SOCIALPAY_ENDPOINT
const client = new SocialPayClient(loadConfigFromEnv());
```

## Error Handling

```typescript
import { SocialPayClient, SocialPayError } from "@mongolian-payment/socialpay";

try {
  await client.invoiceQr(1000, "INV-001");
} catch (err) {
  if (err instanceof SocialPayError) {
    console.error(err.message);      // Human-readable message
    console.error(err.statusCode);   // HTTP or API status code
    console.error(err.response);     // Raw API response (if available)
  }
}
```

## API Reference

### `new SocialPayClient(config)`

| Parameter          | Type     | Description                       |
| ------------------ | -------- | --------------------------------- |
| `config.terminal`  | `string` | Terminal ID assigned by SocialPay |
| `config.secret`    | `string` | HMAC-SHA256 secret key            |
| `config.endpoint`  | `string` | Base URL of the SocialPay API     |

### Methods

| Method                                                      | Returns                          | Description                     |
| ----------------------------------------------------------- | -------------------------------- | ------------------------------- |
| `invoicePhone(amount, invoice, phone)`                      | `SocialPaySimpleResponse`        | Invoice via phone notification  |
| `invoiceQr(amount, invoice)`                                | `SocialPaySimpleResponse`        | Invoice with QR code            |
| `checkTransaction(amount, invoice)`                         | `SocialPayTransactionResponse`   | Check transaction status        |
| `cancelInvoice(amount, invoice)`                            | `SocialPaySimpleResponse`        | Cancel a pending invoice        |
| `cancelTransaction(amount, invoice)`                        | `SocialPayTransactionResponse`   | Cancel/reverse a transaction    |
| `transactionSettlement(settlementId)`                       | `SocialPaySettlementResponse`    | Perform settlement              |

All methods automatically generate the required HMAC-SHA256 checksum.

## License

MIT