> ## Documentation Index > Fetch the complete documentation index at: https://devdraft.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Refund a payment > Refunds an existing payment. Requires an idempotency key to prevent duplicate refunds on retry. ## Idempotency Key Benefits for Refunds Refunds are critical financial operations where duplicates can cause serious issues. Using idempotency keys ensures: 1. **Prevent duplicate refunds**: Even if a request times out or fails, retrying with the same key won't issue multiple refunds 2. **Safe retries**: Network failures or timeouts won't risk creating multiple refunds 3. **Consistent response**: Always get the same response for the same operation ## Example Request (curl) ```bash curl -X POST \ https://api.example.com/rest-api/v0/test-payment/pay_abc123xyz456/refund \ -H 'Content-Type: application/json' \ -H 'Client-Key: your-api-key' \ -H 'Client-Secret: your-api-secret' \ -H 'Idempotency-Key: refund_123456_unique_key' ``` ## Example Response (First Request) ```json { "id": "ref_xyz789", "paymentId": "pay_abc123xyz456", "amount": 100.00, "status": "succeeded", "timestamp": "2023-07-01T14:30:00.000Z" } ``` ## Example Response (Duplicate Request) The exact same response will be returned for any duplicate request with the same idempotency key, without creating a new refund. ## Idempotency Key Guidelines - Use a unique key for each distinct refund operation - Store keys client-side to ensure you can retry with the same key if needed - Keys expire after 24 hours by default ## OpenAPI ````yaml /swagger.yml post /api/v0/test-payment/{id}/refund openapi: 3.0.0 info: title: Devdraft AI Payment & Business Management API description: >- A comprehensive payment processing and business management API that enables seamless integration of cryptocurrency and traditional payment methods. version: 1.0.0 contact: {} servers: - url: https://api.devdraft.ai description: Production Server security: [] tags: [] paths: /api/v0/test-payment/{id}/refund: post: tags: - Test Payments summary: Refund a payment description: >- Refunds an existing payment. Requires an idempotency key to prevent duplicate refunds on retry. ## Idempotency Key Benefits for Refunds Refunds are critical financial operations where duplicates can cause serious issues. Using idempotency keys ensures: 1. **Prevent duplicate refunds**: Even if a request times out or fails, retrying with the same key won't issue multiple refunds 2. **Safe retries**: Network failures or timeouts won't risk creating multiple refunds 3. **Consistent response**: Always get the same response for the same operation ## Example Request (curl) ```bash curl -X POST \ https://api.example.com/rest-api/v0/test-payment/pay_abc123xyz456/refund \ -H 'Content-Type: application/json' \ -H 'Client-Key: your-api-key' \ -H 'Client-Secret: your-api-secret' \ -H 'Idempotency-Key: refund_123456_unique_key' ``` ## Example Response (First Request) ```json { "id": "ref_xyz789", "paymentId": "pay_abc123xyz456", "amount": 100.00, "status": "succeeded", "timestamp": "2023-07-01T14:30:00.000Z" } ``` ## Example Response (Duplicate Request) The exact same response will be returned for any duplicate request with the same idempotency key, without creating a new refund. ## Idempotency Key Guidelines - Use a unique key for each distinct refund operation - Store keys client-side to ensure you can retry with the same key if needed - Keys expire after 24 hours by default operationId: TestPaymentController_refundPayment_v0 parameters: - name: id required: true in: path description: Payment ID to refund schema: type: string - name: idempotency-key in: header description: >- Unique key to ensure the refund request is idempotent. If a request with the same key is sent multiple times, only the first will be processed, and subsequent requests will return the same response. required: true schema: type: string format: uuid example: refund_123456_unique_key responses: '200': description: Payment refunded successfully content: application/json: schema: $ref: '#/components/schemas/RefundResponseDto' '400': description: |- Bad Request. The idempotency key is missing or invalid. Sample response: ```json { "statusCode": 400, "message": "The idempotency-key header is required for POST requests" } ``` '401': description: Unauthorized. Client key or secret is invalid or missing. '409': description: >- Idempotency Conflict. The provided idempotency key was already used with different parameters. Sample response: ```json { "statusCode": 409, "message": "Conflict: Idempotency key already used with different request data" } ``` '429': description: Too many requests, rate limit exceeded. security: - x-client-secret: [] - x-client-key: [] components: schemas: RefundResponseDto: type: object properties: id: type: string description: Refund ID example: ref_12345abcdef paymentId: type: string description: Original payment ID example: pay_12345abcdef amount: type: number description: The amount refunded example: 100.5 status: type: string description: Refund status example: succeeded timestamp: type: string description: Timestamp of the refund example: '2023-07-01T12:00:00.000Z' required: - id - paymentId - amount - status - timestamp securitySchemes: x-client-secret: type: apiKey in: header name: x-client-secret description: >- Your secret API key. Keep this secure and never expose it in client-side code. x-client-key: type: apiKey in: header name: x-client-key description: Your unique client API key. Obtain this from your Devdraft AI dashboard. ````