Moves amount USD from your own active USD account in Payca to the IBAN balance, at once, one for one (1 USD = 1 USDC or USDT, the IBAN's asset) and without a fee. Offered when the IBAN says usdTopUp: true; otherwise 403 capability_disabled (Payca enables it for you on request, separately from usdTransfer). The source must be a USD account of the IBAN's owner: your own USD account for a company IBAN of your integration, the cabinet user's for a cabinet company; anything else is invalid_request with a detail. Not enough on the USD account is banking_rejected; it never goes below zero.

Retries are safe with the same Idempotency-Key; the same key with a different body is idempotency_conflict.

Parameters

NameInTypeRequiredDescription
companyId path string (uuid) yes

Your company that Payca enabled for Virtual IBAN.
ibanId path string (uuid) yes

The id of one of your IBANs held in a stablecoin, from GET …/ibans.
Idempotency-Key header string yes

Your unique key for this operation, 1–128 characters.

Request body

application/json · object · required

FieldTypeRequiredDescription
amount string yes

Amount in USD, positive, at most two decimals; the same amount of the IBAN's asset is credited. A JSON number is accepted too.
fromAccountId string (uuid) yes

Your active USD account to debit.

Responses

StatusBodyDescription
200 VirtualIbanUsdTopUp

Top-up done (or the top-up this key already made).
400 VirtualIbanError

The request was refused; code says why (see errors).
401 —

Missing or invalid x-client-id / x-client-secret (no body).
403 VirtualIbanError

The request was refused; code says why (see errors).
404 VirtualIbanError

The request was refused; code says why (see errors).
409 VirtualIbanError

The request was refused; code says why (see errors).
503 VirtualIbanError

The request was refused; code says why (see errors).

Specification

This page is generated from the OpenAPI specification, which remains the authoritative machine-readable source.