API overview

Base URLs

Base URL
https://api.finomesh.com/api/v1

All requests and responses are JSON (Content-Type: application/json). Merchant endpoints require the X-Api-Key header.

Endpoints at a glance

Method & path	Auth	Purpose
POST /payments	API key	Create a payment
POST /payments/{id}/verify	API key	Verify a payment's outcome
POST /payments/{id}/inquiry	API key	Submit a transaction inquiry
GET /merchant/settlements/balances	API key + signature	Cashout: available balance per asset
POST /merchant/settlements	API key + signature	Cashout: request a settlement
GET /merchant/settlements/{id}	API key + signature	Cashout: settlement status

The core API-key surface is deliberately small: your server creates payments and verifies their outcomes — the verify response carries everything you need about a payment. Transaction inquiry is a support escalation on top of that pair, for the rare payment a customer paid but that never resolved. Browsing and searching payments happens in the merchant dashboard, not over the API. For driving a test payment through its outcomes, see Sandbox Overview.

The cashout endpoints let your server withdraw your available balance programmatically. They are off by default — Finomesh enables the cashout API for your gateway on request — and additionally hardened: every request carries an HMAC signature and must come from an allowlisted IP. See the Cashout / Settlements guide.

Response envelope

Every response uses one of two envelopes.

Success — HTTP 2xx:

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

Field	Type	Nullable	Description	Example
success	boolean	No	Always true on a 2xx response.	true
data	object	No	The endpoint's result payload. Its shape depends on the endpoint — see the field table on each reference page.	{ … }

Error — HTTP 4xx/5xx:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Key: 'CreatePaymentRequest.CallbackURL' Error:Field validation for 'CallbackURL' failed on the 'required' tag"
  }
}

Field	Type	Nullable	Description	Example
success	boolean	No	Always false on an error response.	false
error	object	No	Error detail. Present only on failures.	{ … }
error.code	string (enum)	No	Stable machine-readable slug from the error-code table — branch on this.	validation_error
error.message	string	No	Human-readable description. May change between releases — never branch on it.	"…"

error.code is a stable machine-readable slug — branch on it, not on message (which is human-readable and may change).

Error codes

The common codes shared across endpoints — with a How to fix for each — are on the Error Codes page. Endpoint-specific errors are listed on each reference page; cashout has its own Cashout Errors.

Rate limiting

Every endpoint is rate limited per source IP, per endpoint; exceeding the limit returns 429 with a Retry-After header. See Rate Limits for how to handle it.

Conventions

• Money is always a string. Every monetary field ("amount": "49.99") is a decimal string with up to 18 decimal places. Parse with a decimal library — never a float.
• Timestamps are RFC 3339 / ISO-8601 UTC strings ("2026-06-12T10:21:43Z").
• IDs are UUIDs.