Select a payment method

Create a method attempt for a checkout Payment without changing the Payment.

POST /v2/public/payments/{paymentId}/options

cURL

direct-or-routing-crypto-option

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

200

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

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 from the same list with a receiptEmail (plus optional fiatCurrency and returnUrl). Hosted-on-ramp-only fields are rejected for crypto methods.

Routing options are quoted when you select them. 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

Retry key. Reuse a key only with the identical request; different input returns a conflict.

Example:

"request-key-001"

Path Parameters

paymentId · string · required

The payment_* ID returned when the Payment was created.

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

200

application/json

Selected payment option

previousSelectedOptionId · string | null · required

Example:

"pay_option_previous"

option · object · required

Show child attributes