Payouts and rails

POST/v1/payouts

Scope payouts:write (provider key). Pays out from your settlement wallet.

Field	Type	Required	Notes
`walletId`	string	yes	your settlement wallet
`amountMicros`	string	yes	micro-dollars leaving your wallet. The payout fee comes out of it
`rail`	`"usdc_base"`	yes	`"bank_transfer"` and `"ach"` are preview rails: refused with `NOT_SUPPORTED` (501) unless the deployment has turned preview rails on, and never offered in the console
`destination`	string	no	leave it out to use your registered destination. Recommended
`treasuryProviderId`	string	no	only if two payout providers serve the same rail

The payout row's creditedAmountMicros is what was sent and feeMicros the payout fee kept (absent when none). It's idempotent per payout. On a real rail it returns status: "submitted": your wallet has been debited and the money is in transit. It becomes confirmed when the rail confirms, or returned` (re-credited with a new entry) if the payment comes back.

Refusals: VALIDATION_FAILED (below the minimum payout, or not more than the payout fee), DESTINATION_COOLING_DOWN, SANCTIONED_ADDRESS, TREASURY_UNAVAILABLE, COVERAGE_SHORTFALL, INSUFFICIENT_FUNDS, FUNDS_CLEARING (earnings still in the clearing period), LIMIT_EXCEEDED. See Earnings and payouts.

GET/v1/rail/providers

Scope rail:read. What this deployment can do. Ask before offering a funding or payout option.

JSON

{
  "sandbox": false,
  "minimums": { "cardTopUpMicros": "25000000", "internationalCardTopUpMicros": "50000000", "cardDomesticCountries": ["US"], "payoutMicros": "10000000" },
  "providers": [{
    "id": "tprov_circle", "name": "circle", "adapterType": "custodian", "status": "active",
    "roles": ["funding", "payout"], "currencies": ["USDC"], "rails": ["usdc_base"],
    "topUps": false, "depositAddresses": true, "faucet": false
  }]
}

id is stable (tprov_ + the provider's name), so it's safe to store or to pass as treasuryProviderId. roles says what a provider is allowed to do. topUps, depositAddresses and faucet say what you can ask it for. A card processor that supports browser checkout also has client: { vendor, publishableKey, testMode }, the public key a card form is set up with. sandbox is always false on the hosted platform. minimums are the amount floors this deployment enforces, in micro-dollars: the smallest card top-up, the smallest on a card issued outside cardDomesticCountries, and the smallest payout. A missing one means no minimum.

GET/v1/rail/transactions

Scope rail:read. Every deposit, payout and dispute on wallets you own. A disputed card top-up appears as direction: "reversal", with the dispute id as externalRef and reversesRailTransactionId naming the top-up; it becomes returned if the dispute is won. Each row has its state (pending, held, submitted, confirmed, returned …) and both amounts: the amount on the rail, and the amount credited in USD. A payout also carries destination: the address or external-account id it was sent to, including your saved destination when the request named none. It is fixed when the payout is made, so changing your saved destination later doesn't change it. Payouts made before this field existed don't have one.