API reference

REST endpoints, request and response shapes, error envelope and versioning.

Not live yet — api.baynoy.com does not resolve, so the examples below will not run today. They describe the contract we are building to, and the shapes on this page may still change.

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