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

The first release checks 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). With amount, each distinct pool/window examines up to 500 payouts on either side of the requested amount, ordered by their current free remainder. Pending and partially paid payouts both participate. If amount is outside min_amount–max_amount, the search starts at the closest boundary; recommendation deltas still use the original amount. Each side reads one extra row to detect truncation. Without amount, the read examines up to 1,000 rows in matching order, plus one extra row.

These limits apply before filtering by amount and current eligibility. Rejected rows consume the budget too: an empty response with truncated: true does not establish that the rest of the pool has no suitable amounts. 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

Both endpoints share a limit of five requests per second per shop per gateway replica. A limit response is 429 with Retry-After. Reduce polling and query when choosing a payment amount. Reads have a two-second downstream budget and share a separate concurrency cap of one active read per self-matching replica, across all shops and both endpoints. That read consumes a slot inside the existing database budget. If its cap or the shared budget is busy, the request is rejected immediately with 503, without waiting in a queue. 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: shared read capacity exhausted, dependency unavailable, incompatible rolling version, stale preset version, 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.