Create a payment for the client account

Create a receive or send Payment for the account fixed by the client token.

POST /v2/client/me/payments

cURL

receive-payment

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

200

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

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

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

Example:

"request-key-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

200

application/json

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.

Action required

Start account KYC

Verify UPA email

Complete hosted compliance

Waiting for review

Contact support

No action required (type none)

Show child attributes

checkout · object

Show child attributes