baynoy

API reference

Refunds

Reverse part or all of a previous payment back to the customer's original payment method. Refunds settle on the same rail as the charge, so reconciliation lines up automatically.

Issue a refund

POST/v1/refundsscope: refunds:write

Use an Idempotency-Key on every refund call — you never want to accidentally double-refund. The amount is in the same minor unit as the original payment (cents for USD/EUR/CHF, no decimal for JPY).

Body parameters

paymentIdrequired

string

UUID of the Payment to refund.
amountrequired

number

Refund amount in minor units. Cannot exceed the remaining refundable balance on the payment.
reason

string

Free-form, max 500 chars. Surfaced on the refund-issued email and dashboard timeline.
curl https://baynoy.com/api/v1/refunds \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: rfnd-2026-05-27-abc" \
  -d '{
    "paymentId": "8f7e6d5c-4b3a-2918-7654-3210fedcba98",
    "amount": 500,
    "reason": "Customer requested partial refund"
  }'
Response
{
  "ok": true,
  "data": {
    "id": "c4d5e6f7-8a9b-40c1-d2e3-f4a5b6c7d8e9",
    "paymentId": "8f7e6d5c-4b3a-2918-7654-3210fedcba98",
    "amount": "500",
    "currency": "CHF",
    "status": "succeeded",
    "reason": "Customer requested partial refund",
    "providerRef": "re_1NxYzA...",
    "createdAt": "2026-05-27T12:34:56.789Z"
  }
}

List refunds

GET/v1/refundsscope: refunds:read

Cursor-paginated, newest first.

Query parameters

cursor

string

Pagination cursor (bare UUID).
limit

number

1–100, default 20.
curl "https://baynoy.com/api/v1/refunds?limit=20" \
  -H "Authorization: Bearer sk_test_…"
Response
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "c4d5e6f7-8a9b-40c1-d2e3-f4a5b6c7d8e9",
        "amount": "500",
        "currency": "CHF",
        "status": "succeeded",
        "payment": { "id": "8f7e6d5c-4b3a-2918-7654-3210fedcba98", "amount": "2000", "currency": "CHF" },
        "createdAt": "2026-05-27T12:34:56.789Z"
      }
    ],
    "nextCursor": null,
    "hasMore": false
  }
}