Limits and minimums

A payout has to fit between the minimum and the cap of its method. Outside that range it is rejected before any money moves.

	Value	Who sets it
Minimum per transaction	~Bs 925.00 (1 token)	The payment network
Cap per transaction, pago móvil	Bs 100,000.00 (10000000)	The receiving bank
Cap per transaction, bank transfer	Bs 500,000.00 (50000000)	The banking network
Daily cap	Bs 2,000,000.00 (200000000)	The banking network

The caps come from the Venezuelan banking ecosystem, not from a commercial decision of ours: pago móvil is more limited than bank transfer because the receiving banks set it that way. If your operation needs more, it is handled with the payment network.

The minimum is in tokens, not in bolívares

The payment network’s floor is set at 1 token. It is converted at the current rate on every transfer, so its equivalent in Bs moves every day.

~Bs 925 is today's figure, not a constant

At the measured rate of 924.5231 Bs/USDT, 1 token is ~Bs 925.00.

If your product pays out small amounts, do not leave them at the edge: a rate move pushes them to the other side and the payout is rejected with reason: "amount_below_minimum". Leave some margin or round up.

It is checked before calling the payment network, so an amount that is too small does not waste an attempt: the payout responds 201 with status: "failed", reason: "amount_below_minimum" and the entry reversed. You are not charged anything.

The pago móvil cap

Bs 100,000.00 per transaction, the lowest of the two methods. Exceeding it returns 422 limit_exceeded, with the details in meta:

422 Unprocessable Entity

{ "error": {
    "type": "invalid_request_error", "code": "limit_exceeded",
    "message": "Supera el límite por operación de pago móvil",
    "request_id": "req_8a0312ba896772bc441134cd",
    "meta": { "limit": "per_tx_max", "max": "10000000", "scope": "platform" } } }

The four limits

meta.limit	What it measures
per_tx_max	Maximum amount of one transaction
daily_max	Accumulated amount for the day
monthly_max	Accumulated amount for the month
daily_count_max	Number of transactions for the day

Limits have a method: the same amount can fit by bank transfer and not by pago móvil. There are also per-beneficiary limits.

Precedence

beneficiary  >  customer  >  tenant  >  platform

And within each level, the specific method before *. The most specific one wins outright: caps do not intersect, they replace each other. meta.scope tells you which rule rejected the payment.

Checking your usage

curl -s "$BASE/v1/limits/usage?asset=BS" -H "x-api-key: $KEY"

200 OK

{
  "asset": "BS",
  "usage": { "day_amount": "45371900", "day_count": "38",
             "month_amount": "912440000" },
  "limit": { "scope": "tenant", "method": "*",
             "per_tx_max": "10000000", "daily_max": "500000000",
             "monthly_max": null, "daily_count_max": null }
}

Field	What it is
usage.day_amount · usage.month_amount	Amount paid out today and this month, in minor units
usage.day_count	Transactions today
limit	The rule that applies to you. null if none is configured

It accepts customerId to see the usage of a specific user of yours.

Usage does not distinguish method; the check does

GET /limits/usage gives the accumulated figure for the asset, without separating pago móvil from bank transfer. The check the payout performs does filter by method. With different caps per method, use this figure as a guide, not as an exact calculation.

Payouts that ended up failed or reversed do not count towards usage.

And the payment network’s ceiling

Above all this sits the payment network’s own ceiling (reason: "amount_above_limit") and its liquidity at the time (reason: "payout_insufficient_balance"). Those are not raised per client: you have to split the payment or wait.

Where it is rejected	How you see it
In our limits	422 limit_exceeded with error.meta
On the payment network	201 with status: "failed" and reason

See errors for the difference between the two taxonomies.