### Install @gpmpay/sdk with pnpm, npm, yarn, or bun

Source: https://docs.gpmpay.com/sdk-nodejs

Install the @gpmpay/sdk package using your preferred package manager. Requires Node.js 18.17 or later (uses global fetch). No runtime dependencies, works with both ESM and CommonJS.

```bash
pnpm add @gpmpay/sdk
```

```bash
npm install @gpmpay/sdk
```

```bash
yarn add @gpmpay/sdk
```

```bash
bun add @gpmpay/sdk
```

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

### GET /transactions - List transactions (200 response)

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Example response for listing transactions with type=IN and limit=10. The response includes transaction details such as id, bankAccountId, type, source, amount, balanceAfter, referenceCode, transferContent, counterAccount, counterName, transactionTime, and createdAt. Note that amount and balanceAfter are strings (Prisma Decimal), not numbers.

```json
{
  "statusCode": 200,
  "message": "",
  "data": {
    "data": [
      {
        "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
        "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a6b1e04",
        "type": "IN",
        "source": "REAL",
        "amount": "100000",
        "balanceAfter": null,
        "referenceCode": "FT24xxxxxxx",
        "transferContent": "Thanh toan DH1024",
        "counterAccount": null,
        "counterName": null,
        "transactionTime": "2026-04-22T03:35:50.306Z",
        "createdAt": "2026-04-22T03:35:51.101Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 10,
      "totalItems": 1,
      "totalPages": 1
    }
  }
}
```

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

### GET /webhook-settings

Source: https://docs.gpmpay.com/api-reference

Retrieves the list of registered webhook endpoints.

```APIDOC
## GET /webhook-settings

### Description
Retrieves the list of registered webhook endpoints.

### Method
GET

### Endpoint
/webhook-settings

### Parameters
#### Query Parameters
- No query parameters documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### GET /webhook-settings

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Retrieves a list of webhook settings with optional pagination and filtering. Requires the `webhooks:manage` scope.

```APIDOC
## GET /webhook-settings

### Description
Đăng ký và quản lý endpoint nhận webhook. Toàn bộ folder dùng scope `webhooks:manage`.

### Method
GET

### Endpoint
{{baseUrl}}/webhook-settings

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of records to return. Default: 10.
- **page** (integer) - Optional - Page number. Disabled by default.
- **driver** (string) - Optional - Filter by driver type: HTTP, TELEGRAM, WORDPRESS, GOOGLE_SHEETS. Disabled by default.
- **sortBy** (string) - Optional - Sort field. Disabled by default.
- **sortOrder** (string) - Optional - Sort order: asc or desc. Disabled by default.

### Request Example
GET {{baseUrl}}/webhook-settings?limit=10

### Response
#### Success Response (200)
- **data** (array) - List of webhook settings.
  - **id** (string) - Webhook setting ID.
  - ... (other fields as per API)

#### Response Example
(No explicit response example provided in source)
```

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

### GET /transactions

Source: https://docs.gpmpay.com/api-reference

Retrieves the list of balance transactions for the authenticated user.

```APIDOC
## GET /transactions

### Description
Retrieves the list of balance transactions for the authenticated user.

### Method
GET

### Endpoint
/transactions

### Parameters
#### Query Parameters
- No query parameters documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### .env file setup for GPMPay environment variables

Source: https://docs.gpmpay.com/sdk-nodejs

Place these variables in your .env file. Both are server-side secrets; do not commit or prefix with NEXT_PUBLIC_ or VITE_. The webhook secret is only shown once when creating the endpoint.

```plaintext
# Bí mật phía server. KHÔNG commit, KHÔNG đặt tên NEXT_PUBLIC_ / VITE_.
GPMPAY_API_TOKEN=gpm_abcd1234_xxxxxxxxxxxxxxxxxxxxxxxx
 
# Chỉ cần khi bạn nhận webhook. Chỉ hiện đúng một lần lúc tạo endpoint.
GPMPAY_WEBHOOK_SECRET=8f2c1d9a4b7e6035c8a1f4d2e9b70653a4c8e1f2d9b5074a6c3e8f1d2b9a5074
```

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

### GET /webhook-settings/{id}

Source: https://docs.gpmpay.com/api-reference

Retrieves the details of a single webhook endpoint by its ID.

```APIDOC
## GET /webhook-settings/{id}

### Description
Retrieves the details of a single webhook endpoint by its ID.

### Method
GET

### Endpoint
/webhook-settings/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook endpoint.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### Response envelope example

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Shows the standard response envelope for all GPM Pay API responses. The envelope contains statusCode, message, and data fields.

```json
{ "statusCode": 200, "message": "", "data": ... }
```

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

### GET /banks

Source: https://docs.gpmpay.com/api-reference

Retrieves the list of NAPAS banks, including the bank identification numbers (BIN) used to generate VietQR codes.

```APIDOC
## GET /banks

### Description
Retrieves the list of NAPAS banks, including the bank identification numbers (BIN) used to generate VietQR codes.

### Method
GET

### Endpoint
/banks

### Parameters
#### Query Parameters
- No query parameters documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### Simulate transaction response (201)

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Example response for a successful simulated transaction. Returns transaction object with source SIMULATED and historyIds array. Empty historyIds means no endpoint has fireOnSimulated enabled.

```json
{
  "statusCode": 201,
  "message": "",
  "data": {
    "transaction": {
      "id": "9c2e5f18-7b34-4d61-8a05-1f7c3b9e2d46",
      "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a4b1e03",
      "type": "IN",
      "source": "SIMULATED",
      "amount": "50000",
      "balanceAfter": null,
      "referenceCode": "SIM-01KPSM49SATV1NMCYKR9V6N64E",
      "transferContent": "DH1024",
      "counterAccount": null,
      "counterName": null,
      "transactionTime": "2026-04-22T03:35:50.306Z",
      "createdAt": "2026-04-22T03:35:50.412Z"
    },
    "historyIds": [
      "b7d4a1c8-3e29-4f60-95ab-8c1d2e6f4073"
    ]
  }
}
```

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

### Paginated response envelope example

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Shows the response envelope for list endpoints, which includes a pagination layer inside the data field with page, limit, totalItems, and totalPages. The limit is capped at 50 by the server.

```json
{ "statusCode": 200, "message": "", "data": { "data": [ ... ], "meta": { "page": 1, "limit": 10, "totalItems": 42, "totalPages": 5 } } }
```

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

### GET /bank-accounts/{id}

Source: https://docs.gpmpay.com/api-reference

Retrieves a single bank account by its ID, including the associated bank relationship used to obtain the BIN.

```APIDOC
## GET /bank-accounts/{id}

### Description
Retrieves a single bank account by its ID, including the associated bank relationship used to obtain the BIN.

### Method
GET

### Endpoint
/bank-accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bank account.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### GET /bank-accounts/{bankAccountId}

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Retrieves a single bank account by its ID, including the related bank object. Requires the 'bank-accounts:read' scope. The ID must be a valid UUID; otherwise, a 400 error is returned.

```APIDOC
## GET /bank-accounts/{bankAccountId}

### Description
Retrieves a single bank account by its ID, including the related bank object. Requires the 'bank-accounts:read' scope. The ID must be a valid UUID; otherwise, a 400 error is returned.

### Method
GET

### Endpoint
{{baseUrl}}/bank-accounts/{{bankAccountId}}

### Parameters
#### Path Parameters
- **bankAccountId** (string) - Required - UUID of the bank account to retrieve.

### Request Example
GET {{baseUrl}}/bank-accounts/{{bankAccountId}}

### Response
#### Success Response (200)
- **data** (object) - Bank account details.
- **data.id** (string) - Unique identifier.
- **data.bank** (object) - Related bank object containing NAPAS bin.

#### Response Example
{
  "data": {
    "id": "string",
    "bank": {}
  }
}
```

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

### Real transaction payload

Source: https://docs.gpmpay.com/webhook

Example of a real webhook payload for an incoming transaction. Contains fields like 'id', 'gateway', 'transactionDate', 'accountNumber', 'content', 'transferType', 'transferAmount', 'referenceCode', and 'source'.

```json
{
  "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
  "gateway": "VCB",
  "transactionDate": "2026-04-22T03:35:50.306Z",
  "accountNumber": "0123456789",
  "subAccount": null,
  "content": "Thanh toan DH1024",
  "description": "Thanh toan DH1024",
  "transferType": "in",
  "transferAmount": 100000,
  "accumulated": null,
  "referenceCode": "FT24xxxxxxx",
  "source": "REAL"
}
```

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

### Verify webhook signature with gpmpayWebhook

Source: https://docs.gpmpay.com/sdk-nodejs

Verify webhook signatures with gpmpayWebhook. Must use express.raw() to get the raw body; if express.json() parses first, the signature will always fail and the SDK will throw a clear error.

```typescript
import express from "express";
import { gpmpayWebhook } from "@gpmpay/sdk/webhooks";
 
app.post(
  "/webhooks/gpmpay",
  express.raw({ type: "application/json" }), // bắt buộc: cần raw body
  gpmpayWebhook({
    secret: process.env.GPMPAY_WEBHOOK_SECRET!,
    onEvent: async (event) => {
      if (event.payload.transferType !== "in") return;
      const code = /DH\d+/.exec(event.payload.content)?.[0];
      if (code) await fulfil(code, event.payload);
    },
  }),
);
```

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

### Use gpmpay CLI for token check, webhook testing, and history

Source: https://docs.gpmpay.com/sdk-nodejs

Use the bundled gpmpay CLI to check tokens, list accounts, listen for webhooks locally, send signed test events, and inspect delivery history. The handler must reject events with --bad-signature or --skew 600.

```bash
npx gpmpay ping                # kiểm tra token + xem scope thật của nó
npx gpmpay accounts list       # lấy bankAccountId cho --account
npx gpmpay webhook listen      # receiver local, verify chữ ký trực tiếp
 
# Bắn 1 event đã ký vào handler của bạn — không cần API token:
npx gpmpay webhook send --url http://localhost:3000/webhooks/gpmpay \
  --secret $GPMPAY_WEBHOOK_SECRET
 
# Handler phải TỪ CHỐI hai lệnh này:
npx gpmpay webhook send --url ... --secret ... --bad-signature
npx gpmpay webhook send --url ... --secret ... --skew 600
 
npx gpmpay webhook history     # đã giao chưa, mã lỗi là gì, thử mấy lần
```

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

### GET /webhook-histories

Source: https://docs.gpmpay.com/api-reference

Retrieves the log of webhook deliveries.

```APIDOC
## GET /webhook-histories

### Description
Retrieves the log of webhook deliveries.

### Method
GET

### Endpoint
/webhook-histories

### Parameters
#### Query Parameters
- No query parameters documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### GpmPay.fromEnv() and constructor initialization

Source: https://docs.gpmpay.com/sdk-nodejs

Use GpmPay.fromEnv() to read environment variables; it throws GpmPayConfigError at startup if the token is missing. The constructor requires you to pass the token explicitly.

```typescript
import { GpmPay } from "@gpmpay/sdk";
 
// Thiếu token → ném GpmPayConfigError ngay lúc khởi động,
// không đợi tới request đầu tiên mới nhận 401.
const client = GpmPay.fromEnv();
 
// Chỉ mình fromEnv() đọc env. Constructor thì bạn phải tự truyền:
const explicit = new GpmPay({
  apiToken: process.env.GPMPAY_API_TOKEN!,
});
```

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

### POST /webhook-settings

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Creates a new webhook setting. Supports various drivers and authorization types. Requires the `webhooks:manage` scope.

```APIDOC
## POST /webhook-settings

### Description
Registers a webhook endpoint to receive notifications.

### Method
POST

### Endpoint
{{baseUrl}}/webhook-settings

### Parameters
#### Request Body
- **name** (string) - Optional - Name of the webhook setting (max 128 characters).
- **scope** (string) - Required - `ALL` for all accounts (including future accounts), `SPECIFIC` for only specified bank account IDs.
- **bankAccountIds** (array of UUID) - Required when `scope=SPECIFIC` - Array of bank account IDs (at least 1 element).
- **driver** (string) - Optional - `HTTP` (default), `TELEGRAM`, `WORDPRESS`, or `GOOGLE_SHEETS`.
- **url** (string) - Required for HTTP/WORDPRESS/GOOGLE_SHEETS - Endpoint URL. Leave empty for Telegram.
- **isActive** (boolean) - Optional - Whether the webhook is active.
- **fireOnSimulated** (boolean) - Optional - Default `true`. If `false`, simulator will not fire to this endpoint.
- **authorizationType** (string) - Optional - `HMAC`, `API_KEY`, or `NONE`.
- **authorizationSecret** (string) - Required depending on authorizationType - Max 512 characters. Encrypted when stored.
- **telegramChatId** (string) - Required when `driver=TELEGRAM` - Telegram chat ID.
- **wpSecret** (string) - Required when `driver=WORDPRESS` - WordPress secret (min 16 characters).
- **googleSheetName** (string) - Optional for `GOOGLE_SHEETS` - Google Sheet name.

### Request Example
```json
{
  "name": "Shop chinh",
  "scope": "ALL",
  "driver": "HTTP",
  "url": "https://shop.example.com/webhooks/gpmpay",
  "isActive": true,
  "fireOnSimulated": true,
  "authorizationType": "HMAC",
  "authorizationSecret": "8f2c1d9a4b7e6035c8a1f4d2e9b70653a4c8e1f2d9b5074a6c3e8f1d2b9a5074"
}
```

### Response
#### Success Response (200)
Returns the created webhook setting.

#### Response Example
(Not provided in source)

### Error Handling
(Not specified in source)
```

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

### GET /bank-accounts

Source: https://docs.gpmpay.com/api-reference

Retrieves the list of bank accounts belonging to the authenticated user.

```APIDOC
## GET /bank-accounts

### Description
Retrieves the list of bank accounts belonging to the authenticated user.

### Method
GET

### Endpoint
/bank-accounts

### Parameters
#### Query Parameters
- No query parameters documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### Initialize GpmPay client and list transactions

Source: https://docs.gpmpay.com/sdk-nodejs

Initialize the GpmPay client with an API token (must be kept secret server-side) and list incoming transactions to find a payment by your own reconciliation code. The code is generated by you and must appear in the transfer content.

```typescript
import { GpmPay } from "@gpmpay/sdk";
 
const client = new GpmPay({ apiToken: process.env.GPMPAY_API_TOKEN! });
 
// Mã đối soát do BẠN sinh — đưa vào nội dung chuyển khoản khi dựng QR.
const code = "DH1024";
 
const { data } = await client.transactions.list({ type: "IN", limit: 10 });
const paid = data.find((tx) => tx.transferContent.includes(code));
```

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

### GET /webhook-histories/{id}

Source: https://docs.gpmpay.com/api-reference

Retrieves the details of a single webhook delivery, including the payload and response.

```APIDOC
## GET /webhook-histories/{id}

### Description
Retrieves the details of a single webhook delivery, including the payload and response.

### Method
GET

### Endpoint
/webhook-histories/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook delivery.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### Shell export and ping verification for GPMPay

Source: https://docs.gpmpay.com/sdk-nodejs

Export the environment variables in your shell and verify the token with `npx gpmpay ping` before deploying.

```bash
export GPMPAY_API_TOKEN=gpm_abcd1234_xxxxxxxxxxxxxxxxxxxxxxxx
export GPMPAY_WEBHOOK_SECRET=8f2c1d9a4b7e6035c8a1f4d2e9b70653a4c8e1f2d9b5074a6c3e8f1d2b9a5074
 
# Xác nhận token sống và xem scope thật của nó trước khi deploy:
npx gpmpay ping
```

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

### GET /transactions/{id}

Source: https://docs.gpmpay.com/api-reference

Retrieves a single transaction by its ID, including the history of webhook deliveries associated with it.

```APIDOC
## GET /transactions/{id}

### Description
Retrieves a single transaction by its ID, including the history of webhook deliveries associated with it.

### Method
GET

### Endpoint
/transactions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the transaction.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### POST /webhook-settings

Source: https://docs.gpmpay.com/api-reference

Registers a new webhook endpoint. The HTTP driver is pinged before saving to verify connectivity.

```APIDOC
## POST /webhook-settings

### Description
Registers a new webhook endpoint. The HTTP driver is pinged before saving to verify connectivity.

### Method
POST

### Endpoint
/webhook-settings

### Parameters
#### Request Body
- No request body schema documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### GET /transactions

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Lists transactions with optional filters. Requires the 'transactions:read' scope. Use this to reconcile by searching for your order code in 'transferContent'.

```APIDOC
## GET /transactions

### Description
Lists transactions with optional filters. Requires the 'transactions:read' scope. Use this to reconcile by searching for your order code in 'transferContent'.

### Method
GET

### Endpoint
{{baseUrl}}/transactions

### Parameters
#### Query Parameters
- **type** (string) - Optional - IN = tiền vào, OUT = tiền ra.
- **limit** (integer) - Optional - Tối đa 50.
- **page** (integer) - Optional - Page number.
- **bankAccountId** (string) - Optional - Phải là UUID hợp lệ.
- **source** (string) - Optional - REAL | SIMULATED. Bỏ trống = cả hai.
- **search** (string) - Optional - Tìm trong nội dung chuyển khoản.
- **startDate** (string) - Optional - Với transactions, lọc theo transactionTime (không phải createdAt). ISO 8601.
- **endDate** (string) - Optional - End date filter.
- **sortBy** (string) - Optional - Sort field.
- **sortOrder** (string) - Optional - asc | desc.

### Response
#### Success Response (200)
- **statusCode** (integer) - HTTP status code.
- **message** (string) - Response message.
- **data** (object) - Contains data array and meta.
  - **data** (array) - List of transactions.
    - **id** (string) - Transaction ID.
    - **bankAccountId** (string) - Bank account ID.
    - **type** (string) - Transaction type (IN/OUT).
    - **source** (string) - Source (REAL/SIMULATED).
    - **amount** (string) - Transaction amount as string.
    - **balanceAfter** (string|null) - Balance after transaction.
    - **referenceCode** (string) - Reference code.
    - **transferContent** (string) - Transfer content.
    - **counterAccount** (string|null) - Counter account.
    - **counterName** (string|null) - Counter name.
    - **transactionTime** (string) - Transaction time.
    - **createdAt** (string) - Creation time.
  - **meta** (object) - Pagination metadata.
    - **page** (integer) - Current page.
    - **limit** (integer) - Items per page.
    - **totalItems** (integer) - Total items.
    - **totalPages** (integer) - Total pages.

#### Response Example
{
  "statusCode": 200,
  "message": "",
  "data": {
    "data": [
      {
        "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
        "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a4b1e03",
        "type": "IN",
        "source": "REAL",
        "amount": "100000",
        "balanceAfter": null,
        "referenceCode": "FT24xxxxxxx",
        "transferContent": "Thanh toan DH1024",
        "counterAccount": null,
        "counterName": null,
        "transactionTime": "2026-04-22T03:35:50.306Z",
        "createdAt": "2026-04-22T03:35:51.101Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 10,
      "totalItems": 1,
      "totalPages": 1
    }
  }
}
```

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

### Docker Compose environment configuration for GPMPay

Source: https://docs.gpmpay.com/sdk-nodejs

Configure the environment variables in a Docker Compose service, reading from the .env file next to the compose file. The `:?bat buoc` syntax makes the service fail if the variables are not set.

```yaml
services:
  shop:
    image: my-shop:latest
    environment:
      # Đọc từ .env cạnh compose file — đừng viết thẳng giá trị vào đây.
      GPMPAY_API_TOKEN: ${GPMPAY_API_TOKEN:?bat buoc}
      GPMPAY_WEBHOOK_SECRET: ${GPMPAY_WEBHOOK_SECRET:?bat buoc}
```

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

### GET /transactions

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Lists transactions recorded on your accounts. The response includes transaction details, and the first transaction ID is stored in the 'transactionId' variable for subsequent requests.

```APIDOC
## GET /transactions

### Description
Lists transactions recorded on your accounts. The response includes transaction details, and the first transaction ID is stored in the 'transactionId' variable for subsequent requests.

### Method
GET

### Endpoint
{{baseUrl}}/transactions

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by transaction type (e.g., IN).
- **limit** (integer) - Optional - Maximum number of records to return.
- **page** (integer) - Optional - Page number for pagination.
- **status** (string) - Optional - Filter by status.
- **bankAccountId** (string) - Optional - Filter by bank account ID.
- **sortBy** (string) - Optional - Field to sort by.
- **sortOrder** (string) - Optional - Sort order: asc or desc.
- **search** (string) - Optional - Search query.
- **startDate** (string) - Optional - Filter by createdAt, ISO 8601 format.
- **endDate** (string) - Optional - Filter by createdAt, ISO 8601 format.

### Request Example
GET {{baseUrl}}/transactions?type=IN&limit=10

### Response
#### Success Response (200)
- **data** (array) - List of transactions.
- **data[].id** (string) - Unique identifier of the transaction.

#### Response Example
{
  "data": {
    "data": [
      {
        "id": "string"
      }
    ]
  }
}
```

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

### POST /simulator/transactions

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Simulates a transaction to test the end-to-end flow without real money. Requires the 'simulator' scope.

```APIDOC
## POST /simulator/transactions

### Description
Simulates a transaction to test the end-to-end flow without real money. Requires the 'simulator' scope.

### Method
POST

### Endpoint
{{baseUrl}}/simulator/transactions

### Parameters
#### Request Body
- **bankAccountId** (string) - Required - The bank account ID for the simulated transaction.
- **amount** (number) - Required - The transaction amount.
- **type** (string) - Required - Transaction type: IN or OUT.
- **transferContent** (string) - Optional - Transfer content.

### Request Example
{
  "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a4b1e03",
  "amount": 100000,
  "type": "IN",
  "transferContent": "Simulated payment"
}

### Response
#### Success Response (201)
- **id** (string) - The ID of the simulated transaction.
- **bankAccountId** (string) - The bank account ID.
- **type** (string) - Transaction type.
- **amount** (string) - Transaction amount as string.
- **transferContent** (string) - Transfer content.
- **transactionTime** (string) - Transaction time.

#### Response Example
{
  "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
  "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a4b1e03",
  "type": "IN",
  "amount": "100000",
  "transferContent": "Simulated payment",
  "transactionTime": "2026-04-22T03:35:50.306Z"
}
```

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

### GET /transactions/{{transactionId}} - Retrieve transaction

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Retrieves a single transaction by its ID. The response includes webhookHistories to check if the webhook for this transaction was delivered successfully. Requires scope transactions:read.

```json
{
  "statusCode": 200,
  "message": "",
  "data": {
    "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
    "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a6b1e04",
    "type": "IN",
    "source": "REAL",
    "amount": "100000",
    "balanceAfter": null,
    "referenceCode": "FT24xxxxxxx",
    "transferContent": "Thanh toan DH1024",
    "counterAccount": null,
    "counterName": null,
    "transactionTime": "2026-04-22T03:35:50.306Z",
    "createdAt": "2026-04-22T03:35:51.101Z"
  }
}
```

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

### POST /simulator/transactions

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Creates a simulated transaction with source SIMULATED and triggers webhooks to all endpoints with fireOnSimulated enabled. Returns { transaction, historyIds } instead of a plain Transaction.

```APIDOC
## POST /simulator/transactions

### Description
Tạo một giao dịch mang `source: SIMULATED` và bắn webhook y như giao dịch thật, tới mọi endpoint đang bật `fireOnSimulated`.

### Method
POST

### Endpoint
{{baseUrl}}/simulator/transactions

### Parameters
#### Request Body
- **bankAccountId** (string, UUID) - Required - UUID of the bank account.
- **amount** (integer) - Required - Amount in VND, must be >= 1. Integer only.
- **transferContent** (string) - Required - Transfer content, max 100 characters. Use for reconciliation code.
- **type** (string) - Optional - `IN` (default) or `OUT`.
- **referenceCode** (string) - Optional - Max 64 characters.
- **counterAccount** (string) - Optional - Max 64 characters.
- **counterName** (string) - Optional - Max 255 characters.
- **transactionTime** (string, ISO 8601) - Optional - Transaction time.

### Request Example
{
  "bankAccountId": "{{bankAccountId}}",
  "amount": 50000,
  "transferContent": "DH1024",
  "type": "IN"
}

### Response
#### Success Response (201)
- **statusCode** (integer) - HTTP status code.
- **message** (string) - Response message.
- **data** (object) - Contains transaction and historyIds.
  - **transaction** (object) - The simulated transaction.
    - **id** (string) - Transaction ID.
    - **bankAccountId** (string) - Bank account ID.
    - **type** (string) - Transaction type.
    - **source** (string) - Always "SIMULATED".
    - **amount** (string) - Transaction amount.
    - **balanceAfter** (null) - Balance after transaction.
    - **referenceCode** (string) - Reference code.
    - **transferContent** (string) - Transfer content.
    - **counterAccount** (null) - Counter account.
    - **counterName** (null) - Counter name.
    - **transactionTime** (string) - Transaction time.
    - **createdAt** (string) - Creation timestamp.
  - **historyIds** (array) - List of webhook history IDs.

#### Response Example
{
  "statusCode": 201,
  "message": "",
  "data": {
    "transaction": {
      "id": "9c2e5f18-7b34-4d61-8a05-1f7c3b9e2d46",
      "bankAccountId": "3d1f0c9e-5b47-4a12-9f8e-2c6d7a4b1e03",
      "type": "IN",
      "source": "SIMULATED",
      "amount": "50000",
      "balanceAfter": null,
      "referenceCode": "SIM-01KPSM49SATV1NMCYKR9V6N64E",
      "transferContent": "DH1024",
      "counterAccount": null,
      "counterName": null,
      "transactionTime": "2026-04-22T03:35:50.306Z",
      "createdAt": "2026-04-22T03:35:50.412Z"
    },
    "historyIds": [
      "b7d4a1c8-3e29-4f60-95ab-8c1d2e6f4073"
    ]
  }
}
```

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

### List webhook settings request URL

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Request URL for listing webhook settings. Uses {{baseUrl}} and includes query parameters: limit (10), page (disabled), driver (disabled), sortBy (disabled), sortOrder (disabled).

```http
{{baseUrl}}/webhook-settings?limit=10
```

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

### GET /bank-accounts

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Lists bank accounts that receive money. Requires the 'bank-accounts:read' scope. The response includes bank account details, and the first account ID is stored in the 'bankAccountId' variable for subsequent requests.

```APIDOC
## GET /bank-accounts

### Description
Lists bank accounts that receive money. Requires the 'bank-accounts:read' scope. The response includes bank account details, and the first account ID is stored in the 'bankAccountId' variable for subsequent requests.

### Method
GET

### Endpoint
{{baseUrl}}/bank-accounts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of records to return. Max 50; larger values are capped to 50.
- **page** (integer) - Optional - Page number for pagination.
- **status** (string) - Optional - Filter by status: PENDING_VERIFICATION, ACTIVE, SUSPENDED, DELETED.
- **bankId** (string) - Optional - UUID of the bank, obtained from List banks.
- **sortBy** (string) - Optional - Field to sort by (e.g., createdAt).
- **sortOrder** (string) - Optional - Sort order: asc or desc.
- **search** (string) - Optional - Search query.
- **startDate** (string) - Optional - Filter by createdAt, ISO 8601 format.
- **endDate** (string) - Optional - Filter by createdAt, ISO 8601 format.

### Request Example
GET {{baseUrl}}/bank-accounts?limit=10

### Response
#### Success Response (200)
- **data** (array) - List of bank accounts.
- **data[].id** (string) - Unique identifier of the bank account.
- **data[].bank** (object) - Related bank object containing NAPAS bin for VietQR.

#### Response Example
{
  "data": {
    "data": [
      {
        "id": "string"
      }
    ]
  }
}
```

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

### POST /simulator/transactions - Simulate transaction

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

Simulates a transaction to test the end-to-end flow without real money. The request requires Accept and Content-Type headers set to application/json.

```http
POST {{baseUrl}}/simulator/transactions HTTP/1.1
Accept: application/json
Content-Type: application/json
```

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

### Link tạo QR từ Dashboard

Source: https://docs.gpmpay.com/ma-qr

Link mẫu từ Dashboard để tạo mã QR VietQR, với các placeholder cần thay thế. Thay <AMOUNT> bằng số tiền (VND, số nguyên) hoặc bỏ tham số để người trả tự nhập. Thay <CONTENT> bằng nội dung chuyển khoản chứa mã đối soát (tối đa 50 ký tự). Có thể đổi compact2 thành compact, qr_only hoặc print để thay đổi kiểu ảnh.

```text
https://img.vietqr.io/image/<BIN>-<SO_TAI_KHOAN>-compact2.png?accountName=<TEN_CHU_TK>&amount=<AMOUNT>&addInfo=<CONTENT>
```

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

### POST /webhook-settings/http/test-connection

Source: https://docs.gpmpay.com/api-reference

Pings the HTTP endpoint to test connectivity before saving the webhook configuration.

```APIDOC
## POST /webhook-settings/http/test-connection

### Description
Pings the HTTP endpoint to test connectivity before saving the webhook configuration.

### Method
POST

### Endpoint
/webhook-settings/http/test-connection

### Parameters
#### Request Body
- No request body schema documented.

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example provided.
```

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

### POST /webhook

Source: https://docs.gpmpay.com/webhook

Endpoint that receives webhook notifications from GPM Pay for real and simulated transactions. Must respond with a 2xx status within 5 seconds for verification.

```APIDOC
## [POST] /webhook

### Description
Receives webhook notifications from GPM Pay for real and simulated transactions. Must respond with a 2xx status within 5 seconds for verification.

### Method
POST

### Endpoint
/webhook

### Request Body
- **id** (string) - Required - Unique identifier of the transaction.
- **gateway** (string) - Required - Payment gateway (e.g., "VCB", "GPMPAY").
- **transactionDate** (string) - Required - ISO 8601 timestamp of the transaction.
- **accountNumber** (string) - Required - Account number involved.
- **subAccount** (string|null) - Optional - Sub-account if any.
- **content** (string) - Required - Transaction content.
- **description** (string) - Optional - Description (present in real transactions).
- **transferType** (string) - Required - Type of transfer: "in" or "out".
- **transferAmount** (number) - Required - Amount transferred.
- **accumulated** (number|null) - Optional - Accumulated amount if any.
- **referenceCode** (string) - Required - Reference code for the transaction.
- **source** (string) - Required - Source of transaction: "REAL" or "SIMULATED".
- **test** (boolean) - Optional - Flag indicating verification test (only in verification payloads).

### Request Example
{
  "id": "f68120ba-c60a-433a-a7af-3746a4eec807",
  "gateway": "VCB",
  "transactionDate": "2026-04-22T03:35:50.306Z",
  "accountNumber": "0123456789",
  "subAccount": null,
  "content": "Thanh toan DH1024",
  "description": "Thanh toan DH1024",
  "transferType": "in",
  "transferAmount": 100000,
  "accumulated": null,
  "referenceCode": "FT24xxxxxxx",
  "source": "REAL"
}

### Response
#### Success Response (200)
- **status** (number) - HTTP status code (2xx) indicating successful receipt.

#### Response Example
200 OK

### Error Handling
- If the endpoint does not return a 2xx status within 5 seconds during verification, the webhook setting is not saved and the API returns error 400.
- For verification payloads (test: true), the handler should return 200 and stop processing to avoid creating a fake transaction.
```

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

### Simulate transaction request body

Source: https://docs.gpmpay.com/downloads/gpmpay-postman-collection.json

JSON body for creating a simulated transaction. Requires bankAccountId, amount (integer VND >= 1), and transferContent (<= 100 chars). Optional fields: type (IN/OUT), referenceCode, counterAccount, counterName, transactionTime.

```json
{
  "bankAccountId": "{{bankAccountId}}",
  "amount": 50000,
  "transferContent": "DH1024",
  "type": "IN"
}
```