> ## Documentation Index > Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees. > Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown. > OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis. > MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries. > Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix. > Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests. # Request Transaction Refund > Requests a refund (full or partial) for a completed transaction. Verifies and validates that the requested refund amount does not exceed the remaining refundable balance of the original transaction. ## OpenAPI ````yaml /api/merchant_api.yaml post /refunds openapi: 3.1.0 info: title: OwnPay Merchant API description: > The OwnPay Merchant API enables merchants to programmatically interface with their white-labeled payment gateway. It exposes endpoints to initiate payments (creating payment intents), query transaction statuses, issue full or partial refunds, manage customer profiles securely in compliance with GDPR and OWASP, generate and revoke API keys, and test/audit webhook delivery attempts. ### Authentication Authentication is performed via HTTP Bearer token in the `Authorization` header. ```http Authorization: Bearer your_api_key_here ``` API keys carry specific privilege scopes (e.g., `read`, `write`, `admin`). Some administrative operations (like listing/generating API keys) require **both** `write` and `admin` scopes, as well as passing a valid platform super-administrator's email address in the `X-Super-Admin-Email` header for safety. version: 1.0.0 servers: - url: https://{brand_domain}/api/v1 description: Sandbox or Production white-labeled brand gateway API server. variables: brand_domain: default: ownpay.org description: The custom domain configured for your white-labeled brand. security: - BearerAuth: [] paths: /refunds: post: summary: Request Transaction Refund description: > Requests a refund (full or partial) for a completed transaction. Verifies and validates that the requested refund amount does not exceed the remaining refundable balance of the original transaction. operationId: requestRefund requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRefundRequest' responses: '201': description: Refund requested and processed successfully. content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: >- Invalid refund parameters (e.g., refund amount exceeds transaction total, or transaction status is not refundable). content: application/json: schema: $ref: '#/components/schemas/ApiSingleErrorResponse' '404': description: Original transaction not found under the brand scope. content: application/json: schema: $ref: '#/components/schemas/ApiSingleErrorResponse' '422': description: Missing required fields (e.g., trx_id/transaction_id is empty). content: application/json: schema: $ref: '#/components/schemas/ApiSingleErrorResponse' '500': description: Internal processing failure during refund execution. content: application/json: schema: $ref: '#/components/schemas/ApiSingleErrorResponse' components: schemas: CreateRefundRequest: type: object required: - trx_id properties: trx_id: type: string description: >- OwnPay transaction reference code (e.g. `OP-12345`) or gateway transaction ID. example: OP-481029304 transaction_id: type: integer description: Alternative key using the internal transaction integer ID. example: 45 amount: type: string description: >- Optional positive numeric string to issue a partial refund. If omitted, a full refund is requested. example: '150.00' reason: type: string description: Refund reason justification. example: Customer requested return RefundResponse: type: object properties: success: type: boolean example: true data: type: object properties: id: type: integer nullable: true example: 12 uuid: type: string nullable: true format: uuid example: d2f44778-d421-4f1e-9271-70bf8e3b123a transaction_id: type: integer nullable: true example: 45 trx_id: type: string nullable: true example: OP-481029304 gateway_trx_id: type: string nullable: true example: A8K9D2J3S amount: type: string example: '150.00' reason: type: string nullable: true example: Customer requested return status: type: string example: completed processed_at: type: string format: date-time nullable: true example: '2026-06-23T14:20:00Z' created_at: type: string format: date-time example: '2026-06-23T14:19:55Z' ApiSingleErrorResponse: type: object properties: success: type: boolean example: false error: type: string example: Payment not found errors: type: array items: type: object properties: code: type: string example: PAYMENT_NOT_FOUND message: type: string example: Payment not found field: type: string nullable: true example: null request_id: type: string example: 8f5a2e9b0c7d4e5f securitySchemes: BearerAuth: type: http scheme: bearer description: Provide the Bearer API Key generated for your brand. ```` ## Related topics - [Transactions - View Payments, Refunds, and Gateway Status](/docs/user-guide/payments/transactions.md) - [Retrieve Refund](/docs/api-reference/retrieve-refund.md) - [List Refunds](/docs/api-reference/list-refunds.md) - [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md) - [Retrieve Transaction](/docs/api-reference/retrieve-transaction.md)