Refund a payment

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

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

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

POST

payments

{paymentId}

refunds

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

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

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

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. Provider-funded and multi-payer Payments go through the provider or manual recovery workflow instead, and failed external-payout treasury recovery is an operations workflow that this endpoint cannot request. 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:

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

Canonical payment_* identifier. Internal execution identifiers are never accepted by Partner Payment routes.

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-payout treasury recovery is an operations workflow 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

Refund accepted

refund

object

required

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Authorizations

Headers

Path Parameters

Body

Response