Payments
Create a payment
Create a receive or send Payment, the canonical financial obligation for a money flow.
POST
intent picks a business flow (receive or send), not a payer payment method. Idempotency-Key is required; reuse it only with the identical request. The response always uses a payment_* ID. paymentAmount names one asset and exactly one representation, decimal or atomic. Commercial fees, destination, settlement, the optional return URL and capability snapshots are frozen atomically with the Payment.
Receive creates an escrow-backed checkout. Payers then use Direct crypto, cross-chain Routing or an enabled on-ramp method through the Public Checkout API. This create response is the only Partner API response that returns checkout.clientSecret: store it securely, or redirect with checkout.paymentUrl. A returnUrl must exactly match an app URL configured in Payment settings; hosted checkout appends only stableyard_payment_id and never treats the return as payment proof.
Send creates an outgoing execution and its required next action. Preview first and proceed only when the selected source is available.
- Crypto send supports direct transfers and, when enabled, Vault-funded cross-chain routing from Arbitrum. A required route is executable when the Vault funding option reports
vault_routing; Stableyard funds and verifies the route under the same Payment ID. Connected-wallet cross-chain send is unavailable. - External QR, one-time External Bank Transfer and verified Linked Bank Payout are executions of this same Payment; there is no standalone off-ramp API. Offer them only when
/v2/partners/configreports the method available. They verify the destination and resolve funding terms at create time instead of using preview. - For US linked-bank payouts the crypto amount is fixed at creation and the final USD amount is confirmed at payout. Creating the Payment does not move funds.
- For a linked bank, send only
bankAccountId; Stableyard uses the verified bank details on file. - Personal or peer-to-peer QR codes are rejected before quotation with
details.reasonCode: personal_qr_not_supported; use External Bank Transfer instead. - A bank-lookup result marked
provider_state_uncertainis not retryable, because the external rail may already have created a pending transaction.
Authorizations
Headers
Body
application/json
- Receive payment
- Send payment
- External QR payment
- Create payment request
- External bank payment
- Deliver an exact USD amount
- Collect an exact crypto amount
Create a bounded checkout that collects funds and settles them to a UPA or external wallet.
Response
Created payment
The exact action the caller must complete. Null means Stableyard needs no action from the partner right now.
- Action required
- Start account KYC
- Re-verify identity
- Verify UPA email
- Complete hosted compliance
- Waiting for review
- Contact support
- No action required (type none)