Select a payment method

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "paymentMethodId": "crypto.direct"
}
'

{
  "previousSelectedOptionId": "pay_option_previous",
  "option": {
    "id": "pay_option_123",
    "providerCode": "direct",
    "paymentMethodType": "crypto",
    "paymentMethodId": "crypto.direct",
    "type": "crypto",
    "displayName": "Arbitrum USDC",
    "status": "creating",
    "selectionStatus": "selected",
    "requiredAmountAtomic": "1000000",
    "paidAmountAtomic": "1000000",
    "remainingAmountAtomic": "1000000",
    "isTerminal": true,
    "confirmationMode": "provider_webhook",
    "transactionSubmissions": [
      {
        "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "purpose": "destination_escrow",
        "status": "submitted",
        "failureCode": null,
        "submittedAt": "2026-08-28T10:00:00.000Z",
        "verifiedAt": null
      }
    ],
    "sourceAmount": {
      "amountAtomic": "10000000",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "destinationAmount": {
      "amountAtomic": "10000000",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "payerAmount": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "recipientAmount": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "providerFee": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "execution": {
      "type": "deposit_address",
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "assetSymbol": "USDC",
      "amountAtomic": "1000000",
      "decimals": 0,
      "expiresAt": null
    },
    "expiresAt": null,
    "refreshable": true,
    "feeAmountAtomic": null,
    "actionExpiresAt": null,
    "quoteExpiresAt": null,
    "orderExpiresAt": null,
    "receipts": [
      {
        "chainId": 1,
        "txHash": "example",
        "logIndex": null,
        "amountAtomic": "1000000",
        "confirmedAt": "2026-08-28T10:00:00.000Z"
      }
    ]
  }
}

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

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

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

POST

public

payments

{paymentId}

options

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "paymentMethodId": "crypto.direct"
}
'

{
  "previousSelectedOptionId": "pay_option_previous",
  "option": {
    "id": "pay_option_123",
    "providerCode": "direct",
    "paymentMethodType": "crypto",
    "paymentMethodId": "crypto.direct",
    "type": "crypto",
    "displayName": "Arbitrum USDC",
    "status": "creating",
    "selectionStatus": "selected",
    "requiredAmountAtomic": "1000000",
    "paidAmountAtomic": "1000000",
    "remainingAmountAtomic": "1000000",
    "isTerminal": true,
    "confirmationMode": "provider_webhook",
    "transactionSubmissions": [
      {
        "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "purpose": "destination_escrow",
        "status": "submitted",
        "failureCode": null,
        "submittedAt": "2026-08-28T10:00:00.000Z",
        "verifiedAt": null
      }
    ],
    "sourceAmount": {
      "amountAtomic": "10000000",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "destinationAmount": {
      "amountAtomic": "10000000",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "payerAmount": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "recipientAmount": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "providerFee": {
      "amountAtomic": "10000000",
      "amountDecimal": "10",
      "assetSymbol": "USDC",
      "decimals": 6,
      "chainId": 42161,
      "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "execution": {
      "type": "deposit_address",
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "assetSymbol": "USDC",
      "amountAtomic": "1000000",
      "decimals": 0,
      "expiresAt": null
    },
    "expiresAt": null,
    "refreshable": true,
    "feeAmountAtomic": null,
    "actionExpiresAt": null,
    "quoteExpiresAt": null,
    "orderExpiresAt": null,
    "receipts": [
      {
        "chainId": 1,
        "txHash": "example",
        "logIndex": null,
        "amountAtomic": "1000000",
        "confirmedAt": "2026-08-28T10:00:00.000Z"
      }
    ]
  }
}

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

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

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

Creates one method attempt without changing the Payment’s obligation, recipient, settlement or commercial fee snapshot. Pass a Direct or Routing paymentMethodId from List payment methods, or the hosted on-ramp method with a receiptEmail (plus optional fiatCurrency and returnUrl). Hosted-on-ramp-only fields are rejected for crypto methods. Routing quotes are fetched only after this selection and are immediately converted into a funding order. Idempotency-Key is required.

Authorizations

Authorization

string

header

required

Short-lived browser capability for exactly one payment_* resource. Never place it in a URL.

Headers

Idempotency-Key

string

required

Use this for retry-safe payment operations from your backend.

Example:

"payment-request-001"

Path Parameters

paymentId

string

required

Canonical payment_* identifier. Internal execution identifiers are never accepted by Partner Payment routes.

Pattern: ^payment_[A-Za-z0-9_-]+$

Example:

"payment_123"

Body

application/json

Direct or Routing crypto option
Hosted on-ramp option

paymentMethodId

string

required

Use a direct or Routing id returned by payment-method discovery. Hosted-on-ramp-only fields are rejected.

Maximum string length: 160

Pattern: ^(crypto\.direct|routing\.[a-z0-9_.:-]+)$

Example:

"crypto.direct"

Response

Selected payment option

previousSelectedOptionId

string | null

required

Example:

"pay_option_previous"

option

object

required

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Select a payment method

Authorizations

Headers

Path Parameters

Body

Response