API Overview

Welcome to the One2Pays API documentation. Our REST API allows you to accept payments, process withdraws, and integrate payment processing into your applications.

Base URL

All API requests should be made to:

<ApiUrl />

For testing, use our sandbox environment:

<SandboxApiUrl />

Authentication

One2Pays uses HMAC-based Integration Authentication for all API requests. Each integration has an API key and secret key that are used to generate HMAC signatures.

See the Authentication guide for detailed information on how to authenticate your requests.

Request Format

All requests should be made over HTTPS. The API accepts JSON-encoded request bodies and returns JSON-encoded responses.

Content Type

All requests with a body must include the following header:

Content-Type: application/json

Required Headers

All requests must include these headers for HMAC authentication:

• X-API-Key - Your integration API key
• X-Timestamp - Unix timestamp in milliseconds
• X-Signature - HMAC-SHA256 signature (format: sha256=<hex_signature>)

Response Format

All responses are returned in JSON format with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "1000.00",
    "currency": "THB",
    "status": "processing",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be a valid decimal number",
    "metadata": {
      "field": "amount"
    }
  }
}

Paginated Response

List endpoints return paginated results:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "amount": "1000.00",
        "status": "succeeded"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}

Rate Limiting

The One2Pays API has rate limits to ensure fair usage:

• Production: 1000 requests per minute per integration
• Sandbox: 100 requests per minute per integration

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later",
    "metadata": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2024-01-01T00:01:00.000Z",
      "retryAfter": 60
    }
  }
}

Idempotency

To prevent duplicate requests, you can include an idempotencyKey field in your request body. If you retry a request with the same idempotency key, you'll receive the same response as the original request.

{
  "amount": "1000.00",
  "referenceId": "order-12345",
  "idempotencyKey": "unique-key-123"
}

Pagination

List endpoints return paginated results. Use the page and limit parameters to control pagination:

# Get first page (10 items)
GET /api/v1/payments?page=1&limit=10

# Get second page (next 10 items)
GET /api/v1/payments?page=2&limit=10

Pagination Parameters

• page - Page number (default: 1, minimum: 1)
• limit - Items per page (default: 10, minimum: 1, maximum: 100)

Pagination Response

{
  "success": true,
  "data": {
    "data": [...],
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}

Timestamps

All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SS.sssZ

Examples:

• 2024-01-01T00:00:00.000Z
• 2024-01-01T12:30:45.123Z

Amount Format

All amounts are specified as decimal strings, not integers:

• ✅ Correct: "1000.00" (represents 10.00 THB)
• ❌ Incorrect: 1000 (integer)

Amounts are in the smallest currency unit (satang for THB, where 100 satang = 1 THB).

Currency

Currently, One2Pays only supports Thai Baht (THB). All amounts are specified in satang (1/100 of a baht).

• "1000.00" = 10.00 THB = 1000 satang
• "100.00" = 1.00 THB = 100 satang

Available Endpoints

Payments

• POST /api/v1/payments - Create payment
• GET /api/v1/payments - List payments
• GET /api/v1/payments/:id - Retrieve payment
• POST /api/v1/payments/:id/cancel - Cancel payment

Withdraws

• POST /api/v1/withdraws - Create withdraw
• GET /api/v1/withdraws - List withdraws
• GET /api/v1/withdraws/:id - Retrieve withdraw
• POST /api/v1/withdraws/:id/cancel - Cancel withdraw

Balance

• GET /api/v1/balance - Get combined wallet and settlement balance

Authentication

• POST /api/v1/auth/login - Login (for dashboard access, not API authentication)

Next Steps

• Authentication - Learn how to authenticate your requests with HMAC
• Create Payment - Start accepting payments
• Create Withdraw - Send payouts to customers
• Webhooks - Handle real-time events
• Error Handling - Understand error responses