> ## Documentation Index > Fetch the complete documentation index at: https://docs.payzah.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Refund a payment > Returns funds to a customer for a transaction that has already completed successfully. Refunds can only be issued against captured payments. Confirm the original transaction is `CAPTURED` using the payment status endpoint before calling this. A success response confirms the refund was **submitted**, not that it has settled. Confirm the final state with the payment status endpoint. Payzah does not deduplicate refund requests — guard against duplicate submissions on your side. ## OpenAPI ````yaml /openapi.yaml post /ws/paymentgateway/refund openapi: 3.1.0 info: title: Payzah Payment Gateway API version: 1.0.0 description: > Accept K-Net, VISA, MasterCard, and Apple Pay payments in Kuwait. Every endpoint is a `POST` request with a JSON body. Authenticate by sending your Base64-encoded private key in the `Authorization` header. **All requests must be made server-side.** Never expose your private key in client-side code, mobile app binaries, or public repositories. ## Testing from these docs The interactive console below is pointed at the **test environment only** (`https://development.payzah.net`). Requests you send from this page create real sandbox transactions, but no real money moves. Use your **test** API key and the [sandbox test cards](/guides/test-credentials). Production endpoints are deliberately excluded here — switch your base URL to production only from your own server code, once your integration is fully validated. contact: name: Payzah Support email: Info@payzah.com url: https://payzah.com x-logo: altText: Payzah servers: - url: https://development.payzah.net description: Test environment (sandbox) security: - PrivateKeyAuth: [] tags: - name: Payments description: Create payment sessions and check their outcome. - name: Refunds description: Return funds to a customer for a completed transaction. paths: /ws/paymentgateway/refund: post: tags: - Refunds summary: Refund a payment description: > Returns funds to a customer for a transaction that has already completed successfully. Refunds can only be issued against captured payments. Confirm the original transaction is `CAPTURED` using the payment status endpoint before calling this. A success response confirms the refund was **submitted**, not that it has settled. Confirm the final state with the payment status endpoint. Payzah does not deduplicate refund requests — guard against duplicate submissions on your side. operationId: refundPayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundRequest' examples: full: summary: Full refund value: trackid: '1000' refrence_code: '2021060819283746732378' amount: '70' refund_type: '1' message: This is the message why to refund the amount partial: summary: Partial refund value: trackid: '1000' refrence_code: '2021060819283746732378' amount: '25' refund_type: '2' message: Partial refund for one returned item responses: '200': description: > Always returned with HTTP 200. Check the `status` field — a `200` with `status: false` means nothing was refunded. content: application/json: schema: oneOf: - $ref: '#/components/schemas/RefundSuccess' - $ref: '#/components/schemas/ErrorResponse' examples: success: summary: Refund submitted value: status: true message: Refund request is submited successfully code: 10012 error: summary: No matching transaction value: status: false message: No Record found for the provided details code: 10012 components: schemas: RefundRequest: type: object required: - trackid - refrence_code - amount - refund_type - message properties: trackid: type: string description: Merchant Track ID used during the original payment transaction. example: '1000' refrence_code: type: string description: > Payzah Reference Code from the successful payment — the `PaymentID` from initialization, or `payzahRefrenceCode` from the status response. Note the spelling: the field is `refrence_code`, not `reference_code`. example: '2021060819283746732378' amount: type: string description: > Amount to refund. For a full refund, the original transaction amount. For a partial refund, the portion to return. Must not exceed the captured amount. example: '70' refund_type: type: string enum: - '1' - '2' description: '`1` = Full Refund, `2` = Partial Refund.' example: '1' message: type: string description: >- Reason for the refund. Stored against the transaction for reconciliation and support. example: This is the message why to refund the amount RefundSuccess: type: object properties: status: type: boolean const: true description: '`true` when the refund request was submitted successfully.' example: true message: type: string example: Refund request is submited successfully code: type: integer example: 10012 ErrorResponse: type: object properties: status: type: boolean const: false description: '`false` when the request failed. Always check this field.' example: false message: type: string description: Human-readable description of the error. example: No Record found for the provided details code: description: > Numeric error code. See the Response Codes reference for the full list of codes 10000–10015. Commonly returned values: | Code | Meaning | | --- | --- | | `10001` | `trackid` contains invalid characters | | `10002` | `trackid` missing | | `10003` | `amount` malformed | | `10004` | `amount` missing | | `10005` | `success_url` missing | | `10006` | `error_url` missing | | `10012` | No record found for the provided details | | `10013` | Request body empty or not JSON | | `10014` | Invalid Authorization token | | `10015` | Account not permitted to use Credit Card direct integration | oneOf: - type: string - type: integer example: 10012 securitySchemes: PrivateKeyAuth: type: apiKey in: header name: Authorization description: > Your private key, Base64-encoded. Encode the key before sending it — for example `base64_encode($privateKey)` in PHP or `Buffer.from(privateKey).toString('base64')` in Node.js. Paste the **already-encoded** value here when testing from these docs. **Use your test key here.** This console only calls the sandbox environment, so a production key will not authenticate. ````