Create a payment for the client account

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client/me/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "intent": "receive",
  "amountMode": "collect_exact",
  "paymentAmount": {
    "amount": "50.00",
    "assetType": "crypto",
    "assetCode": "USDC",
    "chainId": 8453,
    "tokenAddress": "0x1111111111111111111111111111111111111111"
  },
  "settlement": {
    "settlementDestinationId": "settlementdestination_123"
  },
  "description": "Example payment",
  "externalReference": "example",
  "expiresInSeconds": 600,
  "metadata": {}
}
'

{
  "payment": {
    "id": "payment_123",
    "apiVersion": "2026-09-09",
    "intent": "receive",
    "amountMode": "collect_exact",
    "status": "requires_payment_method",
    "offrampStatus": null,
    "stage": null,
    "operationalState": "normal",
    "operationalReasonCode": null,
    "operationalUpdatedAt": null,
    "statusVersion": 1,
    "paymentAmount": {
      "amount": "50.00",
      "amountAtomic": "50000000",
      "assetType": "crypto",
      "assetCode": "USDC",
      "decimals": 6,
      "chainId": 8453,
      "tokenAddress": "0x1111111111111111111111111111111111111111"
    },
    "sourceAmount": {
      "amount": "50.00",
      "amountAtomic": "50000000",
      "assetType": "crypto",
      "assetCode": "USDC",
      "decimals": 6,
      "chainId": 8453,
      "tokenAddress": "0x1111111111111111111111111111111111111111"
    },
    "participants": [
      {
        "role": "sender",
        "accountId": "acct_123"
      }
    ],
    "recipientDisplay": {
      "displayName": "Example account",
      "logoUrl": null
    },
    "destination": {
      "type": "upa",
      "accountId": "acct_123"
    },
    "settlement": {
      "type": "settlement_destination",
      "settlementDestinationId": null,
      "destinationType": "example",
      "destinationAddress": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "assetCode": "USDC",
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "decimals": 0
    },
    "fees": {
      "version": null,
      "pricingStatus": "quote_pending",
      "platformFeeBps": 0,
      "partnerFeeBps": 0,
      "platformFeeAmountAtomic": null,
      "partnerFeeAmountAtomic": null,
      "merchantNetAmountAtomic": null
    },
    "funding": {
      "mode": "escrow",
      "required": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "providerPrincipal": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "providerFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "platformFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "partnerFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "totalFees": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "exchangeRate": {
        "rate": "1000000",
        "baseAssetCode": "USDC",
        "quoteAssetCode": "USDC"
      },
      "quoteExpiresAt": null,
      "depositAddress": {
        "address": "0x1111111111111111111111111111111111111111",
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111",
        "assetCode": "USDC",
        "decimals": 0,
        "amount": "1000000",
        "amountAtomic": "1000000"
      }
    },
    "externalReference": null,
    "description": null,
    "metadata": {},
    "expiresAt": null,
    "acceptedAt": null,
    "succeededAt": null,
    "cancelledAt": null,
    "failure": {
      "code": null,
      "message": null
    },
    "refundSummary": {
      "status": "none",
      "count": 0,
      "requestedAmountAtomic": "1000000",
      "confirmedAmountAtomic": "1000000"
    },
    "incidentRecoverySummary": {
      "count": 0,
      "pendingCount": 0,
      "confirmedCount": 0,
      "failedCount": 0,
      "requiresInterventionCount": 0,
      "requestedAmountAtomic": "1000000",
      "confirmedAmountAtomic": "1000000"
    },
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "checkout": {
    "paymentUrl": "https://example.com",
    "clientSecret": "examplexxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiresAt": "2026-08-28T10:00:00.000Z",
    "returnUrl": null
  },
  "nextAction": {
    "id": "resource_123",
    "type": "transaction",
    "expiresAt": null,
    "depositInstructions": {
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "assetCode": "USDC",
      "decimals": 0,
      "amount": "1000000",
      "amountAtomic": "1000000"
    }
  }
}

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

client

payments

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client/me/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "intent": "receive",
  "amountMode": "collect_exact",
  "paymentAmount": {
    "amount": "50.00",
    "assetType": "crypto",
    "assetCode": "USDC",
    "chainId": 8453,
    "tokenAddress": "0x1111111111111111111111111111111111111111"
  },
  "settlement": {
    "settlementDestinationId": "settlementdestination_123"
  },
  "description": "Example payment",
  "externalReference": "example",
  "expiresInSeconds": 600,
  "metadata": {}
}
'

{
  "payment": {
    "id": "payment_123",
    "apiVersion": "2026-09-09",
    "intent": "receive",
    "amountMode": "collect_exact",
    "status": "requires_payment_method",
    "offrampStatus": null,
    "stage": null,
    "operationalState": "normal",
    "operationalReasonCode": null,
    "operationalUpdatedAt": null,
    "statusVersion": 1,
    "paymentAmount": {
      "amount": "50.00",
      "amountAtomic": "50000000",
      "assetType": "crypto",
      "assetCode": "USDC",
      "decimals": 6,
      "chainId": 8453,
      "tokenAddress": "0x1111111111111111111111111111111111111111"
    },
    "sourceAmount": {
      "amount": "50.00",
      "amountAtomic": "50000000",
      "assetType": "crypto",
      "assetCode": "USDC",
      "decimals": 6,
      "chainId": 8453,
      "tokenAddress": "0x1111111111111111111111111111111111111111"
    },
    "participants": [
      {
        "role": "sender",
        "accountId": "acct_123"
      }
    ],
    "recipientDisplay": {
      "displayName": "Example account",
      "logoUrl": null
    },
    "destination": {
      "type": "upa",
      "accountId": "acct_123"
    },
    "settlement": {
      "type": "settlement_destination",
      "settlementDestinationId": null,
      "destinationType": "example",
      "destinationAddress": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "assetCode": "USDC",
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "decimals": 0
    },
    "fees": {
      "version": null,
      "pricingStatus": "quote_pending",
      "platformFeeBps": 0,
      "partnerFeeBps": 0,
      "platformFeeAmountAtomic": null,
      "partnerFeeAmountAtomic": null,
      "merchantNetAmountAtomic": null
    },
    "funding": {
      "mode": "escrow",
      "required": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "providerPrincipal": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "providerFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "platformFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "partnerFee": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "totalFees": {
        "amount": "1000000",
        "amountAtomic": "1000000",
        "assetType": "crypto",
        "assetCode": "USDC",
        "decimals": 0,
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111"
      },
      "exchangeRate": {
        "rate": "1000000",
        "baseAssetCode": "USDC",
        "quoteAssetCode": "USDC"
      },
      "quoteExpiresAt": null,
      "depositAddress": {
        "address": "0x1111111111111111111111111111111111111111",
        "chainId": 1,
        "tokenAddress": "0x1111111111111111111111111111111111111111",
        "assetCode": "USDC",
        "decimals": 0,
        "amount": "1000000",
        "amountAtomic": "1000000"
      }
    },
    "externalReference": null,
    "description": null,
    "metadata": {},
    "expiresAt": null,
    "acceptedAt": null,
    "succeededAt": null,
    "cancelledAt": null,
    "failure": {
      "code": null,
      "message": null
    },
    "refundSummary": {
      "status": "none",
      "count": 0,
      "requestedAmountAtomic": "1000000",
      "confirmedAmountAtomic": "1000000"
    },
    "incidentRecoverySummary": {
      "count": 0,
      "pendingCount": 0,
      "confirmedCount": 0,
      "failedCount": 0,
      "requiresInterventionCount": 0,
      "requestedAmountAtomic": "1000000",
      "confirmedAmountAtomic": "1000000"
    },
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "checkout": {
    "paymentUrl": "https://example.com",
    "clientSecret": "examplexxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiresAt": "2026-08-28T10:00:00.000Z",
    "returnUrl": null
  },
  "nextAction": {
    "id": "resource_123",
    "type": "transaction",
    "expiresAt": null,
    "depositInstructions": {
      "address": "0x1111111111111111111111111111111111111111",
      "chainId": 1,
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "assetCode": "USDC",
      "decimals": 0,
      "amount": "1000000",
      "amountAtomic": "1000000"
    }
  }
}

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

Use intent: receive for authenticated add-money or receive checkout, and intent: send for an outgoing payment. The account comes from the client bearer token, so the body cannot supply sender, recipient, accountId or externalUserId. The issuing app must have Payments enabled and the issuing credential must permit v2:payments. Idempotency-Key is required.

Authorizations

Authorization

string

header

required

Short-lived account-bound token returned by POST /v2/client/auth/exchange.

Headers

Idempotency-Key

string

required

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

Example:

"payment-request-001"

Body

application/json

Receive payment
Send payment

Creates a canonical receive or send Payment for the bearer token's existing account. The client token supplies recipient for receive and sender for send; account locators are rejected.

intent

string

required

Allowed value: "receive"

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

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

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

Create a payment for the client account

Authorizations

Headers

Body

Response