Settlement quickstart

Four calls take an account from no destination to settled value. You need an account with at least one connected wallet; create one on Universal Payment Account. Every call uses the sandbox base URL. Swap it for production when you go live; see Environments.

1. List the account’s destinations

curl https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/settlement-destinations \
  -u "$APP_ID:$APP_SECRET"

{
  "accountId": "acct_123",
  "destinations": [
    {
      "id": "destination_123",
      "type": "crypto_wallet",
      "status": "active",
      "preferred": true,
      "capabilities": {
        "settlementSupported": true,
        "unavailableReason": null,
        "network": { "code": "base", "chainId": 8453, "chainFamily": "evm" },
        "assets": [
          { "symbol": "USDC", "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6 }
        ]
      }
    }
  ],
  "nextCursor": null
}

Pick a row where status is active and capabilities.settlementSupported is true, and take its id.

2. Set the settlement profile

curl -X PUT https://staging-api-v2.stableyard.fi/v2/accounts/acct_123/settlement-profile \
  -u "$APP_ID:$APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "settlementDestinationId": "destination_123", "assetSymbol": "USDC" }'

The body takes those two keys and nothing else. assetSymbol is optional.

{
  "id": "settle_123",
  "accountId": "acct_123",
  "version": 2,
  "connectedWalletId": "wallet_123",
  "settlementDestinationId": "destination_123",
  "status": "draft",
  "destinationType": "smart_wallet",
  "chainId": 42161,
  "destinationAddress": "11111111111111111111111111111111",
  "assetSymbol": "USDC",
  "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "snapshot": {}
}

Read status rather than assuming it: a newly created account’s profile is returned as draft, and the enum is draft, active, inactive, failed. Repeating the same selection returns the existing profile, and GET /v2/accounts/{accountId}/settlement-profile returns null when nothing is selected.

3. Collect a payment into the account

Create a receive payment addressed to the account. The destination is not in this request, and never is.

curl -X POST https://staging-api-v2.stableyard.fi/v2/payments \
  -u "$APP_ID:$APP_SECRET" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "receive",
    "recipient": { "accountId": "acct_123" },
    "amountMode": "collect_exact",
    "paymentAmount": {
      "amount": "25.00",
      "assetType": "crypto",
      "assetCode": "USDC",
      "chainId": 42161
    },
    "description": "Invoice #1042",
    "externalReference": "order_1042",
    "expiresInSeconds": 600
  }'

The response freezes the settlement snapshot and the fees onto the payment:

{
  "payment": {
    "id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
    "intent": "receive",
    "status": "requires_payment_method",
    "stage": "awaiting_payment",
    "operationalState": "normal",
    "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"
    },
    "expiresAt": "2026-08-28T10:10:00.000Z"
  }
}

merchantNetAmountAtomic is what the destination receives. Fees are deducted from the verified amount, not recalculated at settlement time.

A recipient account with no active settlement profile is refused with a 409 conflict naming the account. Set the profile before you point any value at an account.

4. Confirm the value landed

curl https://staging-api-v2.stableyard.fi/v2/payments/payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR \
  -u "$APP_ID:$APP_SECRET"

Field	Reading it
`status`	`accepted`: the deposit was verified and settlement is not finished. `succeeded`: the destination was credited
`stage`	Moves through `settlement_pending`, `settlement_broadcast`, `settlement_confirming`
`operationalState`	A `succeeded` payment with `requires_intervention` still needs someone to look at it

Subscribe to payment.accepted and payment.succeeded rather than polling, and treat each event as a prompt to read the payment. payment.settlement_returned fires when a broadcast settlement comes back. See Webhooks. The account now has a standing destination. Every later deposit into it settles there, net of fees, with no destination in any request body.

Next: Settlement lifecycle

When accepted becomes succeeded, and what to read in between.

Start here

Settling

Operating it

Settlement quickstart

1. List the account’s destinations

2. Set the settlement profile

3. Collect a payment into the account

4. Confirm the value landed

Next: Settlement lifecycle

​1. List the account’s destinations

​2. Set the settlement profile

​3. Collect a payment into the account

​4. Confirm the value landed

Next: Settlement lifecycle

1. List the account’s destinations

2. Set the settlement profile

3. Collect a payment into the account

4. Confirm the value landed