Overview

The Merchant API V1 is the recommended API for new integrations. It provides full access to payment collection, wallet disbursement, beneficiary management, and settlement reporting.

Base URL

https://api.flypay.asia

For FlyPay (whitelabel aggregator):

https://api.flypay.asia

All endpoints are prefixed with /v1/. All requests and responses use Content-Type: application/json.

Amount Units

All monetary values in the V1 API use normal Rupiah units:

• IDR 1 = 1
• IDR 50,000 = 50000
• IDR 1,000,000 = 1000000

Request amount fields are whole-Rupiah integers such as amount. Responses are Rupiah JSON numbers and may contain up to two decimal places when a calculated fee has sub-Rupiah precision. Minor units are internal and are never exposed by the merchant API.

Response Format

Success

{
  "success": true,
  "data": { ... }
}

Paginated Success

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "total_pages": 5
  }
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Pagination

List endpoints accept:

Parameter	Default	Maximum	Description
page	1	—	Page number (1-based)
limit	10	50	Items per page

Idempotency

To prevent duplicate processing on network retries:

• Orders: Send a stable Idempotency-Key request header and retry with the exact same body. The same key replays its original response; a different key with the same confirmed merchant order ID returns the existing order (HTTP 200). An unresolved order returns ORDER_PENDING_CONFIRMATION and must be reconciled through the order list.
• Disbursements: Include an idempotency_key field in the request body. Duplicate submissions with the same key return the existing disbursement.

POST /v1/orders
Idempotency-Key: order-2026-06-01-00123

Rate Limits

Rate limiting is enforced per API key. Contact your account manager for your specific limits. When exceeded, the API returns HTTP 429 Too Many Requests.

HTTP Status Codes

Code	Meaning
200	Success (GET, update operations)
201	Created (POST operations that create a resource)
400	Bad request — validation error or invalid input
401	Unauthorized — missing or invalid API key
403	Forbidden — valid key but insufficient permissions
404	Resource not found
409	Conflict — duplicate resource
422	Unprocessable entity — business rule violation
429	Rate limit exceeded
503	Service unavailable — vendor gateway issue