> ## Documentation Index > Fetch the complete documentation index at: https://docs.tagada.io/llms.txt > Use this file to discover all available pages before exploring further. # Refund a payment ## OpenAPI ````yaml /payments-api/openapi.json post /v1/refunds openapi: 3.1.0 info: title: TagadaPay Payments API version: '2026-11-01' servers: - url: https://api.tagada.io security: [] paths: /v1/refunds: post: tags: - refunds summary: Refund a payment operationId: refunds.create parameters: - in: header name: payments-account required: false schema: type: string - in: header name: payments-version required: false schema: enum: - '2026-11-01' type: string - in: header name: idempotency-key required: true schema: maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRefund' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Refund' description: Refund. '400': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: >- parameter_invalid, parameter_missing, amount_out_of_range, amount_exceeds_refundable, refund_not_supported '401': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: authentication_required '403': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: permission_denied '404': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: resource_not_found '409': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: >- idempotency_key_reused, idempotency_key_in_progress, payment_not_refundable, dispute_open '429': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: rate_limited '500': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: internal_error '501': content: application/json: schema: $ref: '#/components/schemas/RefundApiError' description: not_implemented security: - bearerAuth: [] components: schemas: CreateRefund: additionalProperties: false properties: amount: type: number metadata: additionalProperties: type: string type: object payment: pattern: ^pay_[a-f0-9]{12}$ type: string reason: default: requested enum: - requested - duplicate - fraudulent type: string required: - payment type: object Refund: additionalProperties: false properties: amount: type: number created_at: format: date-time type: string currency: enum: - AED - AFN - ALL - AMD - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - UYI - UYU - UYW - UZS - VED - VES - VND - VUV - WST - XAD - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMW - ZWG type: string id: pattern: ^rfd_[0-9a-hjkmnp-tv-z]{26}$ type: string last_outcome: additionalProperties: false properties: advice_code: type: - string - 'null' bank_reached: type: boolean category: type: string raw_code: type: - string - 'null' raw_message: type: - string - 'null' reason: type: string required: - category - reason - raw_code - raw_message - bank_reached - advice_code type: - object - 'null' metadata: additionalProperties: type: string type: object object: enum: - refund type: string origin: enum: - api - processor type: string payment: pattern: ^pay_[a-f0-9]{12}$ type: string processor_reference: type: - string - 'null' reason: enum: - requested - duplicate - fraudulent - compensation type: string status: enum: - in_flight - pending - succeeded - failed - unknown type: string required: - id - object - payment - amount - currency - status - reason - origin - processor_reference - last_outcome - created_at - metadata type: object RefundApiError: properties: error: properties: code: $ref: '#/components/schemas/RefundErrorCode' details: additionalProperties: {} type: object message: type: string param: type: - string - 'null' request_id: type: string type: enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - unavailable_error type: string required: - type - code - message - param - request_id type: object required: - error type: object RefundErrorCode: enum: - amount_exceeds_refundable - amount_out_of_range - authentication_required - dispute_open - idempotency_key_in_progress - idempotency_key_reused - internal_error - not_implemented - parameter_invalid - parameter_missing - payment_not_refundable - permission_denied - rate_limited - refund_not_supported - resource_not_found type: string x-extensible-enum: - amount_exceeds_refundable - amount_out_of_range - authentication_required - dispute_open - idempotency_key_in_progress - idempotency_key_reused - internal_error - not_implemented - parameter_invalid - parameter_missing - payment_not_refundable - permission_denied - rate_limited - refund_not_supported - resource_not_found securitySchemes: bearerAuth: description: >- Secret, platform or publishable API key. Platform keys require Payments-Account. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.