> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve refund > Retrieve a refund by the merchant-provided `refund_id`. The response includes the current status, on-chain transaction hash, and failure reason when applicable. ## OpenAPI ````yaml /en/api/refund-openapi.json get /api/v1/refunds/{refund_id} openapi: 3.1.0 info: title: StablePay Refund API version: '2026-04-14' summary: 'StablePay refund endpoints: create, retrieve, and cancel refunds.' description: >- OpenAPI specification for the StablePay refund endpoints. ## Authentication Every endpoint requires both a **Bearer API Key** and signature headers: - `Authorization: Bearer {api_key}` - `X-StablePay-Timestamp`: Unix timestamp in seconds - `X-StablePay-Nonce`: Random string (UUID recommended) used for replay protection - `X-StablePay-Signature`: HMAC-SHA256 signature ## Signing rules The signing string is `{timestamp}.{nonce}.{requestBody}`: - `POST` requests: `requestBody` is the raw JSON payload string - `GET` requests: `requestBody` is the empty string Compute HMAC-SHA256 of the signing string using the merchant API Secret, and use the lowercase hex digest as `X-StablePay-Signature`. ## Amount precision All amount fields are expressed in the smallest unit of the currency. USDT and USDC both use 6 decimal places (i.e., 1 USDT = 1,000,000). servers: - url: https://api.stablepay.co description: Production security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: Refunds description: Create, retrieve, and cancel refunds. paths: /api/v1/refunds/{refund_id}: get: tags: - Refunds summary: Retrieve refund description: >- Retrieve a refund by the merchant-provided `refund_id`. The response includes the current status, on-chain transaction hash, and failure reason when applicable. operationId: getRefund parameters: - $ref: '#/components/parameters/RefundId' - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' responses: '200': description: Retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/RefundDetail' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Refund does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: RefundId: name: refund_id in: path required: true description: Unique refund ID supplied by the merchant when the refund was created. schema: type: string example: refund_20250101001 XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix timestamp in seconds. Must be within 5 minutes of server time. schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. schema: type: string example: a1b2c3d4e5f6... schemas: RefundDetail: type: object description: Refund details. properties: refund_id: type: string description: Merchant-supplied refund ID. payment_id: type: string description: Payment identifier returned for subscription refund scenarios. order_id: type: string description: Merchant order ID, returned for normal payment refunds. amount: type: integer format: int64 description: Refund amount in minor units. currency: type: string enum: - USDT - USDC description: Refund currency. status: $ref: '#/components/schemas/RefundStatus' reason: type: string enum: - requested_by_customer - duplicate - fraudulent - expired_uncaptured description: Refund reason. description: type: string description: Refund description. created_at: type: integer format: int64 description: Refund creation time, Unix seconds. metadata: type: object additionalProperties: true description: Merchant metadata. failure_reason: type: string enum: - charge_already_refunded - insufficient_funds - expired_or_canceled_card - declined_by_bank - lost_or_stolen_card - unknown description: Failure reason, returned when the refund failed. transaction_hash: type: string description: On-chain transaction hash, returned after success. receipt_number: type: string description: Refund receipt number. processed_at: type: integer format: int64 description: >- Processing completion time, Unix seconds. Returned after success, failure, or cancellation. ErrorResponse: type: object description: Error response. properties: error: type: object properties: type: type: string description: Error type. code: type: string description: Error code. message: type: string description: Error message. param: type: string description: Related parameter. doc_url: type: string description: Error documentation URL. decline_code: type: string description: Decline code. request_log_url: type: string description: Request log URL. charge: type: string description: Related payment ID. request_id: type: string description: Request ID. timestamp: type: integer format: int64 description: Error timestamp in Unix seconds. RefundStatus: type: string enum: - pending - processing - completed - failed - canceled description: >- Refund status. Newly created refunds usually return `processing` in the current implementation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key, for example `Bearer sk_live_xxx`. stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix timestamp in seconds. Must be within 5 minutes of server time. stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. ````