Create a payment

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/payments \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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
}
'

{
  "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"
  }
}

POST

payments

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/payments \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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
}
'

{
  "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"
  }
}

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 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 and the Quickstart.

Authorizations

Authorization

string

header

required

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.

Headers

Idempotency-Key

string

required

Required retry key. Reuse only with the identical payment request.

Example:

"payment-request-001"

Stableyard-Version

enum<string>

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.

Available options:

2026-09-09

Body

application/json

Create a bounded checkout that collects funds and settles them to a UPA or external wallet.

intent

string

required

Allowed value: "receive"

recipient

UPA by account ID · object

required

Choose where Stableyard ultimately settles the receive Payment. A UPA uses its settlement profile; an external wallet is paid directly without creating a UPA.

UPA by account ID
UPA by external user ID
External wallet

Show child attributes

paymentAmount

Decimal amount · object

required

Recommended for business integrations. For example, 10.00 USDC.

Decimal amount
Atomic amount

Show child attributes

amountMode

string

default:collect_exact

Allowed value: "collect_exact"

settlement

object

Show child attributes

returnUrl

string<uri>

Optional hosted-checkout return URL. It must exactly match an app URL configured in Payment settings.

Maximum string length: 2048

description

string

Required string length: 1 - 500

externalReference

string

Required string length: 1 - 256

expiresInSeconds

integer

default:600

Required range: 60 <= x <= 86400

metadata

object

Response

Created payment

payment

object

required

Show child attributes

nextAction

Action required · object

required

The exact action the caller must complete. Null means Stableyard needs no action from the partner right now.

Show child attributes

checkout

object

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Authorizations

Headers

Body

Response