Refund a payment

Refund a collected direct receive Payment to the verified payer.

POST /v2/payments/{paymentId}/refunds

cURL

decimal-refund-amount

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/payments/{paymentId}/refunds \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": "5.00",
  "reasonCode": "customer_request",
  "reason": "Requested by partner"
}
'

202

{
  "refund": {
    "id": "refund_01JY8Q3R5T7V9W2X4Z6AB8CDEF",
    "paymentId": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
    "status": "created",
    "amount": "5.00",
    "amountAtomic": "5000000",
    "assetCode": "USDC",
    "chainId": 42161,
    "transactionHash": null,
    "reasonCode": "customer_request",
    "reason": "Customer requested a partial refund",
    "createdAt": "2026-08-28T11:00:00.000Z",
    "broadcastAt": null,
    "confirmedAt": null,
    "failure": null
  }
}

Refund exactly one amount, as a decimal amount or an amountAtomic (never both), with a reasonCode (customer_request or operational) and a reason. Stableyard derives the destination from independently verified payer evidence; you cannot choose or override it.

Only direct crypto receive Payments can be refunded here. For on-ramp-funded or multi-payer Payments, or a failed payout, contact Stableyard. Idempotency-Key is required; reuse it only with the identical refund request. The refund is returned with 202 Accepted.

See Reconciliation for telling a refund from a recovery.

Authorizations

Authorization · string · header · required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Idempotency-Key · string · required

Required retry key. Reuse only with the identical refund request.

Example:

"request-key-001"

Stableyard-Version · enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options: 2026-09-09

Path Parameters

paymentId · string · required

The payment_* ID returned when the Payment was created.

Pattern: ^payment_[A-Za-z0-9_-]+$

Example:

"payment_123"

Body

application/json

Create refund request

Create refund request

Refund exactly one decimal or atomic amount from a supported accepted direct receive Payment. Stableyard derives the payer destination from verified receipt evidence. Failed external payouts are returned by Stableyard and cannot be requested through this body.

amount · string · required

Required string length: 1 - 100

Pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$

Example:

"5.00"

reasonCode · enum<string> · required

Available options: customer_request, operational

reason · string · required

Required string length: 1 - 500

amountAtomic · string

Required string length: 1 - 80

Pattern: ^[1-9][0-9]*$

Example:

"5000000"

Response

202

application/json

Refund accepted

refund · object · required

Show child attributes