API 参考

REST 端点、请求与响应结构、错误封装与版本管理。

尚未上线 —— api.baynoy.com 无法解析,下面的示例目前无法运行。它们描述的是我们正在实现的接口约定,本页的结构仍可能调整。

Resources that exist today

Payments: GET/POST /v1/payments · GET /v1/payments/{id} · POST /v1/payments/{id}/refunds · GET /v1/payments/export. Catalog: /v1/catalog/products · /v1/catalog/links. Invoices: /v1/invoices and /v1/invoices/{id}/issue, /send, /paid, /void. Money held and out: GET /v1/balances · /v1/beneficiaries · /v1/payouts · /v1/statements · GET /v1/reports/summary. Cards: /v1/cards · /v1/cards/{id}/state. Crypto: GET /v1/crypto · /v1/crypto/addresses · /v1/crypto/withdrawals. Webhooks: /v1/developers/webhooks. Currency conversion: GET /v1/fx/currencies (which currencies the current rate source can convert now: { source, available, unavailable }) · GET /v1/fx/rates?from&to (indicative) · POST /v1/fx/quotes (locks a rate for 60 seconds: the live mid-market rate or a daily reference rate, plus 1% between major currencies — USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD, SEK, NOK — or 2% when either side is any other currency) · POST /v1/fx/conversions (spends a quote; Idempotency-Key) · GET /v1/fx/conversions. Subscriptions: GET /v1/subscriptions · GET /v1/subscriptions/plans · POST /v1/subscriptions/{id}/cancel. Disputes: GET /v1/disputes · GET /v1/disputes/{id} · POST /v1/disputes/{id}/evidence · POST /v1/disputes/{id}/accept.

The error envelope

Every non-2xx response carries {"error": {"code", "message", "details?"}}. Codes are stable identifiers you can branch on; messages are human-readable and may change.

Idempotency

Money-moving POSTs take an Idempotency-Key header. The same key with the same body safely returns the first result; the same key with a different body is a conflict.

cURL
curl https://api.baynoy.com/v1/payouts \
  -H "Authorization: Bearer bk_test_..." \
  -H "Idempotency-Key: 7c1f0b6e-..." \
  -H "Baynoy-Signature: kid=key_...,ts=1794300000,nonce=8f2c...,v1=<hex>" \
  -H "Content-Type: application/json" \
  -d '{"beneficiaryId": "ben_123", "amountMinor": "250000", "assetKey": "fiat:EUR"}'

# same key + same body  -> the original result, no second payout
# same key + other body -> 409 conflict