Pakasir SDK

https://github.com/zeative/pakasir-sdk
Admin
SDK TypeScript ringan untuk integrasi pembayaran digital Indonesia pakasir.com, mendukung QRIS,...
Tokens:27,420
Snippets:168
Trust Score:7.3
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Basic construction example

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to create a Pakasir instance with a valid slug and API key.

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({
  slug: 'my-project-slug',
  apikey: 'pk_live_xxxxxxxx',
});
```

--------------------------------

### Create payment and access PaymentPayload

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/types.md

Shows how to create a payment and access the returned PaymentPayload. The example uses a BNI VA method and logs the payment number and total payment.

```typescript
import { Pakasir, type PaymentPayload } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

const payment: PaymentPayload = await pakasir.createPayment('bni_va', 'ORDER-12345', 100_000);
console.log(payment.payment_number, payment.total_payment); // "1234567890" 103500
```

--------------------------------

### stopWatch usage examples

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example calls to stopWatch. The first stops polling immediately for order 'ORDER-12345' with amount 100000. The second demonstrates that calling stopWatch on an unknown key is a no-op and safe.

```typescript
pakasir.stopWatch('ORDER-12345', 100_000); // stops polling immediately
// safe when nothing is being watched; stopWatch on an unknown key is a no-op
pakasir.stopWatch('ORDER-NEVER-STARTED', 10_000);
```

--------------------------------

### Create a payment with Pakasir SDK

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Minimal example to create a payment using the Pakasir SDK. Requires a project slug and API key from the Pakasir dashboard. The createPayment method is called with the payment method code 'qris', an order ID, and the amount in the smallest currency unit (e.g., 10000 for Rp10,000).

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({
  slug: 'your-slug',
  apikey: 'your-api-key',
});

const result = await pakasir.createPayment('qris', 'your-order-id', 10000);

console.log(result);
```

--------------------------------

### Error handling for initialize()

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example of error handling when calling initialize(). It catches the Error thrown when the config is invalid and logs the error message "Pakasir config is not valid!".

```typescript
try {
  pakasir.initialize();
} catch (error) {
  console.error(error); // "Pakasir config is not valid!"
}
```

--------------------------------

### Using WatchOptions with watchPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/types.md

Shows how to create a WatchOptions object and pass it to the watchPayment method. The example sets a custom interval of 5 seconds and a timeout of 5 minutes, and logs status changes and errors. The watchPayment method accepts the options as the third parameter; if omitted, it defaults to an empty object.

```typescript
import { Pakasir, type WatchOptions } from 'pakasir-sdk';

const options: WatchOptions = {
  interval: 5_000,
  timeout: 300_000,
  onStatusChange: (payment) => console.log(payment.status),
  onError: (err) => console.error(err),
};

pakasir.watchPayment('ORDER-12345', 100_000, options);
```

--------------------------------

### Polling with callbacks example

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example of polling with callbacks. It sets interval and timeout, and provides both onStatusChange and onError callbacks. The onStatusChange callback stops the watcher when the payment is completed or canceled. Errors are routed to onError and do not stop polling.

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

pakasir.watchPayment('ORDER-12345', 100_000, {
  interval: 3000,
  timeout: 600_000, // stop after 10 minutes

  onStatusChange: (payment) => {
    console.log('Status changed:', payment.status, payment);
    if (payment.status === 'completed' || payment.status === 'canceled') {
      pakasir.stopWatch('ORDER-12345', 100_000);
    }
  },

  onError: (error) => console.error('Poll failed:', error.message),
});
```

--------------------------------

### POST /api/transactioncreate/{method} request

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Example HTTP request for creating a payment transaction. The {method} path parameter is replaced with a PaymentMethod code such as 'qris'. The API key is sent in the request body as 'api_key', not in an Authorization header.

```http
POST https://app.pakasir.com/api/transactioncreate/qris
Content-Type: application/json
```

--------------------------------

### Error handling for simulationPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Error handling example for simulationPayment. It catches and logs any error thrown during the call.

```typescript
try {
  await pakasir.simulationPayment('ORDER-12345', 100_000);
} catch (error) {
  console.error((error as Error).message);
}
```

--------------------------------

### Basic call to detailPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example of calling `detailPayment` with a valid order ID and amount. The returned `detail` object contains `status` and `completed_at` fields from the server. Note that `expired_at` is always `null` and `payment_number` is always `undefined`.

```typescript
const detail = await pakasir.detailPayment('ORDER-12345', 100_000);
console.log(detail.status);        // "pending" | "canceled" | "completed" (server-provided)
console.log(detail.completed_at);  // string | null
```

--------------------------------

### watchPayment(order_id, amount, options?)

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Starts monitoring a payment by its order ID and amount. Polls at a configurable interval, invoking onStatusChange when the payment status differs from the last observed status, and onError on poll failures. Returns void and uses background timers.

```APIDOC
## watchPayment(order_id, amount, options?)

### Description
Starts monitoring a payment by order ID and amount. It polls the payment status periodically and invokes callbacks on status changes or errors. Returns void and manages background timers that can be stopped with stopWatch or auto-stop after a timeout.

### Method
Function call

### Signature
watchPayment(order_id: string, amount: number, options: WatchOptions = {}): void

### Parameters
- **order_id** (string) - Required - Order ID to monitor.
- **amount** (number) - Required - Amount of the payment (part of the internal watch key).
- **options** (WatchOptions) - Optional, default `{}` - Polling configuration and callbacks.
  - **options.interval** (number) - Optional, default `3000` - Polling interval in milliseconds.
  - **options.timeout** (number) - Optional, default `600000` - Auto-stop timeout in milliseconds (default 10 minutes).
  - **options.onStatusChange** (`(payment: PaymentPayload) => void`) - Optional - Called whenever `detailPayment` returns a status different from the last observed status. The first poll always fires it (no previous status exists).
  - **options.onError** (`(error: Error) => void`) - Optional - Called when a poll's `detailPayment` rejects. Polling continues.

### WatchOptions Interface
```typescript
export interface WatchOptions {
  interval?: number;
  timeout?: number;
  onStatusChange?: (payment: PaymentPayload) => void;
  onError?: (error: Error) => void;
}
```

### Return Type
`void` - This method starts background timers; use `stopWatch` to end them (they also self-terminate at `timeout`).

### Behavior
1. Sanitizes `order_id`; the watch key is `` `${order_id}_${amount}` ``.
2. Calls `stopWatch(order_id, amount)` first, so re-invoking replaces any existing watcher for the same key.
3. Schedules a `setTimeout(timeout)` that calls `stopWatch` (auto-stop).
4. Immediately runs one poll (so `onStatusChange` fires right away), then polls every `interval` ms via `setInterval`.
5. On each poll, `detailPayment(order_id, amount)` is awaited; errors are routed to `onError` (if provided) and do not stop polling, and rejected polls do not update `lastStatuses`.
6. `onStatusChange` fires only when `payment.status` differs from the stored last status. Because `stopWatch` deletes the stored status, a fresh watch always reports the first poll as a change.

Note the timers are `NodeJS.Timeout` handles; this is server-side polling (Node/Bun/Deno with global timers), and the public API returns no handle.

### Example
```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

pakasir.watchPayment('ORDER-12345', 100_000, {
  interval: 3000,
  timeout: 600_000, // stop after 10 minutes

  onStatusChange: (payment) => {
    console.log('Status changed:', payment.status, payment);
    if (payment.status === 'completed' || payment.status === 'canceled') {
      pakasir.stopWatch('ORDER-12345', 100_000);
    }
  },

  onError: (error) => console.error('Poll failed:', error.message),
});
```
```

--------------------------------

### Error handling for detailPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example of handling errors from `detailPayment`. If the server response has neither `json.data` nor `json.transaction`, an `Error` is thrown with the server message or `"Failed to get payment detail!"`. Network failures or missing `json.transaction` while `json.data` exists cause a built-in `TypeError`.

```typescript
try {
  await pakasir.detailPayment('NOPE', 100_000);
} catch (error) {
  // server message if any, otherwise "Failed to get payment detail!"
  console.error((error as Error).message);
}
```

--------------------------------

### initialize()

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Validates the constructor config at runtime. Throws an Error if config.slug or config.apikey is falsy.

```APIDOC
## initialize()

### Description
Validates the constructor config at runtime. Throws an Error if config.slug or config.apikey is falsy.

### Method
initialize

### Endpoint
initialize()

### Parameters
None.

### Return Type
void

### Throws
- **Error** - If config.slug or config.apikey is falsy (empty string, undefined, etc.) - message: "Pakasir config is not valid!"

### Behavior
Validates the constructor config at runtime. Note that although TypeScript's PakasirConfig type requires both fields, this runtime guard exists for JavaScript callers and defensive coding.

### Examples
Error handling:

```typescript
try {
  pakasir.initialize();
} catch (error) {
  console.error(error); // "Pakasir config is not valid!"
}
```
```

--------------------------------

### GET /api/transactiondetail

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Documentation for the GET /api/transactiondetail endpoint, including query parameters, response fields, and error handling.

```APIDOC
## GET /api/transactiondetail

### Description
Retrieves the current state of a transaction. Used by `detailPayment` to read transaction details, and indirectly by `cancelPayment`, `simulationPayment`, and each `watchPayment` poll.

### Method
GET

### Endpoint
`https://app.pakasir.com/api/transactiondetail?project={slug}&amount={amount}&order_id={order_id}&api_key={apikey}`

### Parameters
#### Query Parameters
- **project** (string) - Required - The project slug, sourced from `config.slug`.
- **amount** (number) - Required - The transaction amount (raw, not sanitized).
- **order_id** (string) - Required - The sanitized order ID.
- **api_key** (string) - Required - The API key, sourced from `config.apikey`.

### Response
#### Success Response (200)
- **data** (any) - Presence of `data` or `transaction` suppresses the error branch.
- **transaction** (object) - Presence of `data` or `transaction` suppresses the error branch.
- **transaction.payment_method** (string) - Forwarded into `getPaymentUrl` to recompute fee/URL/`total_payment`.
- **transaction.status** (string) - Mapped to `PaymentPayload.status` (unvalidated).
- **transaction.completed_at** (string) - Mapped to `PaymentPayload.completed_at`.
- **message** (string) - Thrown error message when both `data` and `transaction` are absent.

### Error Handling
- Throws `Error(json.message || "Failed to get payment detail!")` when neither `json.data` nor `json.transaction` exists.
- Secondary failure: `getPaymentUrl(json.transaction.payment_method, order_id, amount)` re-validates order-id/amount minimums and can throw (e.g., a paypal transaction reported below Rp10.000, or an order_id shorter than 5 chars after sanitization).

### Authentication
Auth via `api_key` query parameter. Status codes are not validated by the client.
```

--------------------------------

### Basic usage of getPaymentUrl

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to instantiate the Pakasir client and call getPaymentUrl with a 'qris' method. The output demonstrates the generated payment URL and computed fee and total payment.

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

const payment = pakasir.getPaymentUrl('qris', 'ORDER-12345', 100_000, 'https://example.com/success');
console.log(payment.payment_url);
// https://app.pakasir.com/pay/my-project/100000?order_id=ORDER-12345&redirect=https://example.com/success&qris_only=1
console.log(payment.fee);        // 1010 (0.007 * 100000 + 310, rounded)
console.log(payment.total_payment); // 101010
```

--------------------------------

### Using PakasirConfig with Pakasir constructor

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/types.md

Shows how to import and use `PakasirConfig` with the `Pakasir` constructor. The config is validated by `Pakasir.initialize()`, which throws if either field is falsy.

```typescript
import { Pakasir, type PakasirConfig } from 'pakasir-sdk';

const config: PakasirConfig = { slug: 'my-project', apikey: 'pk_live_xxx' };
const pakasir = new Pakasir(config);
```

--------------------------------

### GET /api/transactiondetail

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Retrieves details of a payment transaction. The API key is sent as a query parameter.

```APIDOC
## GET /api/transactiondetail

### Description
Retrieves details of a payment transaction. The API key is sent as a query parameter.

### Method
GET

### Endpoint
`https://app.pakasir.com/api/transactiondetail`

### Parameters
#### Query Parameters
- **api_key** (string) - Required - API key for authentication.
- **order_id** (string) - Required - Order identifier for the transaction.

### Request Example
```http
GET https://app.pakasir.com/api/transactiondetail?api_key=your-api-key&order_id=order-123
```

### Response
#### Success Response
- **data** (any) - Present if successful; suppresses error branch.
- **payment** (object) - Present if successful; suppresses error branch.
- **payment.payment_number** (string) - Payment number.
- **payment.expired_at** (string) - Expiration timestamp.
- **message** (string) - Error message when both `data` and `payment` are absent.

#### Response Example
```json
{
  "payment": {
    "payment_number": "PAY123",
    "expired_at": "2025-01-01T00:00:00Z"
  }
}
```

### Error Handling
Throws `Error(json.message || "Failed to get payment details!")` when neither `json.data` nor `json.payment` exists.
```

--------------------------------

### initialize() method signature

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Signature of the initialize() method. It takes no parameters and returns void. It validates the constructor config at runtime and throws an Error with message "Pakasir config is not valid!" if config.slug or config.apikey is falsy.

```typescript
initialize(): void
```

--------------------------------

### Get Payment URL

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Generates a payment URL without an API call. Useful for client-side redirects.

```APIDOC
## [GET] Get Payment URL

### Description
Generates a payment URL without an API call. Useful for client-side redirects.

### Method
GET

### Endpoint
`pakasir.getPaymentUrl(method, order_id, amount)`

### Parameters
#### Path Parameters
- **method** (`PaymentMethod`) - Required - Payment method code
- **order_id** (`string`) - Required - Unique order ID (min 5 characters)
- **amount** (`number`) - Required - Amount in Rupiah (min Rp500)

### Request Example
```typescript
const payment = pakasir.getPaymentUrl('qris', 'ORDER-12345', 100_000);
```

### Response
#### Success Response (200)
- **payment** (`PaymentPayload`) - The payment URL object

#### Response Example
```typescript
console.log(payment);
```
```

--------------------------------

### Instantiate Pakasir with required config

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/configuration.md

Constructs a Pakasir client with the required slug and apikey options. Falsy values for either throw "Pakasir config is not valid!" at construction time. No other constructor options exist.

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({
  slug: 'my-project',   // required
  apikey: 'pk_live_xxx', // required
  // no other options exist
});
```

--------------------------------

### Get Payment URL with pakasir.getPaymentUrl

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Generates a payment URL without making an API call. Useful for client-side redirects.

```typescript
const payment = pakasir.getPaymentUrl('qris', 'ORDER-12345', 100_000);

console.log(payment);
```

--------------------------------

### Constructor signature

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

The constructor takes a PakasirConfig object and immediately calls initialize(), which throws on falsy slug or apikey.

```typescript
// src/core/pakasir.ts:18-20
constructor(public config: PakasirConfig)
```

--------------------------------

### Module graph of pakasir-sdk source tree

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/index.md

Illustrates the module graph of the source tree, showing the entry point re-exports and the internal-only modules. The consts and helpers modules are not re-exported at the package entry point.

```text
src/index.ts                 ← package entry point (re-exports only)
├── export * from './core/pakasir'   → Pakasir class, WatchOptions interface
└── export * from './types'          → PakasirConfig, PaymentMethod, PaymentPayload

src/core/pakasir.ts          ← the Pakasir client class (all logic)
src/types/index.ts           ← all public type aliases
src/consts.ts                ← BASE_API_URL constant (NOT re-exported at top level)
src/utils/helpers.ts         ← sanitizeUrlSafe helper (NOT re-exported at top level)
```

--------------------------------

### Wire environment variables into Pakasir config

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/configuration.md

Shows how to wire environment variables into the Pakasir constructor, since the SDK itself does not read process.env. Use this pattern if you need env-based configuration.

```typescript
const pakasir = new Pakasir({
  slug: process.env.PAKASIR_SLUG!,
  apikey: process.env.PAKASIR_API_KEY!,
});
```

--------------------------------

### Pakasir constructor

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Constructor for the Pakasir SDK client. Requires a config object with slug and apikey.

```APIDOC
## Class `Pakasir`

### Description
Creates a new Pakasir client instance bound to a project slug and API key.

### Constructor
`constructor(config: PakasirConfig)`

### Parameters
- **config** (PakasirConfig) - Required - Project credentials: `{ slug: string; apikey: string }`

### Behavior
Immediately calls `initialize()`, which throws if `slug` or `apikey` is falsy.

### Example
```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({
  slug: 'my-project-slug',
  apikey: 'pk_live_xxxxxxxx',
});
```
```

--------------------------------

### watchPayment method signature

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Signature of the watchPayment method. It starts background polling for a payment status and returns void. The method sanitizes order_id and uses a watch key of `${order_id}_${amount}`. It calls stopWatch first, so re-invoking replaces any existing watcher for the same key.

```typescript
watchPayment(order_id: string, amount: number, options: WatchOptions = {}): void
```

--------------------------------

### Simulation Payment with pakasir.simulationPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Simulates a successful payment for testing purposes.

```typescript
const simulated = await pakasir.simulationPayment('ORDER-12345', 100_000);

console.log(simulated);
```

--------------------------------

### POST /api/transactioncreate/{method}

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Creates a payment transaction. The `{method}` path parameter is a `PaymentMethod` code (e.g., `qris`). The client sends the API key in the JSON body as `api_key`.

```APIDOC
## POST /api/transactioncreate/{method}

### Description
Creates a payment transaction. The `{method}` path parameter is a `PaymentMethod` code (e.g., `qris`). The client sends the API key in the JSON body as `api_key`.

### Method
POST

### Endpoint
`https://app.pakasir.com/api/transactioncreate/{method}`

### Parameters
#### Path Parameters
- **method** (string) - Required - Payment method code (e.g., `qris`).

#### Request Body
- **project** (string) - Required - Project slug from configuration.
- **api_key** (string) - Required - API key for authentication.
- **order_id** (string) - Required - Sanitized order identifier.
- **amount** (number) - Required - Transaction amount.
- **redirect_url** (string | null) - Optional - Redirect URL after payment, sanitized or null.

### Request Example
```http
POST https://app.pakasir.com/api/transactioncreate/qris
Content-Type: application/json

{
  "project": "your-slug",
  "api_key": "your-api-key",
  "order_id": "order-123",
  "amount": 10000,
  "redirect_url": "https://example.com/redirect"
}
```

### Response
#### Success Response
- **data** (any) - Present if successful; suppresses error branch.
- **payment** (object) - Present if successful; suppresses error branch.
- **payment.payment_number** (string) - Payment number.
- **payment.expired_at** (string) - Expiration timestamp.
- **message** (string) - Error message when both `data` and `payment` are absent.

#### Response Example
```json
{
  "payment": {
    "payment_number": "PAY123",
    "expired_at": "2025-01-01T00:00:00Z"
  }
}
```

### Error Handling
Throws `Error(json.message || "Failed to create payment!")` when neither `json.data` nor `json.payment` exists. If `json.data` exists but `json.payment` is missing, accessing `json.payment.payment_number` throws a `TypeError`.
```

--------------------------------

### POST /api/paymentsimulation

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Simulates a payment transaction. The API key is sent in the JSON body.

```APIDOC
## POST /api/paymentsimulation

### Description
Simulates a payment transaction. The API key is sent in the JSON body.

### Method
POST

### Endpoint
`https://app.pakasir.com/api/paymentsimulation`

### Parameters
#### Request Body
- **api_key** (string) - Required - API key for authentication.
- **order_id** (string) - Required - Order identifier for the simulation.
- **amount** (number) - Required - Transaction amount.

### Request Example
```http
POST https://app.pakasir.com/api/paymentsimulation
Content-Type: application/json

{
  "api_key": "your-api-key",
  "order_id": "order-123",
  "amount": 10000
}
```

### Response
#### Success Response
- **data** (any) - Present if successful; suppresses error branch.
- **payment** (object) - Present if successful; suppresses error branch.
- **payment.payment_number** (string) - Payment number.
- **payment.expired_at** (string) - Expiration timestamp.
- **message** (string) - Error message when both `data` and `payment` are absent.

#### Response Example
```json
{
  "payment": {
    "payment_number": "PAY123",
    "expired_at": "2025-01-01T00:00:00Z"
  }
}
```

### Error Handling
Throws `Error(json.message || "Failed to simulate payment!")` when neither `json.data` nor `json.payment` exists.
```

--------------------------------

### Import Pakasir from pakasir-sdk

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/index.md

Shows how to import the Pakasir class from the package root using either ES module import or CommonJS require. The SDK is dual-format (ESM/CJS) with bundled type declarations.

```typescript
import { Pakasir } from 'pakasir-sdk';
// or
const { Pakasir } = require('pakasir-sdk');
```

--------------------------------

### Basic createPayment call

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Basic usage of createPayment with a QRIS method. The response includes payment_number and expired_at from the server.

```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

const payment = await pakasir.createPayment('qris', 'ORDER-12345', 100_000, 'https://example.com/success');
console.log(payment.payment_number); // e.g. "QRIS-1234567890"
console.log(payment.expired_at);     // ISO timestamp from the server
```

--------------------------------

### POST /api/paymentsimulation

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Marks a payment as paid in a test/demo flow. Used by the `simulationPayment` method in the SDK.

```APIDOC
## POST /api/paymentsimulation

### Description
Marks a payment as paid in a test/demo flow. Used by the `simulationPayment` method in the SDK.

### Method
POST

### Endpoint
`https://app.pakasir.com/api/paymentsimulation`

### Parameters
#### Request Body
- **project** (string) - Required - The project slug from the SDK configuration.
- **api_key** (string) - Required - The API key from the SDK configuration.
- **order_id** (string) - Required - The sanitized order ID.
- **amount** (number) - Required - The payment amount.

### Request Example
```json
{
  "project": "your-project-slug",
  "api_key": "your-api-key",
  "order_id": "order-123",
  "amount": 100.00
}
```

### Response
#### Success Response
- **data** (any) - Present on success; suppresses the error branch.
- **success** (any) - Present on success; suppresses the error branch.
- **message** (string) - Error message when both `data` and `success` are absent.

#### Response Example
```json
{
  "data": {},
  "success": true
}
```

### Error Handling
Throws `Error(json.message || "Failed to simulate payment!")` when neither `data` nor `success` is present.
```

--------------------------------

### createPayment(method, order_id, amount, redirect_url?)

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Creates a payment transaction by sending a POST request to the Pakasir API. It validates inputs locally, computes the payment payload, and enriches it with server-provided payment number and expiration timestamp.

```APIDOC
## createPayment(method, order_id, amount, redirect_url?)

### Description
Creates a payment transaction by sending a POST request to the Pakasir API. It validates inputs locally, computes the payment payload, and enriches it with server-provided payment number and expiration timestamp.

### Method
POST

### Endpoint
https://app.pakasir.com/api/transactioncreate/{method}

### Parameters
#### Path Parameters
- **method** (PaymentMethod) - Required - Payment method code (e.g., 'qris', 'paypal').

#### Request Body
- **project** (string) - Required - Project slug.
- **api_key** (string) - Required - API key.
- **order_id** (string) - Required - Unique order ID (sanitized, min 5 chars after sanitization).
- **amount** (number) - Required - Amount in Rupiah (min Rp500, min Rp10.000 for paypal).
- **redirect_url** (string) - Optional - Redirect URL after payment.

### Request Example
{
  "project": "my-project",
  "api_key": "pk_live_xxx",
  "order_id": "ORDER-12345",
  "amount": 100000,
  "redirect_url": "https://example.com/success"
}

### Response
#### Success Response (200)
- **payment_number** (string) - Payment number from server (e.g., "QRIS-1234567890").
- **expired_at** (string) - ISO timestamp from server.
- **project** (string) - Project slug (computed locally).
- **amount** (number) - Amount in Rupiah (computed locally).
- **fee** (number) - Fee (computed locally).
- **total_payment** (number) - Total payment amount (computed locally).
- **payment_url** (string) - Payment URL (computed locally).
- **status** (string) - Hard-coded to 'pending'.

#### Response Example
{
  "payment_number": "QRIS-1234567890",
  "expired_at": "2025-01-01T00:00:00Z",
  "project": "my-project",
  "amount": 100000,
  "fee": 5000,
  "total_payment": 105000,
  "payment_url": "https://app.pakasir.com/pay/...",
  "status": "pending"
}

### Error Handling
- **Error** - Local validation failures (e.g., amount below minimum).
- **Error** - Server response has neither `json.data` nor `json.payment` — message from `json.message` if present, else "Failed to create payment!".
- **TypeError** - `json.data` exists but `json.payment` is missing.
- **TypeError** - Network failure (`fetch` rejects).
```

--------------------------------

### Error handling and sanitization with getPaymentUrl

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Demonstrates error handling for invalid amounts and order IDs. Shows that order_id is sanitized before validation, so 'O-1/2' becomes 'O-12' and fails the length check.

```typescript
try {
  pakasir.getPaymentUrl('qris', 'ORD/ER', 100); // amount < 500
} catch (error) {
  console.error((error as Error).message); // "Amount must be at least Rp500!"
}

// order_id is sanitized first; "O-1/2" becomes "O-12" (4 chars) and fails the length check
try {
  pakasir.getPaymentUrl('qris', 'O-1/2', 1000);
} catch (error) {
  console.error((error as Error).message); // "Order ID must be at least 5 characters long!"
}
```

--------------------------------

### simulationPayment(order_id, amount)

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Simulates a payment as completed by sending a POST request to the Pakasir API. Returns the payment detail with status set to 'completed'.

```APIDOC
## simulationPayment(order_id, amount)

### Description
Simulates a payment as completed by sending a POST request to the Pakasir API. Returns the payment detail with status set to 'completed'.

### Method
POST

### Endpoint
https://app.pakasir.com/api/paymentsimulation

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **project** (string) - Required - The project identifier.
- **api_key** (string) - Required - The API key for authentication.
- **order_id** (string) - Required - Order ID of the payment to simulate as completed.
- **amount** (number) - Required - Amount used when the payment was created.

### Request Example
{
  "project": "your-project",
  "api_key": "your-api-key",
  "order_id": "ORDER-12345",
  "amount": 100000
}

### Response
#### Success Response (200)
- **status** (string) - The status of the payment, set to 'completed'.
- Additional fields from the payment detail.

#### Response Example
{
  "status": "completed",
  "order_id": "ORDER-12345",
  "amount": 100000
}

### Error Handling
- **Error** - If the server response has neither `json.data` nor `json.success`, the error message is taken from `json.message` or defaults to "Failed to simulate payment!".
- **Error** - Any error thrown by the subsequent `detailPayment` call.
- **TypeError** - On network failure.

### Examples
Basic call:

```typescript
const simulated = await pakasir.simulationPayment('ORDER-12345', 100_000);
console.log(simulated.status); // "completed"
```

Error handling:

```typescript
try {
  await pakasir.simulationPayment('ORDER-12345', 100_000);
} catch (error) {
  console.error((error as Error).message);
}
```
```

--------------------------------

### Browser Redirect /pay/{slug}/{amount} and /paypal/{slug}/{amount}

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/endpoints.md

Generates the payment page URL handed to the customer. This is not fetched by the SDK; it is returned as `PaymentPayload.payment_url`.

```APIDOC
## Browser Redirect /pay/{slug}/{amount} and /paypal/{slug}/{amount}

### Description
Generates the payment page URL handed to the customer. This is not fetched by the SDK; it is returned as `PaymentPayload.payment_url`.

### Method
Browser Redirect (GET)

### Endpoint
`https://app.pakasir.com/pay/{slug}/{amount}` and `https://app.pakasir.com/paypal/{slug}/{amount}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - Project slug.
- **amount** (number) - Required - Payment amount.

### Response
Redirects the customer's browser to the payment page.
```

--------------------------------

### Error handling on invalid config

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Demonstrates that constructing with an empty slug throws an error with the message "Pakasir config is not valid!".

```typescript
try {
  const pakasir = new Pakasir({ slug: '', apikey: 'pk_live_xxx' });
} catch (error) {
  console.error((error as Error).message); // "Pakasir config is not valid!"
}
```

--------------------------------

### getPaymentUrl(method, order_id, amount, redirect_url?)

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Generates a payment URL and payment payload locally without a network request. It validates the order ID and amount, computes the fee, and constructs the payment URL based on the payment method.

```APIDOC
## getPaymentUrl(method, order_id, amount, redirect_url?)

### Description
Generates a payment URL and payment payload locally without a network request. It validates the order ID and amount, computes the fee, and constructs the payment URL based on the payment method.

### Method
SDK Method

### Signature
```typescript
getPaymentUrl(method: PaymentMethod, order_id: string, amount: number, redirect_url?: string): PaymentPayload
```

### Parameters
- **method** (PaymentMethod) - Required - Payment method code. Also drives the fee calculation and URL pattern.
- **order_id** (string) - Required - Unique order ID. Sanitized with `sanitizeUrlSafe` before validation/use; must be at least 5 characters *after* sanitization.
- **amount** (number) - Required - Amount in Indonesian Rupiah. Must be ≥ 500 (`≥ 10.000` for `paypal`).
- **redirect_url** (string) - Optional - Redirect URL after payment. Appended raw (un-encoded, unsanitized) to the generated payment URL query string; defaults to `null` when omitted.

### Return Type
`PaymentPayload` — a fully locally-computed payment object (no network request). The status is always `'pending'`, `payment_number` is `undefined` (unset local variable), `expired_at` is `now + 24h` in ISO-8601, and `completed_at` is `null`.

### Throws
- `Error` - Sanitized `order_id` length < 5 — `"Order ID must be at least 5 characters long!"`
- `Error` - `amount < 500` — `"Amount must be at least Rp500!"`
- `Error` - `method === 'paypal'` and `amount < 10000` — `"Amount must be at least Rp10.000!"`
- `Error` - `method` matches no case — `"Invalid payment method! Only \"all\", \"qris\", and \"paypal\" are allowed!"` (unreachable through TypeScript, since `PaymentMethod` covers all cases)

### Behavior Details
- `order_id` is first passed through `sanitizeUrlSafe` (`String(s).replace(/[^\w\-_.~0-9]/g, '')`), which strips characters that are unsafe in URLs — spaces, slashes, unicode, etc. Validation and all generated URLs use the sanitized value.
- Sanitization happens **before** the length check, so `"ab cd"` becomes `"abcd"` (4 chars) and would fail the ≥ 5 check.
- Fee table per method (computed locally, never fetched):
  - `all`: `0`
  - `qris`: `amount > 105000 ? Math.round(0.01 * amount) : Math.round(0.007 * amount + 310)`
  - `paypal`: `Math.max(Math.round(0.01 * amount), 3000)`
  - `cimb_niaga_va`, `bni_va`, `bnc_va`, `maybank_va`, `permata_va`, `atm_bersama_va`, `bri_va`: `3500`
  - `sampoerna_va`, `artha_graha_va`: `2000`
- `total_payment = amount + fee`.
- Generated payment URL patterns (host = `https://app.pakasir.com`):
  - `all`: `/pay/{slug}/{amount}?order_id={id}&redirect={redirect_url}`
  - `qris`: `/pay/{slug}/{amount}?order_id={id}&redirect={redirect_url}&qris_only=1`
  - `paypal`: `/paypal/{slug}/{amount}?order_id={id}&redirect={redirect_url}`
  - all VA methods: `/pay/{slug}/{amount}?order_id={id}&redirect={redirect_url}&payment_method={method}`

### Examples
Basic call (client-side URL generation):
```typescript
import { Pakasir } from 'pakasir-sdk';

const pakasir = new Pakasir({ slug: 'my-project', apikey: 'pk_live_xxx' });

const payment = pakasir.getPaymentUrl('qris', 'ORDER-12345', 100_000, 'https://example.com/success');
console.log(payment.payment_url);
// https://app.pakasir.com/pay/my-project/100000?order_id=ORDER-12345&redirect=https://example.com/success&qris_only=1
console.log(payment.fee);        // 1010 (0.007 * 100000 + 310, rounded)
console.log(payment.total_payment); // 101010
```

Error handling and sanitization:
```typescript
try {
  pakasir.getPaymentUrl('qris', 'ORD/ER', 100); // amount < 500
} catch (error) {
  console.error((error as Error).message); // "Amount must be at least Rp500!"
}

// order_id is sanitized first; "O-1/2" becomes "O-12" (4 chars) and fails the length check
try {
  pakasir.getPaymentUrl('qris', 'O-1/2', 1000);
} catch (error) {
  console.error((error as Error).message); // "Order ID must be at least 5 characters long!"
}
```
```

--------------------------------

### Simulation Payment

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Simulates a successful payment for testing purposes.

```APIDOC
## [POST] Simulation Payment

### Description
Simulates a successful payment for testing purposes.

### Method
POST

### Endpoint
`pakasir.simulationPayment(order_id, amount)`

### Parameters
#### Path Parameters
- **order_id** (`string`) - Required - Unique order ID (min 5 characters)
- **amount** (`number`) - Required - Amount in Rupiah (min Rp500)

### Request Example
```typescript
const simulated = await pakasir.simulationPayment('ORDER-12345', 100_000);
```

### Response
#### Success Response (200)
- **simulated** (`PaymentPayload`) - The simulated payment object

#### Response Example
```typescript
console.log(simulated);
```
```

--------------------------------

### Basic simulationPayment call

Source: https://github.com/zeative/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Basic usage of simulationPayment. It marks the payment as completed and logs the resulting status.

```typescript
const simulated = await pakasir.simulationPayment('ORDER-12345', 100_000);
console.log(simulated.status); // "completed"
```

--------------------------------

### Watch Payment with pakasir.watchPayment

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Monitors payment status changes in real-time with polling. Options include interval (default 3000 ms), timeout (default 600000 ms), onStatusChange callback, and onError callback.

```typescript
pakasir.watchPayment('ORDER-12345', 100_000, {
  interval: 3000,
  timeout: 600000,

  onStatusChange: (payment) => {
    console.log('Status:', payment);
  },

  onError: (error) => console.error(error),
});
```

--------------------------------

### Create Payment

Source: https://github.com/zeative/pakasir-sdk/blob/main/README.md

Creates a new payment transaction via API.

```APIDOC
## [POST] Create Payment

### Description
Creates a new payment transaction via API.

### Method
POST

### Endpoint
`pakasir.createPayment(method, order_id, amount, redirect_url)`

### Parameters
#### Path Parameters
- **method** (`PaymentMethod`) - Required - Payment method code
- **order_id** (`string`) - Required - Unique order ID (min 5 characters)
- **amount** (`number`) - Required - Amount in Rupiah (min Rp500)
- **redirect_url** (`string?`) - Optional - Optional redirect URL after payment

### Request Example
```typescript
const payment = await pakasir.createPayment('qris', 'ORDER-12345', 100_000, 'https://example.com/success');
```

### Response
#### Success Response (200)
- **payment** (`PaymentPayload`) - The created payment object

#### Response Example
```typescript
console.log(payment);
```
```
Tokens:
Raw