Preview payout requirements
Evaluates a candidate POST /v2/payouts body for this customer and returns the same response shape as GET /v2/payouts/requirements, with one documented difference: rail can be absent here. Unlike the GET, documentation.required is the answer this customer gets for this candidate, which can differ in either direction from the purpose baseline the GET reports. fields, whitelist and blockedJurisdictions are derived from the candidate body the same way the GET derives them from its query. Creates nothing and records no policy decision. An idempotency-key header is rejected with 400 VALIDATION_ERROR: every call re-evaluates the candidate against current policy and rate data, so a cached reply could hand you a requirement that no longer holds. A candidate whose destination is type: virtual_account or type: wallet is a book transfer between your own accounts. It is answered, not refused: documentation carries the real verdict for it, rail is absent because no payment rail names a book transfer, and fields is empty. documentation.due says when a required document is asked for, and due: post_acceptance means an rfi.published webhook asks for it after the payout is accepted. Where the candidate cannot be paid out as submitted for a reason that is not documentation (a blocked jurisdiction, an unwhitelisted recipient, a destination or prefunding rejection), documentation.evaluated reads false alongside documentation.required, so such a candidate is distinguishable from a clean accept, which reads evaluated: true with the same required: false. This response does not carry that reason: submit the same body to POST /v2/payouts to see it. documentation.amountValuation reads amountValuation: valued where the payout amount was valued in USD for this answer, amountValuation: rate_unavailable where no exchange rate could value it, and amountValuation: not_attempted where this answer did not need that value. documentation.degraded reads true where a data source this answer needed was unavailable, so required is cautious rather than exact. The two are independent: an answer that does not rest on the amount stays exact, so it reads degraded: false even where amountValuation reads amountValuation: rate_unavailable, and an answer that rests on another unavailable source reads degraded: true even where amountValuation reads amountValuation: valued. The GET always reads evaluated: true, amountValuation: not_attempted and degraded: false, because it answers the purpose baseline unconditionally and takes no amount. A customerId that names no customer in the calling organization is rejected with 404 CUSTOMER_NOT_FOUND, the same as POST /v2/payouts.
Authorizations
Body
- Option 1
- Option 2
^cus_[0-9A-Za-z]{22}$- Option 1
- Option 2
Declared business purpose of this payout. Drives documentation requirements and whitelist policy.
intercompany, treasury_management, payment_for_goods_or_services, payroll, investments, other, prefunding, purchase_of_goods, rent, loan_payment, personal_transfer_of_funds, gift, bill_payment, charity, tax_payment, person_to_person_transfer Client-supplied reference, unique per resource within your organization. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces.
^[A-Za-z0-9_\-:.]{1,255}$Wallet to spend from. Omit to use the customer's oldest active wallet on the asset's chain.
^wlt_[0-9A-Za-z]{22}$Your customer's own words for what this payment is. Optional with every purpose, including other. Maximum 280 characters, and it cannot be blank.
1 - 280^(?:[^\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]|[\n\r\t])*$IDs of previously uploaded supporting documents (doc_*), must be uploaded with purpose transaction_support. Maximum 10.
10^doc_[0-9A-Za-z]{22}$Your own margin on this payout, in basis points of the amount it moves, to two decimal places. A payout has no exchange rate to widen, so this is charged as a fee on top of the amount you asked us to send: the recipient still receives assetAmount in full, and the source virtual account is debited that amount plus Conduit's fee plus your margin. It reads back on the payout's fees[] as an entry owned by you, and it is accrued to you once the payout succeeds, then paid monthly against a statement. Crypto payouts cannot carry a margin. Requires markup to be enabled for your organization.
0.01 <= x <= 99999.99Must be a multiple of 0.01Your own margin on this payout as a flat amount per transaction, in the payout's asset and at that asset's precision. Charged the same way as markupBps, on top of the amount the recipient receives. Send it alongside markupBps, on its own, or omit both. Crypto payouts cannot carry a margin.
Response
The fields to send, in the same shape that fields has on the onboarding and feature requirements endpoints. pointer is an RFC 6901 JSON Pointer to the place of the value in the create request body. A field that has conditions is required only while every condition holds. fields gives the same fields in its earlier shape.
Countries this rail cannot pay to, as ISO 3166-1 alpha-3 codes. A payout whose recipient country appears here is rejected.
AFG, ALB, DZA, ASM, AND, AGO, AIA, ATA, ATG, ARG, ARM, ABW, AUS, AUT, AZE, BHS, BHR, BGD, BRB, BLR, BEL, BLZ, BEN, BMU, BTN, BOL, BES, BIH, BWA, BVT, BRA, IOT, BRN, BGR, BFA, BDI, CPV, KHM, CMR, CAN, CYM, CAF, TCD, CHL, CHN, CXR, CCK, COL, COM, COG, COD, COK, CRI, CIV, HRV, CUB, CUW, CYP, CZE, DNK, DJI, DMA, DOM, ECU, EGY, SLV, GNQ, ERI, EST, SWZ, ETH, FLK, FRO, FJI, FIN, FRA, GUF, PYF, ATF, GAB, GMB, GEO, DEU, GHA, GIB, GRC, GRL, GRD, GLP, GUM, GTM, GGY, GIN, GNB, GUY, HTI, HMD, VAT, HND, HKG, HUN, ISL, IND, IDN, IRN, IRQ, IRL, IMN, ISR, ITA, JAM, JPN, JEY, JOR, KAZ, KEN, KIR, PRK, KOR, KWT, KGZ, LAO, LVA, LBN, LSO, LBR, LBY, LIE, LTU, LUX, MAC, MDG, MWI, MYS, MDV, MLI, MLT, MHL, MTQ, MRT, MUS, MYT, MEX, FSM, MDA, MCO, MNG, MNE, MSR, MAR, MOZ, MMR, NAM, NRU, NPL, NLD, NCL, NZL, NIC, NER, NGA, NIU, NFK, MKD, MNP, NOR, OMN, PAK, PLW, PSE, PAN, PNG, PRY, PER, PHL, PCN, POL, PRT, PRI, QAT, REU, ROU, RUS, RWA, BLM, SHN, KNA, LCA, MAF, SPM, VCT, WSM, SMR, STP, SAU, SEN, SRB, SYC, SLE, SGP, SXM, SVK, SVN, SLB, SOM, ZAF, SGS, SSD, ESP, LKA, SDN, SUR, SJM, SWE, CHE, SYR, TWN, TJK, TZA, THA, TLS, TGO, TKL, TON, TTO, TUN, TUR, TKM, TCA, TUV, UGA, UKR, ARE, GBR, USA, UMI, URY, UZB, VUT, VEN, VNM, VGB, VIR, WLF, ESH, YEM, ZMB, ZWE The rail this answer describes. Absent where the candidate is a book transfer between the client's own accounts — a virtual_account or wallet destination — which no payment rail names; fields is then empty and documentation still carries the real answer.
crypto, fedwire, rtp, fednow, ach, ach_same_day, swift, sepa, faster_payments, chaps