Payment availability

Use this API before creating a payment when you can choose its amount. For example, a request near 2090.00 may recommend 2100.00 because that amount fits a current matching remainder. This API is optional: you can always call POST /v1/payment directly.

Both endpoints require X-API-Key and use only that key's shop routes. They return source-currency amounts as decimal strings. They never create an operation, expose requisites, or reserve an amount or matching slot.

Available intervals

GET /v1/payment/availability?method=WT_RUB_PHONE&currency=RUB&min_amount=2000.00&max_amount=2200.00

The four query parameters above are required. Both bounds must be positive, and min_amount must not exceed max_amount. The method must belong to the specified currency. The requested range must have configured shop pricing.

The response's intervals are sorted, disjoint ranges. Both endpoints are inclusive. An interval with equal endpoints allows only that exact amount; gaps between intervals are intentional. Do not replace them with one overall minimum and maximum.

Nearby recommendations

POST /v1/payment/recommendations with Content-Type: application/json:

{
  "method": "WT_RUB_PHONE",
  "currency": "RUB",
  "amount": "2090.00",
  "min_amount": "2090.00",
  "max_amount": "2150.00",
  "limit": 3
}

amount is the desired positive amount. The two required bounds specify what you are willing to send; no recommendation exceeds them. amount may lie outside those bounds. limit defaults to 3 and cannot exceed 10.

Example response for a pool with an exact available remainder:

{
  "method": "WT_RUB_PHONE",
  "currency": "RUB",
  "evaluated_at": "2026-09-16T12:00:00Z",
  "coverage": "full",
  "reserved": false,
  "truncated": false,
  "intervals": [{"min_amount": "2100.00", "max_amount": "2100.00"}],
  "recommendations": [{"amount": "2100.00", "delta": "10.00"}]
}

Recommendations prioritize exact free remainders, then distance from amount, then the lower amount on ties. delta is signed. There may be fewer than limit distinct suggestions. Select the amount yourself and submit it in a normal create request with your usual idempotency key. This API never changes an existing payment's amount. It does not promise which payout will be matched; the normal matching priority still applies.

Freshness and coverage

Availability checks cover self-matching only. Other providers continue to work through ordinary creation but do not contribute live availability.

An empty partial/unsupported/truncated response is not a refusal to create a payment. Even a full response is advisory: another payment can consume a slot immediately after the read, a deadline can pass, or configuration can change. Actual admission, FX and other create-time checks still run at creation. Recommendations are amount hints, not a commercial quote or a guaranteed settlement result.

Reads are not cached (Cache-Control: no-store). Results come from a bounded search: an empty response with truncated: true does not prove that no suitable amounts exist. Truncated results do not guarantee the globally nearest amount. At most 200 intervals are returned. Recommendations may refer to a valid observed amount outside those first 200 intervals when truncation occurs.

Errors and limits

Keep the combined request rate for both endpoints at or below five requests per second per shop. On 429, wait for Retry-After before retrying. Query when choosing a payment amount. Reads may return 503 during temporary overload or a dependency timeout. Retry with backoff or use ordinary payment creation.

• 400: invalid method, currency, amounts, bounds or recommendation limit.
• 401/403: authentication or authorization failure.
• 404: shop scope is not accessible.
• 412: shop unavailable for creation, no route, or missing pricing coverage.
• 429: request rate limit.
• 503: temporary read unavailability or timeout. Retry later or use normal creation; this is not an empty matching pool.

No recommendation or availability response is required by the create endpoint.