> ## Documentation Index > Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt > Use this file to discover all available pages before exploring further. # Refund a payment > Refund a collected direct receive Payment to the verified payer. 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](/payments/reconciliation) for telling a refund from a recovery. ## OpenAPI ````yaml openapi.json POST /v2/payments/{paymentId}/refunds openapi: 3.1.0 info: title: Stableyard Partner API version: 2.0.0-staging x-stableyard-api-version: '2026-09-09' x-stableyard-supported-api-versions: - '2026-09-09' summary: Backend API for UPAs, Payments, activity, and optional financial products. description: > Use this API from a trusted partner backend with an app ID and app secret. ## Recommended integration 1. Call `GET /v2/partners/config` to verify credentials and discover enabled capabilities. 2. Create a UPA only when your product needs a persistent Stableyard account. 3. Create a receive or send Payment with `POST /v2/payments`. 4. Redirect a payer to the returned `paymentUrl` or pass the Payment credentials to an official Stableyard interface SDK. 5. Process signed webhooks and fetch the Payment by ID for reconciliation. Checkout execution and account-bound browser endpoints are intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner servers: - url: https://prod-api.stableyard.fi description: Production - url: https://staging-api-v2.stableyard.fi description: Staging - url: http://localhost:3001 description: Local security: [] tags: - name: Authentication x-displayName: API authentication description: Verify your app ID and app secret before calling UPA APIs. - name: Accounts x-displayName: UPA Accounts description: Create Universal Payment Accounts and manage account settings. - name: Deposit Addresses description: Create reusable receive addresses and verify inbound deposits. - name: Identity & KYC description: >- Verify the UPA email and run provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac controlled stablecoin vaults and manage policy updates for accounts. - name: Payments description: >- Create escrow-first payments, issue partner-authenticated send instructions or executions, power public checkout, and reconcile collection through final account settlement. - name: Balances & Transactions description: >- Read Stableyard-posted financial activity. Balances are ledger projections of activity Stableyard processed; they are not live balances of externally controlled wallets. paths: /v2/payments/{paymentId}/refunds: post: tags: - Payments summary: Create refund description: >- Creates a refund against a collected direct receive Payment. Stableyard derives the destination from independently verified payer evidence; callers cannot choose or override it. Provider-funded and multi-payer Payments require the provider or manual recovery workflow. operationId: createPaymentRefund parameters: - name: paymentId in: path required: true schema: type: string pattern: ^payment_[A-Za-z0-9_-]+$ example: payment_123 description: >- Canonical `payment_*` identifier. Internal execution identifiers are never accepted by Partner Payment routes. - name: Idempotency-Key in: header required: true schema: type: string example: payment-request-001 description: Required retry key. Reuse only with the identical refund request. - name: Stableyard-Version in: header required: false schema: type: string enum: - '2026-09-09' description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CanonicalCreateRefundRequest' examples: decimal-refund-amount: summary: Decimal refund amount value: amount: '5.00' reasonCode: customer_request reason: Requested by partner atomic-refund-amount: summary: Atomic refund amount value: amountAtomic: '5000000' reasonCode: customer_request reason: Requested by partner responses: '202': description: Refund accepted headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/CanonicalRefundResponse' examples: refundCreated: summary: Refund queued for verified payer destination value: 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 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '424': $ref: '#/components/responses/FailedDependency' '429': $ref: '#/components/responses/TooManyRequests' security: - partnerBasicAuth: [] components: schemas: CanonicalCreateRefundRequest: title: Create refund request description: >- 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. type: object additionalProperties: false required: - reasonCode - reason properties: amount: type: string minLength: 1 maxLength: 100 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$ example: '5.00' amountAtomic: type: string minLength: 1 maxLength: 80 pattern: ^[1-9][0-9]*$ example: '5000000' reasonCode: type: string enum: - customer_request - operational reason: type: string minLength: 1 maxLength: 500 oneOf: - title: Decimal refund amount required: - amount not: required: - amountAtomic - title: Atomic refund amount required: - amountAtomic not: required: - amount CanonicalRefundResponse: type: object additionalProperties: false required: - refund properties: refund: $ref: '#/components/schemas/CanonicalRefund' CanonicalRefund: type: object additionalProperties: false required: - id - paymentId - status - amount - amountAtomic - assetCode - chainId - transactionHash - reasonCode - reason - createdAt - broadcastAt - confirmedAt - failure properties: id: type: string pattern: ^refund_ paymentId: type: string pattern: ^payment_ status: type: string enum: - created - pending_approval - signing - retry_wait - broadcast - confirmed - failed - requires_intervention - cancelled amount: type: string minLength: 1 maxLength: 100 amountAtomic: type: string minLength: 1 maxLength: 80 pattern: ^[1-9][0-9]*$ assetCode: type: string chainId: type: integer minimum: 1 transactionHash: type: - string - 'null' reasonCode: type: string enum: - duplicate_payment - customer_request - late_payment - overpayment - underpayment - operational - offramp_provider_terminal_failure reason: type: string createdAt: type: string format: date-time broadcastAt: type: - string - 'null' format: date-time confirmedAt: type: - string - 'null' format: date-time failure: oneOf: - title: Failure details type: object additionalProperties: false required: - code - message properties: code: type: - string - 'null' message: type: - string - 'null' - title: No failure type: 'null' ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string minLength: 1 maxLength: 128 example: bad_request message: type: string minLength: 1 maxLength: 1000 example: The request is invalid details: {} responses: BadRequest: description: Bad request headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: BadRequest response value: error: code: bad_request message: The request is invalid details: example Unauthorized: description: Unauthorized headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Unauthorized response value: error: code: bad_request message: The request is invalid details: example Forbidden: description: The app secret does not include the required scope headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Forbidden response value: error: code: bad_request message: The request is invalid details: example NotFound: description: Not found headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: NotFound response value: error: code: bad_request message: The request is invalid details: example Conflict: description: Conflict headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Conflict response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' Retry-After: description: Seconds until the caller should retry. schema: type: integer minimum: 1 RateLimit-Limit: description: Quota for the most constrained policy. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requests remaining in that policy window. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until that policy window resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example securitySchemes: partnerBasicAuth: type: http scheme: basic description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.