Preview a send payment

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/payments/preview \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent": "send",
  "sender": {
    "accountId": "acct_sender"
  },
  "destination": {
    "type": "payment_handle",
    "paymentHandle": "alice@partner"
  },
  "paymentAmount": {
    "amount": "1.00",
    "assetCode": "USDC"
  }
}
'

{
  "sender": {
    "accountId": "acct_sender"
  },
  "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"
  },
  "destination": {
    "type": "crypto_wallet",
    "chainId": 8453,
    "address": "0x2222222222222222222222222222222222222222",
    "assetCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "estimatedSettlementAmount": {
    "amount": "10.00",
    "amountAtomic": "10000000",
    "assetType": "crypto",
    "assetCode": "USDC",
    "decimals": 6,
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "estimatedFees": {
    "totalFeeBps": 50,
    "totalFeeAmountAtomic": "50000"
  },
  "paymentSource": {
    "id": "wallet_123",
    "type": "vault",
    "chainId": 8453,
    "assetCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "address": "0x1111111111111111111111111111111111111111"
  },
  "route": {
    "required": false,
    "sourceChainId": 8453,
    "destinationChainId": 8453,
    "sourceAssetCode": "USDC",
    "destinationAssetCode": "USDC"
  },
  "fundingOptions": [
    {
      "type": "vault",
      "available": true,
      "executionMode": "external_transaction"
    },
    {
      "type": "vault",
      "available": false,
      "executionMode": "managed_authorization",
      "unavailableReason": "vault_not_active"
    }
  ],
  "nextAction": {
    "type": "transaction",
    "createPaymentEndpoint": "/v2/payments",
    "confirmPaymentEndpoint": "/v2/payments/{paymentId}/confirm"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

POST

payments

preview

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/payments/preview \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent": "send",
  "sender": {
    "accountId": "acct_sender"
  },
  "destination": {
    "type": "payment_handle",
    "paymentHandle": "alice@partner"
  },
  "paymentAmount": {
    "amount": "1.00",
    "assetCode": "USDC"
  }
}
'

{
  "sender": {
    "accountId": "acct_sender"
  },
  "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"
  },
  "destination": {
    "type": "crypto_wallet",
    "chainId": 8453,
    "address": "0x2222222222222222222222222222222222222222",
    "assetCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "estimatedSettlementAmount": {
    "amount": "10.00",
    "amountAtomic": "10000000",
    "assetType": "crypto",
    "assetCode": "USDC",
    "decimals": 6,
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "estimatedFees": {
    "totalFeeBps": 50,
    "totalFeeAmountAtomic": "50000"
  },
  "paymentSource": {
    "id": "wallet_123",
    "type": "vault",
    "chainId": 8453,
    "assetCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "address": "0x1111111111111111111111111111111111111111"
  },
  "route": {
    "required": false,
    "sourceChainId": 8453,
    "destinationChainId": 8453,
    "sourceAssetCode": "USDC",
    "destinationAssetCode": "USDC"
  },
  "fundingOptions": [
    {
      "type": "vault",
      "available": true,
      "executionMode": "external_transaction"
    },
    {
      "type": "vault",
      "available": false,
      "executionMode": "managed_authorization",
      "unavailableReason": "vault_not_active"
    }
  ],
  "nextAction": {
    "type": "transaction",
    "createPaymentEndpoint": "/v2/payments",
    "confirmPaymentEndpoint": "/v2/payments/{paymentId}/confirm"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

A read-only preview of the send Payment request (intent: send). It resolves the sender, destination, fee, available funding options and next action without creating a Payment. For a crypto send, proceed only when the selected payment source is available. An enabled Vault source can fund a deposit-address Routing order when route.required is true; confirm that Payment with its returned managed authorization. A connected-wallet send still requires a direct transfer. Receive Payments do not need a preview. See Sending payments.

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

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

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.

intent

string

required

Allowed value: "send"

sender

Stableyard account ID · object

required

Identify a UPA using either its Stableyard account ID or your own external user ID.

Stableyard account ID
External user ID

Show child attributes

destination

UPA account · object

required

Send to another UPA, a payment handle, or an external crypto wallet. External QR and bank rails use their dedicated request variants below.

UPA account
Payment handle
External crypto 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:deliver_exact

Allowed value: "deliver_exact"

mandateId

string

Optional active Vault mandate authorizing this outgoing occurrence. A mandate constrains Vault spending; it does not schedule recurring Payments.

Required string length: 1 - 64

Example:

"vault_mandate_123"

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

Canonical Payment preview

sender

object

required

Show child attributes

paymentAmount

object

required

Show child attributes

sourceAmount

object | null

required

Total sender debit in the source asset, including commercial fees added to the required routing input. Null when the route is unavailable and the source input cannot be quoted.

Show child attributes

destination

UPA account · object

required

Show child attributes

estimatedSettlementAmount

object

required

Show child attributes

estimatedFees

object

required

Show child attributes

paymentSource

object

required

Show child attributes

route

object

required

Show child attributes

fundingOptions

object[]

required

Show child attributes

nextAction

object

required

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Preview a send payment

Authorizations

Headers

Body

Response