> ## Documentation Index > Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment > Create a receive or send Payment, the canonical financial obligation for a money flow. `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](/api-reference/payments/preview-payment) first and proceed only when the selected source is available. * Crypto send supports direct transfers and enabled Arbitrum Vault routing through a deposit-address order. 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/config` reports the method available. They verify the destination and resolve funding terms at create time instead of using preview; the US linked-bank route fixes crypto input without locking final USD delivery, and creating the Payment neither debits the Vault nor submits a duplicate payout. * For a linked bank, send only `bankAccountId`. Stableyard resolves the provider references and creates one idempotent provider transaction before collection. * 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_uncertain` is not retryable, because the external rail may already have created a pending transaction. See [Sending payments](/payments/sending-payments) and the [Quickstart](/payments/quickstart). ## OpenAPI ````yaml openapi.json POST /v2/payments openapi: 3.1.0 info: title: Stableyard Partner API version: 2.0.0-staging x-stableyard-api-version: '2026-09-09' x-stableyard-supported-api-versions: - '2026-09-09' summary: Backend API for UPAs, Payments, activity, and optional financial products. description: > Use this API from a trusted partner backend with an app ID and app secret. ## Recommended integration 1. Call `GET /v2/partners/config` to verify credentials and discover enabled capabilities. 2. Create a UPA only when your product needs a persistent Stableyard account. 3. Create a receive or send Payment with `POST /v2/payments`. 4. Redirect a payer to the returned `paymentUrl` or pass the Payment credentials to an official Stableyard interface SDK. 5. Process signed webhooks and fetch the Payment by ID for reconciliation. Checkout execution and account-bound browser endpoints are intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner servers: - url: https://prod-api.stableyard.fi description: Production - url: https://staging-api-v2.stableyard.fi description: Staging - url: http://localhost:3001 description: Local security: [] tags: - name: Authentication x-displayName: API authentication description: Verify your app ID and app secret before calling UPA APIs. - name: Accounts x-displayName: UPA Accounts description: Create Universal Payment Accounts and manage account settings. - name: Deposit Addresses description: Create reusable receive addresses and verify inbound deposits. - name: Identity & KYC description: >- Verify the UPA email and run provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac controlled stablecoin vaults and manage policy updates for accounts. - name: Payments description: >- Create escrow-first payments, issue partner-authenticated send instructions or executions, power public checkout, and reconcile collection through final account settlement. - name: Balances & Transactions description: >- Read Stableyard-posted financial activity. Balances are ledger projections of activity Stableyard processed; they are not live balances of externally controlled wallets. paths: /v2/payments: post: tags: - Payments summary: Create payment description: >- Creates the canonical financial obligation for a **Receive payment** or **Send payment** flow. These are business intents, not payer payment methods. A receive Payment exposes Direct crypto, Cross-chain routing, and enabled onramp methods through the Public Checkout API after creation. Crypto Send supports executable direct transfers and enabled Arbitrum Vault routing through a deposit-address order. Call `/v2/payments/preview` first and proceed only when the selected source is available. A required route is executable when the Vault funding option reports `vault_routing`. The worker funds and verifies routing under the same Payment ID; connected-wallet cross-chain Send remains unavailable. Optional send rails such as External QR, one-time External Bank Transfer, and a verified Linked Bank Payout remain executions under this same Payment resource and have no standalone Offramp API; expose them only when `/v2/partners/config` reports the method available. Those external fiat rails use create-time destination verification and funding quotes rather than `/v2/payments/preview`; creating the Payment does not debit the Vault or submit a duplicate payout. For a linked bank, the caller supplies only `bankAccountId`; Stableyard resolves encrypted provider references internally and creates one idempotent provider transaction before collection. Personal or peer-to-peer QR codes are rejected before quotation with `details.reasonCode=personal_qr_not_supported` and must be redirected to External Bank Transfer. A bank-lookup result marked `provider_state_uncertain` is not retryable because the external rail may already have created a pending transaction. The response always uses a `payment_*` ID. Receive Payments create an escrow-backed checkout execution; send Payments create an outgoing execution and its required next action. `paymentAmount` has one explicit asset and exactly one decimal or atomic representation. Commercial fees, destination, settlement, optional checkout return URL, and capability snapshots are frozen atomically with the Payment. A receive `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. The receive create response is the only Partner API response that returns `checkout.clientSecret`; store it securely or redirect with `checkout.paymentUrl`. operationId: createPayment parameters: - name: Idempotency-Key in: header required: true schema: type: string example: payment-request-001 description: Required retry key. Reuse only with the identical payment request. - name: Stableyard-Version in: header required: false schema: type: string enum: - '2026-09-09' description: >- Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CanonicalPaymentCreateRequest' examples: receive: summary: Receive into a UPA value: intent: receive recipient: accountId: acct_123 amountMode: collect_exact paymentAmount: amount: '10.00' assetType: crypto assetCode: USDC chainId: 42161 description: 'Order #1001' returnUrl: https://merchant.example/orders/complete expiresInSeconds: 600 directSend: summary: Direct outgoing send value: intent: send sender: accountId: acct_sender destination: type: crypto_wallet chainId: 8453 address: '0x2222222222222222222222222222222222222222' assetCode: USDC amountMode: deliver_exact paymentAmount: amountAtomic: '1000000' decimals: 6 assetType: crypto assetCode: USDC chainId: 8453 externalQrSend: summary: Pay an external merchant QR value: intent: send sender: accountId: acct_sender destination: type: external_qr country: PH qrPayload: 000201010212... amountMode: deliver_exact paymentAmount: amount: '500.00' assetType: fiat assetCode: PHP description: Merchant QR payment externalReference: qr_payment_482 externalBankSend: summary: Pay a Vietnam bank beneficiary value: intent: send sender: accountId: acct_sender destination: type: external_bank country: VN bankCode: '970436' accountNumber: '0123456789' amountMode: deliver_exact paymentAmount: amount: '100000' assetType: fiat assetCode: VND description: Supplier bank transfer externalReference: bank_payment_483 externalBankPhilippinesSend: summary: Pay a Philippines bank beneficiary value: intent: send sender: accountId: acct_sender destination: type: external_bank country: PH bankCode: BPI accountNumber: '09171234567' beneficiaryName: JUAN DELA CRUZ amountMode: deliver_exact paymentAmount: amount: '500.00' assetType: fiat assetCode: PHP description: Beneficiary bank transfer externalReference: bank_payment_484 linkedBankSend: summary: Pay USD to a verified saved US bank beneficiary description: >- The linked-bank provider route has no rate lock, so the delivered USD amount is confirmed only once the provider settles: the sender specifies collect_exact (an exact crypto amount to send), not a fixed USD amount. value: intent: send sender: accountId: acct_sender destination: type: bank_account bankAccountId: bank_123 amountMode: collect_exact paymentAmount: amount: '100.00' assetType: crypto assetCode: USDC chainId: 42161 description: USD withdrawal externalReference: withdrawal_485 publicWalletReceive: summary: Receive into a raw wallet without creating a UPA value: intent: receive recipient: wallet: chainId: 8453 address: '0x2222222222222222222222222222222222222222' assetCode: USDC paymentAmount: amount: '50.00' assetType: crypto assetCode: USDC chainId: 8453 responses: '200': description: Created payment headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/CanonicalPaymentResponse' examples: receivePayment: summary: Receive Payment ready for checkout value: payment: id: payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR apiVersion: '2026-09-09' intent: receive amountMode: collect_exact status: requires_payment_method offrampStatus: null stage: awaiting_payment operationalState: normal operationalReasonCode: null operationalUpdatedAt: null statusVersion: 1 paymentAmount: amount: '25.00' amountAtomic: '25000000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' participants: - role: recipient accountId: acct_123 destination: type: upa accountId: acct_123 settlement: type: settlement_destination settlementDestinationId: destination_123 destinationType: connected_wallet destinationAddress: '0x1111111111111111111111111111111111111111' chainId: 42161 assetCode: USDC tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' decimals: 6 fees: version: 1 pricingStatus: quoted platformFeeBps: 50 partnerFeeBps: 0 platformFeeAmountAtomic: '125000' partnerFeeAmountAtomic: '0' merchantNetAmountAtomic: '24875000' funding: null externalReference: order_1042 description: 'Invoice #1042' metadata: {} expiresAt: '2026-08-28T10:10:00.000Z' acceptedAt: null succeededAt: null cancelledAt: null failure: null refundSummary: status: none count: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' incidentRecoverySummary: count: 0 pendingCount: 0 confirmedCount: 0 failedCount: 0 requiresInterventionCount: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' checkout: paymentUrl: https://pay.stableyard.fi/pay/7Yf3KMpQ2xWa clientSecret: pay_client_secret_opaque_value_123 expiresAt: '2026-08-28T10:10:00.000Z' returnUrl: https://merchant.example/orders/complete nextAction: id: payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR type: payment_method expiresAt: '2026-08-28T10:10:00.000Z' sendPayment: summary: Send Payment requiring a wallet transaction value: payment: id: payment_01JY8M7H3C6D9P2Q4R5T7V8WXA apiVersion: '2026-09-09' intent: send amountMode: deliver_exact status: requires_action offrampStatus: null stage: destination_verifying operationalState: normal operationalReasonCode: null operationalUpdatedAt: null statusVersion: 1 paymentAmount: amount: '10.00' amountAtomic: '10000000' assetType: crypto assetCode: USDC decimals: 6 chainId: 8453 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' sourceAmount: amount: '10.05' amountAtomic: '10050000' assetType: crypto assetCode: USDC decimals: 6 chainId: 8453 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' participants: - role: sender accountId: acct_sender destination: type: crypto_wallet chainId: 8453 address: '0x2222222222222222222222222222222222222222' assetCode: USDC tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' settlement: null fees: version: 1 pricingStatus: quoted platformFeeBps: 50 partnerFeeBps: 0 platformFeeAmountAtomic: '50000' partnerFeeAmountAtomic: '0' merchantNetAmountAtomic: '10000000' funding: null externalReference: transfer_482 description: Vendor payout metadata: {} expiresAt: '2026-08-28T10:10:00.000Z' acceptedAt: null succeededAt: null cancelledAt: null failure: null refundSummary: status: none count: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' incidentRecoverySummary: count: 0 pendingCount: 0 confirmedCount: 0 failedCount: 0 requiresInterventionCount: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' nextAction: id: action_01JY8M8F5N3S7T2V4W6X9ZABCD type: transaction expiresAt: '2026-08-28T10:10:00.000Z' externalQrPayment: summary: External QR Payment ready to collect source funds value: payment: id: payment_01JY8M7H3C6D9P2Q4R5T7V8WQR apiVersion: '2026-09-09' intent: send amountMode: deliver_exact status: requires_payment_method offrampStatus: not_started stage: awaiting_payment operationalState: normal operationalReasonCode: null operationalUpdatedAt: null statusVersion: 1 paymentAmount: amount: '500.00' amountAtomic: '50000' assetType: fiat assetCode: PHP decimals: 2 sourceAmount: amount: '10.05' amountAtomic: '10050000' assetType: crypto assetCode: USDC decimals: 6 chainId: 8453 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' participants: - role: sender accountId: acct_sender destination: type: external_qr country: PH currency: PHP dynamic: true merchant: name: Example Merchant city: Manila settlement: null fees: version: 1 pricingStatus: quoted platformFeeBps: 50 partnerFeeBps: 0 platformFeeAmountAtomic: '50000' partnerFeeAmountAtomic: '0' merchantNetAmountAtomic: '10000000' funding: required: amount: '9.09' amountAtomic: '9090000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerPrincipal: amount: '8.9' amountAtomic: '8900000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerFee: amount: '0.1' amountAtomic: '100000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' platformFee: amount: '0.045' amountAtomic: '45000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' partnerFee: amount: '0.045' amountAtomic: '45000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' totalFees: amount: '0.19' amountAtomic: '190000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' exchangeRate: rate: '0.0178' baseAssetCode: PHP quoteAssetCode: USD quoteExpiresAt: '2026-08-28T10:10:00.000Z' depositAddress: address: '0x2222222222222222222222222222222222222222' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '9.09' amountAtomic: '9090000' externalReference: qr_payment_482 description: Merchant QR payment metadata: {} expiresAt: '2026-08-28T10:10:00.000Z' acceptedAt: null succeededAt: null cancelledAt: null failure: null refundSummary: status: none count: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' incidentRecoverySummary: count: 0 pendingCount: 0 confirmedCount: 0 failedCount: 0 requiresInterventionCount: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' checkout: paymentUrl: https://pay.stableyard.fi/pay/8Qr3KMpQ2xWa clientSecret: pay_client_secret_opaque_value_qr_123 expiresAt: '2026-08-28T10:10:00.000Z' returnUrl: null nextAction: id: payment_01JY8M7H3C6D9P2Q4R5T7V8WQR type: transaction expiresAt: '2026-08-28T10:10:00.000Z' depositInstructions: address: '0x2222222222222222222222222222222222222222' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '9.09' amountAtomic: '9090000' externalBankPayment: summary: External bank Payment ready to collect source funds value: payment: id: payment_01JY8M7H3C6D9P2Q4R5BANK001 apiVersion: '2026-09-09' intent: send amountMode: deliver_exact status: requires_payment_method offrampStatus: not_started stage: awaiting_payment operationalState: normal operationalReasonCode: null operationalUpdatedAt: null statusVersion: 1 paymentAmount: amount: '100000' amountAtomic: '100000' assetType: fiat assetCode: VND decimals: 0 sourceAmount: amount: '10.05' amountAtomic: '10050000' assetType: crypto assetCode: USDC decimals: 6 chainId: 8453 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' participants: - role: sender accountId: acct_sender destination: type: external_bank country: VN currency: VND beneficiary: accountHolderName: NGUYEN VAN A accountNumberLast4: '6789' bankCode: '970436' bankName: Vietcombank country: VN settlement: null fees: version: 1 pricingStatus: quoted platformFeeBps: 50 partnerFeeBps: 0 platformFeeAmountAtomic: '50000' partnerFeeAmountAtomic: '0' merchantNetAmountAtomic: '10000000' funding: required: amount: '4.242' amountAtomic: '4242000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerPrincipal: amount: '4.1' amountAtomic: '4100000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerFee: amount: '0.1' amountAtomic: '100000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' platformFee: amount: '0.021' amountAtomic: '21000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' partnerFee: amount: '0.021' amountAtomic: '21000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' totalFees: amount: '0.142' amountAtomic: '142000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' exchangeRate: rate: '24390.24' baseAssetCode: USDC quoteAssetCode: VND quoteExpiresAt: '2026-08-28T10:10:00.000Z' depositAddress: address: '0x3333333333333333333333333333333333333333' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '4.242' amountAtomic: '4242000' externalReference: bank_payment_483 description: Supplier bank transfer metadata: {} expiresAt: '2026-08-28T10:10:00.000Z' acceptedAt: null succeededAt: null cancelledAt: null failure: null refundSummary: status: none count: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' incidentRecoverySummary: count: 0 pendingCount: 0 confirmedCount: 0 failedCount: 0 requiresInterventionCount: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' checkout: paymentUrl: https://pay.stableyard.fi/pay/8Qr3KMpQ2xWa clientSecret: pay_client_secret_opaque_value_qr_123 expiresAt: '2026-08-28T10:10:00.000Z' returnUrl: null nextAction: id: payment_01JY8M7H3C6D9P2Q4R5BANK001 type: transaction expiresAt: '2026-08-28T10:10:00.000Z' depositInstructions: address: '0x3333333333333333333333333333333333333333' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '4.242' amountAtomic: '4242000' linkedBankPayment: summary: Linked bank Payment ready to collect source funds value: payment: id: payment_01JY8M7H3C6D9P2Q4R5LNKB001 apiVersion: '2026-09-09' intent: send amountMode: collect_exact status: requires_payment_method offrampStatus: not_started stage: awaiting_payment operationalState: normal operationalReasonCode: null operationalUpdatedAt: null statusVersion: 1 paymentAmount: amount: '100.00' amountAtomic: '100000000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' sourceAmount: amount: '10.05' amountAtomic: '10050000' assetType: crypto assetCode: USDC decimals: 6 chainId: 8453 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' participants: - role: sender accountId: acct_sender destination: type: bank_account bankAccountId: bank_123 country: US currency: USD bankName: Example Bank accountNumberLast4: '6789' rail: ach settlement: null fees: version: 1 pricingStatus: quoted platformFeeBps: 50 partnerFeeBps: 0 platformFeeAmountAtomic: '50000' partnerFeeAmountAtomic: '0' merchantNetAmountAtomic: '10000000' funding: required: amount: '100.00' amountAtomic: '100000000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerPrincipal: amount: '99.5' amountAtomic: '99500000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' providerFee: amount: '0' amountAtomic: '0' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' platformFee: amount: '0.5' amountAtomic: '500000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' partnerFee: amount: '0' amountAtomic: '0' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' totalFees: amount: '0.5' amountAtomic: '500000' assetType: crypto assetCode: USDC decimals: 6 chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' exchangeRate: null quoteExpiresAt: '2026-08-28T10:10:00.000Z' depositAddress: address: '0x4444444444444444444444444444444444444444' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '100.00' amountAtomic: '100000000' externalReference: withdrawal_485 description: USD withdrawal metadata: {} expiresAt: '2026-08-28T10:10:00.000Z' acceptedAt: null succeededAt: null cancelledAt: null failure: null refundSummary: status: none count: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' incidentRecoverySummary: count: 0 pendingCount: 0 confirmedCount: 0 failedCount: 0 requiresInterventionCount: 0 requestedAmountAtomic: '0' confirmedAmountAtomic: '0' createdAt: '2026-08-28T10:00:00.000Z' updatedAt: '2026-08-28T10:00:00.000Z' checkout: paymentUrl: https://pay.stableyard.fi/pay/9Lb4XQmN3zR7 clientSecret: pay_client_secret_opaque_value_lnkb_001 expiresAt: '2026-08-28T10:10:00.000Z' returnUrl: null nextAction: id: payment_01JY8M7H3C6D9P2Q4R5LNKB001 type: transaction expiresAt: '2026-08-28T10:10:00.000Z' depositInstructions: address: '0x4444444444444444444444444444444444444444' chainId: 42161 tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' assetCode: USDC decimals: 6 amount: '100.00' amountAtomic: '100000000' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '424': $ref: '#/components/responses/FailedDependency' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' security: - partnerBasicAuth: [] components: schemas: CanonicalPaymentCreateRequest: title: Create payment request description: >- Choose Receive payment when collecting money and Send payment when moving funds owned by an existing UPA. Payment methods such as Direct crypto, Routing, and an enabled hosted on-ramp are selected later within a receive Payment. oneOf: - title: Receive payment description: >- Create a bounded checkout that collects funds and settles them to a UPA or external wallet. type: object additionalProperties: false required: - intent - recipient - paymentAmount properties: intent: type: string const: receive recipient: $ref: '#/components/schemas/CanonicalReceiveRecipient' amountMode: type: string const: collect_exact default: collect_exact paymentAmount: $ref: '#/components/schemas/CanonicalPaymentAmountInput' settlement: type: object additionalProperties: false required: - settlementDestinationId properties: settlementDestinationId: type: string minLength: 1 maxLength: 128 returnUrl: type: string format: uri maxLength: 2048 description: >- Optional hosted-checkout return URL. It must exactly match an app URL configured in Payment settings. description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true - $ref: '#/components/schemas/CanonicalSendPaymentCreateRequest' title: Send payment - $ref: '#/components/schemas/CanonicalExternalQrPaymentCreateRequest' title: External QR payment - $ref: '#/components/schemas/CanonicalExternalBankPaymentCreateRequest' title: External bank payment - $ref: '#/components/schemas/CanonicalLinkedBankPaymentCreateRequest' title: Linked bank payout CanonicalPaymentResponse: type: object additionalProperties: false required: - payment - nextAction properties: payment: $ref: '#/components/schemas/CanonicalPaymentResource' checkout: type: object additionalProperties: false required: - paymentUrl - clientSecret - expiresAt - returnUrl properties: paymentUrl: type: string format: uri clientSecret: type: string minLength: 32 maxLength: 512 expiresAt: type: string format: date-time returnUrl: type: - string - 'null' format: uri nextAction: $ref: '#/components/schemas/CanonicalPaymentNextAction' CanonicalReceiveRecipient: title: Receive payment recipient description: >- Choose where Stableyard ultimately settles the receive Payment. A UPA uses its settlement profile; an external wallet is paid directly without creating a UPA. oneOf: - title: UPA by account ID type: object additionalProperties: false required: - accountId properties: accountId: type: string example: acct_123 - title: UPA by external user ID type: object additionalProperties: false required: - externalUserId properties: externalUserId: type: string maxLength: 128 example: user_123 - title: External wallet type: object additionalProperties: false required: - wallet properties: wallet: type: object additionalProperties: false required: - chainId - address - assetCode properties: chainId: type: integer minimum: 1 example: 8453 address: type: string minLength: 8 maxLength: 256 assetCode: type: string example: USDC tokenAddress: type: string minLength: 1 maxLength: 256 CanonicalPaymentAmountInput: title: Payment amount description: >- Specify the payment amount once, either as a human-readable decimal string or in token atomic units. Never send both representations. oneOf: - $ref: '#/components/schemas/CanonicalDecimalPaymentAmountInput' title: Decimal amount - $ref: '#/components/schemas/CanonicalAtomicPaymentAmountInput' title: Atomic amount CanonicalSendPaymentCreateRequest: title: Send payment description: >- Move funds from an existing UPA payment source to another UPA, payment handle, or external crypto wallet. Crypto Send supports direct transfers and, when enabled, Vault-funded cross-chain or cross-token Routing. The paymentAmount identifies the exact destination asset and amount. Commercial fees are calculated on the quoted source input and added on top; sourceAmount shows the total sender debit. Routing uses exact_output and does not reduce the authorized destination amount for slippage. Preview first and stop when the selected source is unavailable. Routed Vault sends retain the same canonical Payment ID through source funding, destination verification and refund recovery; the routing deposit address is an internal execution detail. type: object additionalProperties: false required: - intent - sender - destination - paymentAmount properties: intent: type: string const: send sender: $ref: '#/components/schemas/CanonicalAccountLocator' destination: $ref: '#/components/schemas/CanonicalSendDestination' amountMode: type: string const: deliver_exact default: deliver_exact mandateId: type: string minLength: 1 maxLength: 64 description: >- Optional active Vault mandate authorizing this outgoing occurrence. A mandate constrains Vault spending; it does not schedule recurring Payments. example: vault_mandate_123 paymentAmount: $ref: '#/components/schemas/CanonicalPaymentAmountInput' description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true CanonicalExternalQrPaymentCreateRequest: title: External QR payment description: >- Pay a provider-resolved merchant QR through the canonical Payment API. The merchant receives the exact fiat obligation (`deliver_exact`); Stableyard separately collects the quoted stablecoin amount from the sender's active Payment Source. This rail has no standalone Offramp API and cannot use the stateless preview endpoint. type: object additionalProperties: false required: - intent - sender - destination - amountMode - paymentAmount properties: intent: type: string const: send sender: $ref: '#/components/schemas/CanonicalAccountLocator' destination: type: object additionalProperties: false required: - type - country - qrPayload properties: type: type: string const: external_qr country: type: string minLength: 2 maxLength: 2 pattern: ^[A-Za-z]{2}$ example: PH qrPayload: type: string minLength: 1 maxLength: 4096 example: 000201010212... amountMode: type: string const: deliver_exact paymentAmount: $ref: '#/components/schemas/CanonicalFiatPaymentAmountInput' description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true CanonicalExternalBankPaymentCreateRequest: title: External bank payment description: >- Pay an exact fiat amount to a one-time bank beneficiary supplied inline. Stableyard verifies the account and freezes the provider quote before source-fund collection. US payouts require a saved linked-bank destination instead. The account number is never returned or persisted in raw form. type: object additionalProperties: false required: - intent - sender - destination - amountMode - paymentAmount properties: intent: type: string const: send sender: $ref: '#/components/schemas/CanonicalAccountLocator' destination: type: object additionalProperties: false required: - type - country - bankCode - accountNumber properties: type: type: string const: external_bank country: type: string minLength: 2 maxLength: 2 pattern: ^[A-Za-z]{2}$ example: VN bankCode: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ example: '970436' accountNumber: type: string minLength: 4 maxLength: 64 writeOnly: true example: '0123456789' beneficiaryName: type: string minLength: 1 maxLength: 200 description: >- Required for Philippines (PH) bank transfers; optional for Vietnam (VN). Supply the beneficiary's bank account holder name. Stableyard checks the provider's returned beneficiary against this name. if: properties: country: pattern: ^[Pp][Hh]$ required: - country then: required: - beneficiaryName amountMode: type: string const: deliver_exact paymentAmount: $ref: '#/components/schemas/CanonicalFiatPaymentAmountInput' description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true CanonicalLinkedBankPaymentCreateRequest: title: Linked bank payout description: >- Pay a verified bank account already linked to the sending UPA. Stableyard resolves the active provider relationship and encrypted provider destination internally; callers supply only the Stableyard bankAccountId. Whether an exact USD amount (deliver_exact) or an exact crypto amount (collect_exact) is accepted depends on the resolved provider route: a route with a rate lock/quote requires deliver_exact; a route with no rate lock (the delivered USD is confirmed only once the provider settles) requires collect_exact. oneOf: - title: Deliver an exact USD amount description: >- Only for a linked-bank route that can quote a rate lock ahead of collection. type: object additionalProperties: false required: - intent - sender - destination - amountMode - paymentAmount properties: intent: type: string const: send sender: $ref: '#/components/schemas/CanonicalAccountLocator' destination: type: object additionalProperties: false required: - type - bankAccountId properties: type: type: string const: bank_account bankAccountId: type: string pattern: ^bank_[A-Za-z0-9_-]{3,59}$ example: bank_123 amountMode: type: string const: deliver_exact paymentAmount: $ref: '#/components/schemas/CanonicalFiatPaymentAmountInput' description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true - title: Collect an exact crypto amount description: >- For a linked-bank route with no rate lock: the sender specifies exactly how much crypto to send, and the delivered USD amount is confirmed only once the provider settles. type: object additionalProperties: false required: - intent - sender - destination - amountMode - paymentAmount properties: intent: type: string const: send sender: $ref: '#/components/schemas/CanonicalAccountLocator' destination: type: object additionalProperties: false required: - type - bankAccountId properties: type: type: string const: bank_account bankAccountId: type: string pattern: ^bank_[A-Za-z0-9_-]{3,59}$ example: bank_123 amountMode: type: string const: collect_exact paymentAmount: $ref: '#/components/schemas/CanonicalPaymentAmountInput' description: type: string minLength: 1 maxLength: 500 externalReference: type: string minLength: 1 maxLength: 256 expiresInSeconds: type: integer minimum: 60 maximum: 86400 default: 600 metadata: type: object additionalProperties: true CanonicalPaymentResource: type: object additionalProperties: false required: - id - apiVersion - intent - amountMode - status - offrampStatus - stage - operationalState - operationalReasonCode - operationalUpdatedAt - statusVersion - paymentAmount - participants - destination - settlement - fees - funding - externalReference - description - metadata - expiresAt - acceptedAt - succeededAt - cancelledAt - failure - refundSummary - incidentRecoverySummary - createdAt - updatedAt properties: id: type: string pattern: ^payment_[A-Za-z0-9_-]+$ apiVersion: $ref: '#/components/schemas/StableyardApiVersion' intent: type: string enum: - receive - send amountMode: type: string enum: - collect_exact - deliver_exact status: type: string enum: - requires_payment_method - requires_action - processing - accepted - succeeded - failed - cancelled - expired description: >- Customer-facing financial lifecycle. Operational recovery never regresses a succeeded Payment or replaces this value with requires_intervention. offrampStatus: type: - string - 'null' enum: - not_started - processing - failed - refunding - refunded - succeeded - null description: >- External payout outcome. failed requires a verified terminal payout failure after confirmed treasury funding; any pre-funding failure is not_started. refunding means an operations recovery has reserved the treasury-held source amount for the sending UPA's frozen preferred crypto settlement destination, and refunded means that settlement is confirmed. Null for other Payment types. stage: type: - string - 'null' enum: - escrow_provisioning - awaiting_payment - destination_verifying - provider_processing - quote_pending - transaction_broadcast - receipt_verifying - payment_detected - settlement_pending - settlement_broadcast - settlement_confirming - settlement_returned - payout_pending - payout_processing - payout_confirming - refund_pending - refund_broadcast - null description: >- Current financial-processing stage. Operational review is represented separately by operationalState. operationalState: type: string enum: - normal - retrying - requires_intervention description: >- Operational health of the Payment. requires_intervention means Stableyard operations must act; it is not a financial payment status. operationalReasonCode: type: - string - 'null' enum: - collection_requires_intervention - custody_after_failure - duplicate_payment_detected - fee_payout_failed - fee_payout_requires_intervention - fee_payout_retry_scheduled - late_payment_received - payment_execution_requires_intervention - payment_execution_retry_scheduled - escrow_provisioning_retry_scheduled - payment_session_requires_intervention - payout_failed - payout_requires_intervention - payout_retry_scheduled - refund_failed - refund_requires_intervention - refund_retry_scheduled - settlement_failed - settlement_requires_intervention - settlement_retry_scheduled - settlement_unconfirmed - null description: >- Machine-readable operational reason when operationalState is not normal. operationalUpdatedAt: type: - string - 'null' format: date-time description: When the operational state or reason last changed. statusVersion: type: integer minimum: 1 paymentAmount: $ref: '#/components/schemas/CanonicalPaymentAmount' sourceAmount: $ref: '#/components/schemas/CanonicalPaymentAmount' description: >- Frozen source debit including commercial fees, exposed for Send execution to callers permitted to view sender fees. participants: type: array items: $ref: '#/components/schemas/CanonicalPaymentParticipant' description: >- Only participant UPAs owned by the authenticated tenant are returned. The array can be empty for creator-only visibility. recipientDisplay: oneOf: - title: Recipient display snapshot type: object additionalProperties: false required: - displayName - logoUrl properties: displayName: type: string minLength: 1 maxLength: 120 logoUrl: type: - string - 'null' format: uri maxLength: 2048 - title: No recipient display snapshot type: 'null' description: >- Immutable payer-facing recipient identity captured when the Payment was created. destination: $ref: '#/components/schemas/CanonicalPaymentDestination' settlement: description: >- Immutable receive-side settlement snapshot. Null for Payment types that do not use a receive settlement destination. oneOf: - $ref: '#/components/schemas/CanonicalPaymentSettlement' title: Settlement destination - title: No settlement destination type: 'null' fees: oneOf: - title: Commercial fee quote pending type: object additionalProperties: false required: - version - pricingStatus - platformFeeBps - partnerFeeBps - platformFeeAmountAtomic - partnerFeeAmountAtomic - merchantNetAmountAtomic properties: version: type: - string - number - 'null' pricingStatus: type: string const: quote_pending platformFeeBps: type: integer minimum: 0 maximum: 10000 partnerFeeBps: type: integer minimum: 0 maximum: 10000 platformFeeAmountAtomic: type: 'null' partnerFeeAmountAtomic: type: 'null' merchantNetAmountAtomic: type: 'null' - title: Quoted commercial fee snapshot type: object additionalProperties: false required: - version - pricingStatus - platformFeeBps - partnerFeeBps - platformFeeAmountAtomic - partnerFeeAmountAtomic - merchantNetAmountAtomic properties: version: type: - string - number - 'null' pricingStatus: type: string const: quoted platformFeeBps: type: integer minimum: 0 maximum: 10000 partnerFeeBps: type: integer minimum: 0 maximum: 10000 platformFeeAmountAtomic: type: string maxLength: 80 pattern: ^(0|[1-9][0-9]*)$ partnerFeeAmountAtomic: type: string maxLength: 80 pattern: ^(0|[1-9][0-9]*)$ merchantNetAmountAtomic: type: string maxLength: 80 pattern: ^(0|[1-9][0-9]*)$ - title: Fees unavailable type: 'null' description: >- Commercial fee terms are returned only to the partner that owns them. quote_pending exposes frozen BPS but keeps exact monetary amounts null until the provider quote is frozen; quoted exposes immutable exact atomic amounts, including genuine zero values. funding: description: >- Create-time funding quote for an external fiat send rail. required is the exact source amount shown before Vault authorization; creation itself does not debit funds or submit the destination payout. Null for ordinary receive and direct-send Payments. oneOf: - $ref: '#/components/schemas/CanonicalExternalQrFunding' title: External provider payout funding - title: No separate funding collection type: 'null' externalReference: type: - string - 'null' description: type: - string - 'null' metadata: type: object additionalProperties: true expiresAt: type: - string - 'null' format: date-time acceptedAt: type: - string - 'null' format: date-time succeededAt: type: - string - 'null' format: date-time cancelledAt: type: - string - 'null' format: date-time failure: oneOf: - title: Failure details type: object additionalProperties: false required: - code - message properties: code: type: - string - 'null' message: type: - string - 'null' - title: No failure type: 'null' refundSummary: $ref: '#/components/schemas/CanonicalPaymentRefundSummary' incidentRecoverySummary: $ref: '#/components/schemas/CanonicalPaymentIncidentRecoverySummary' createdAt: type: string format: date-time updatedAt: type: string format: date-time CanonicalPaymentNextAction: title: Payment next action description: >- The exact action the caller must complete. Null means Stableyard needs no action from the partner right now. oneOf: - title: Action required type: object additionalProperties: false required: - id - type - expiresAt properties: id: type: string type: type: string enum: - transaction - managed_authorization - payment_method expiresAt: type: - string - 'null' format: date-time depositInstructions: $ref: '#/components/schemas/CanonicalPaymentDepositInstructions' description: >- Present only when type is "transaction" for a collection deposit: the exact on-chain payment to make to advance this Payment. - title: Start account KYC type: object additionalProperties: false required: - type properties: type: type: string const: start_kyc_session - title: Verify UPA email type: object additionalProperties: false required: - type properties: type: type: string const: verify_account_email - title: Complete hosted compliance description: >- Open this Stableyard-hosted URL as a top-level page. The link uses a one-time exchange and asks only for information missing from the verified account. type: object additionalProperties: false required: - type - url - expiresAt properties: type: type: string const: complete_compliance url: type: string format: uri expiresAt: type: string format: date-time - title: Wait for partner KYC type: object additionalProperties: false required: - type properties: type: type: string const: wait_for_partner_kyc - title: Contact support type: object additionalProperties: false required: - type properties: type: type: string const: contact_support - title: No provider action type: object additionalProperties: false required: - type properties: type: type: string const: none - title: No action required type: 'null' ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string minLength: 1 maxLength: 128 example: bad_request message: type: string minLength: 1 maxLength: 1000 example: The request is invalid details: {} CanonicalDecimalPaymentAmountInput: title: Decimal amount description: Recommended for business integrations. For example, `10.00` USDC. type: object additionalProperties: false required: - amount - assetCode properties: amount: type: string minLength: 1 maxLength: 100 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ example: '50.00' assetType: type: string enum: - crypto - fiat default: crypto assetCode: type: string pattern: ^[A-Z0-9][A-Z0-9._-]{1,23}$ example: USDC chainId: type: integer minimum: 1 example: 8453 tokenAddress: type: string minLength: 1 maxLength: 256 CanonicalAtomicPaymentAmountInput: title: Atomic amount description: >- Use when your application already works in token atomic units. `decimals` is required. type: object additionalProperties: false required: - amountAtomic - decimals - assetCode properties: amountAtomic: type: string minLength: 1 maxLength: 80 pattern: ^[1-9][0-9]*$ example: '50000000' assetType: type: string enum: - crypto - fiat default: crypto assetCode: type: string pattern: ^[A-Z0-9][A-Z0-9._-]{1,23}$ example: USDC chainId: type: integer minimum: 1 example: 8453 tokenAddress: type: string minLength: 1 maxLength: 256 decimals: type: integer minimum: 0 maximum: 36 example: 6 CanonicalAccountLocator: title: UPA account locator description: >- Identify a UPA using either its Stableyard account ID or your own external user ID. oneOf: - title: Stableyard account ID type: object additionalProperties: false required: - accountId properties: accountId: type: string example: acct_123 - title: External user ID type: object additionalProperties: false required: - externalUserId properties: externalUserId: type: string maxLength: 128 example: user_123 CanonicalSendDestination: title: Send payment destination description: >- Send to another UPA, a payment handle, or an external crypto wallet. External QR and bank rails use their dedicated request variants below. oneOf: - title: UPA account type: object additionalProperties: false required: - type - account properties: type: type: string const: upa account: $ref: '#/components/schemas/CanonicalAccountLocator' - title: Payment handle type: object additionalProperties: false required: - type - paymentHandle properties: type: type: string const: payment_handle paymentHandle: type: string minLength: 1 maxLength: 128 example: alice@partner - title: External crypto wallet type: object additionalProperties: false required: - type - chainId - address - assetCode properties: type: type: string const: crypto_wallet chainId: type: integer minimum: 1 example: 8453 address: type: string minLength: 8 maxLength: 256 example: '0x2222222222222222222222222222222222222222' assetCode: type: string example: USDC tokenAddress: type: string CanonicalFiatPaymentAmountInput: title: Fiat payment amount oneOf: - $ref: '#/components/schemas/CanonicalFiatDecimalPaymentAmountInput' title: Decimal fiat amount - $ref: '#/components/schemas/CanonicalFiatAtomicPaymentAmountInput' title: Atomic fiat amount StableyardApiVersion: type: string enum: - '2026-08-28' - '2026-09-09' example: '2026-09-09' description: >- Immutable date-based contract recorded on the resource. Historical values may appear on existing records; only versions advertised in x-stableyard-supported-api-versions are accepted for new requests. CanonicalPaymentAmount: type: object additionalProperties: false required: - amount - amountAtomic - assetType - assetCode - decimals properties: amount: type: string minLength: 1 maxLength: 100 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ example: '50.00' amountAtomic: type: string minLength: 1 maxLength: 80 pattern: ^[1-9][0-9]*$ example: '50000000' assetType: type: string enum: - crypto - fiat assetCode: type: string example: USDC decimals: type: integer minimum: 0 maximum: 36 example: 6 chainId: type: integer minimum: 1 example: 8453 tokenAddress: type: string CanonicalPaymentParticipant: type: object additionalProperties: false required: - role - accountId properties: role: type: string enum: - sender - recipient accountId: type: string description: >- A UPA account belonging to the authenticated organization, app, and environment. Participants owned by another tenant are omitted. CanonicalPaymentDestination: title: Resolved payment destination oneOf: - title: UPA account type: object additionalProperties: false required: - type - accountId properties: type: type: string const: upa accountId: type: string - title: Payment handle type: object additionalProperties: false required: - type - paymentHandle - accountId properties: type: type: string const: payment_handle paymentHandle: type: string accountId: type: string - title: External crypto wallet type: object additionalProperties: false required: - type - chainId - address - assetCode - tokenAddress properties: type: type: string const: crypto_wallet chainId: type: integer minimum: 1 address: type: string assetCode: type: string tokenAddress: type: string - title: External merchant QR type: object additionalProperties: false required: - type - country - currency - dynamic - merchant properties: type: type: string const: external_qr country: type: string pattern: ^[A-Z]{2}$ example: PH currency: type: string pattern: ^[A-Z]{3}$ example: PHP dynamic: type: boolean merchant: oneOf: - title: Merchant details type: object additionalProperties: false required: - name - city properties: name: type: - string - 'null' city: type: - string - 'null' - title: Merchant details unavailable type: 'null' - title: External bank beneficiary type: object additionalProperties: false required: - type - country - currency - beneficiary properties: type: type: string const: external_bank country: type: string pattern: ^[A-Z]{2}$ example: VN currency: type: string pattern: ^[A-Z]{3}$ example: VND beneficiary: type: object additionalProperties: false required: - accountHolderName - accountNumberLast4 - bankCode - bankName - country properties: accountHolderName: type: - string - 'null' maxLength: 200 accountNumberLast4: type: - string - 'null' pattern: ^[A-Za-z0-9]{4}$ bankCode: type: - string - 'null' maxLength: 64 bankName: type: - string - 'null' maxLength: 200 country: type: - string - 'null' pattern: ^[A-Z]{2}$ - title: Verified linked bank account type: object additionalProperties: false required: - type - bankAccountId - country - currency - bankName - accountNumberLast4 - rail properties: type: type: string const: bank_account bankAccountId: type: string pattern: ^bank_[A-Za-z0-9_-]{3,59}$ example: bank_123 country: type: string pattern: ^[A-Z]{2}$ example: US currency: type: string pattern: ^[A-Z]{3}$ example: USD bankName: type: string minLength: 1 maxLength: 160 example: Example Bank accountNumberLast4: type: string pattern: ^[A-Za-z0-9]{4,8}$ example: '6789' rail: type: string minLength: 1 maxLength: 64 example: ach discriminator: propertyName: type CanonicalPaymentSettlement: type: object additionalProperties: false required: - type - settlementDestinationId - destinationType - destinationAddress - chainId - assetCode - tokenAddress - decimals properties: type: type: string enum: - settlement_destination - crypto_wallet settlementDestinationId: type: - string - 'null' destinationType: type: string destinationAddress: type: string chainId: type: integer minimum: 1 assetCode: type: string tokenAddress: type: string decimals: type: integer minimum: 0 maximum: 36 CanonicalExternalQrFunding: type: object additionalProperties: false required: - required - providerPrincipal - providerFee - platformFee - partnerFee - totalFees - exchangeRate - quoteExpiresAt - depositAddress properties: mode: type: string enum: - escrow - vault_treasury description: >- New external payouts use a unique Payment escrow. vault_treasury is returned only for legacy direct-funded records that remain under reconciliation. required: $ref: '#/components/schemas/CanonicalFundingAmount' providerPrincipal: oneOf: - $ref: '#/components/schemas/CanonicalFundingAmount' - type: 'null' providerFee: oneOf: - $ref: '#/components/schemas/CanonicalFundingAmount' - type: 'null' platformFee: oneOf: - $ref: '#/components/schemas/CanonicalFundingAmount' - type: 'null' partnerFee: oneOf: - $ref: '#/components/schemas/CanonicalFundingAmount' - type: 'null' totalFees: description: >- Total payout fees in the funding asset: providerFee + platformFee (Stableyard) + partnerFee (app partner). Already included in required; do not add again. Null when fee visibility is restricted or a frozen component is unavailable. Excludes any additional fee quoted separately by a selected funding method. oneOf: - $ref: '#/components/schemas/CanonicalFundingAmount' - type: 'null' exchangeRate: description: >- Directional rate frozen from the payout quote. One unit of baseAssetCode equals rate units of quoteAssetCode. oneOf: - type: object additionalProperties: false required: - rate - baseAssetCode - quoteAssetCode properties: rate: type: string pattern: ^(?=.*[1-9])(?:0|[1-9][0-9]*)(?:\.[0-9]{1,18})?$ baseAssetCode: type: string quoteAssetCode: type: string - type: 'null' quoteExpiresAt: type: - string - 'null' format: date-time depositAddress: description: >- Where the sender must deposit the collection asset before Stableyard forwards net proceeds to the provider. Null until the collection escrow is provisioned and live. oneOf: - $ref: '#/components/schemas/CanonicalPaymentDepositInstructions' - type: 'null' CanonicalPaymentRefundSummary: type: object additionalProperties: false required: - status - count - requestedAmountAtomic - confirmedAmountAtomic properties: status: type: string enum: - none - pending - partially_refunded - refunded - failed - requires_intervention count: type: integer minimum: 0 requestedAmountAtomic: type: string pattern: ^[0-9]+$ confirmedAmountAtomic: type: string pattern: ^[0-9]+$ description: >- Aggregate progress for Refund resources attached to this Payment. Supported direct receive refunds are created through the Partner API; eligible failed external payouts use a separate operations recovery after confirmed treasury receipt. CanonicalPaymentIncidentRecoverySummary: type: object additionalProperties: false required: - count - pendingCount - confirmedCount - failedCount - requiresInterventionCount - requestedAmountAtomic - confirmedAmountAtomic properties: count: type: integer minimum: 0 pendingCount: type: integer minimum: 0 confirmedCount: type: integer minimum: 0 failedCount: type: integer minimum: 0 requiresInterventionCount: type: integer minimum: 0 requestedAmountAtomic: type: string pattern: ^[0-9]+$ confirmedAmountAtomic: type: string pattern: ^[0-9]+$ description: >- Recovery of duplicate, late, overpaid, or underpaid receipts. These amounts never contribute to refundSummary for the accepted merchant payment. CanonicalPaymentDepositInstructions: type: object additionalProperties: false required: - address - chainId - tokenAddress - assetCode - decimals - amount - amountAtomic description: >- The exact on-chain deposit to make. Send precisely amountAtomic of tokenAddress on chainId to address; anything else will not be recognized as this Payment's funding. properties: address: type: string chainId: type: integer minimum: 1 tokenAddress: type: string assetCode: type: string decimals: type: integer minimum: 0 maximum: 36 amount: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ amountAtomic: type: string pattern: ^[0-9]+$ CanonicalFiatDecimalPaymentAmountInput: title: Decimal fiat amount description: >- The exact fiat amount the merchant must receive. The currency must match the selected QR country. type: object additionalProperties: false required: - amount - assetType - assetCode properties: amount: type: string minLength: 1 maxLength: 100 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ example: '500.00' assetType: type: string const: fiat assetCode: type: string pattern: ^[A-Z][A-Z0-9._-]{1,23}$ example: PHP CanonicalFiatAtomicPaymentAmountInput: title: Atomic fiat amount description: >- The exact fiat amount in the currency's minor units. `decimals` must match the selected QR country's currency. type: object additionalProperties: false required: - amountAtomic - decimals - assetType - assetCode properties: amountAtomic: type: string minLength: 1 maxLength: 80 pattern: ^[1-9][0-9]*$ example: '50000' decimals: type: integer minimum: 0 maximum: 36 example: 2 assetType: type: string const: fiat assetCode: type: string pattern: ^[A-Z][A-Z0-9._-]{1,23}$ example: PHP CanonicalFundingAmount: type: object additionalProperties: false required: - amount - amountAtomic - assetType - assetCode - decimals - chainId - tokenAddress properties: amount: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ amountAtomic: type: string pattern: ^[0-9]+$ assetType: type: string const: crypto assetCode: type: string decimals: type: integer minimum: 0 maximum: 36 chainId: type: integer minimum: 1 tokenAddress: type: string responses: BadRequest: description: Bad request headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: BadRequest response value: error: code: bad_request message: The request is invalid details: example Unauthorized: description: Unauthorized headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Unauthorized response value: error: code: bad_request message: The request is invalid details: example Forbidden: description: The app secret does not include the required scope headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Forbidden response value: error: code: bad_request message: The request is invalid details: example NotFound: description: Not found headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: NotFound response value: error: code: bad_request message: The request is invalid details: example Conflict: description: Conflict headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Conflict response value: error: code: bad_request message: The request is invalid details: example UnprocessableEntity: description: The requested payment method or refund route is not supported headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: UnprocessableEntity response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' Retry-After: description: Seconds until the caller should retry. schema: type: integer minimum: 1 RateLimit-Limit: description: Quota for the most constrained policy. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requests remaining in that policy window. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until that policy window resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example ServiceUnavailable: description: Payment provider or escrow provisioning is unavailable headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: ServiceUnavailable response value: error: code: bad_request message: The request is invalid details: example securitySchemes: partnerBasicAuth: type: http scheme: basic description: >- HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.