> ## Documentation Index > Fetch the complete documentation index at: https://docs.orsunpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Request a full or partial refund > Accepts an asynchronous refund in the authenticated merchant and API-key mode. Omit amount to refund the remaining refundable amount. PENDING/PROCESSING are not completion. The original connection must support refunds and payment and processing currencies must match. Idempotency-Key is mandatory. ## OpenAPI ````yaml /openapi.json post /v1/payment/{id}/refunds openapi: 3.1.0 info: contact: name: OrsunPay description: >- Server-to-server merchant payments. Money is always a decimal string in major units. title: OrsunPay Merchant API version: '1.0' servers: [] security: [] tags: - description: Poll stored merchant transaction status name: Transactions - description: Create merchant sales and payouts name: Payments - description: Request refunds and read stored refund outcomes name: Refunds - description: Signed merchant event deliveries name: Webhooks - description: Create, list and deactivate shareable merchant payment links name: Payment links paths: /v1/payment/{id}/refunds: post: tags: - Refunds summary: Request a full or partial refund description: >- Accepts an asynchronous refund in the authenticated merchant and API-key mode. Omit amount to refund the remaining refundable amount. PENDING/PROCESSING are not completion. The original connection must support refunds and payment and processing currencies must match. Idempotency-Key is mandatory. operationId: createRefund parameters: - description: Payment transaction ID in: path name: id required: true schema: maxLength: 32 pattern: ^[A-Za-z0-9_-]{1,32}$ type: string - description: >- A single 1–255 character printable ASCII value without spaces. The checkout-submit: prefix is reserved (case-insensitive). Reuse the same key and body after an uncertain response. in: header name: Idempotency-Key required: true schema: example: refund-order-example-1 maxLength: 255 minLength: 1 pattern: ^[\x21-\x7e]+$ type: string requestBody: content: application/json: examples: partial: summary: Partial refund value: amount: '10.00' metadata: orderReference: order_example reason: requested_by_customer remaining: summary: Refund the remaining amount value: {} schema: $ref: '#/components/schemas/CreateRefundDto' required: true responses: '201': content: application/json: example: data: amount: '10.00' createdAt: '2026-10-11T12:00:00.000Z' currency: EUR errorCode: null id: rf_example metadata: orderReference: order_example providerRefundId: null reason: requested_by_customer status: PENDING transactionId: tr_example updatedAt: '2026-10-11T12:00:00.000Z' schema: $ref: '#/components/schemas/RefundResponseDto' description: Refund accepted for asynchronous execution headers: Idempotency-Replayed: description: Returned when the response is an idempotent replay schema: enum: - 'true' type: string '400': content: application/json: example: error: Bad Request message: - Invalid refund input statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/ValidationErrorResponseDto' - $ref: '#/components/schemas/ApiErrorResponseDto' description: Invalid request, metadata or Idempotency-Key '401': content: application/json: example: error: Unauthorized message: Invalid API key statusCode: 401 schema: $ref: '#/components/schemas/UnauthorizedErrorResponseDto' description: Missing, invalid, expired or inactive merchant API key '404': content: application/json: example: error: REFUND_NOT_FOUND errorCode: REFUND_NOT_FOUND message: REFUND_NOT_FOUND status: false statusCode: 404 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- REFUND_NOT_FOUND: unknown payment/refund or one belonging to another merchant or API-key mode '409': content: application/json: example: error: REFUND_EXCEEDS_AMOUNT errorCode: REFUND_EXCEEDS_AMOUNT message: REFUND_EXCEEDS_AMOUNT status: false statusCode: 409 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE or IDEMPOTENCY_IN_PROGRESS. Currency conversion refunds are unsupported; payment and processing currencies must match. headers: Retry-After: description: Seconds before retrying the same in-progress request schema: type: string '422': content: application/json: example: error: REFUND_NOT_SUPPORTED errorCode: REFUND_NOT_SUPPORTED message: REFUND_NOT_SUPPORTED status: false statusCode: 422 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- REFUND_NOT_SUPPORTED (supported providers: Stripe, Mollie, Revolut and Viva), or IDEMPOTENCY_KEY_REUSED with different request input. '429': content: application/json: example: error: RATE_LIMITED errorCode: RATE_LIMITED message: Too many requests. Retry after the indicated delay. status: false statusCode: 429 schema: $ref: '#/components/schemas/ApiErrorResponseDto' description: >- RATE_LIMITED: IP, merchant or failed-auth quota exhausted, or auth-in-flight concurrency pressure (Retry-After: 1). Wait Retry-After seconds and retry with the same Idempotency-Key. headers: RateLimit: description: >- Remaining requests (r) and seconds to reset/full refill (t), per evaluated policy. Absent when disabled; merchant quota is omitted during Redis outages, while IP/auth protection uses replica memory. schema: example: '"merchant";r=37;t=4' type: string RateLimit-Policy: description: >- Evaluated policies (draft-ietf-httpapi-ratelimit-headers-11). q is burst quota; w is the full refill window in seconds. schema: example: '"merchant";q=100;w=5' type: string Retry-After: description: Minimum delay in whole seconds before retrying. schema: example: 1 minimum: 1 type: integer '503': content: application/json: examples: authentication: value: error: Service Unavailable message: API_KEY_VALIDATION_UNAVAILABLE statusCode: 503 refund: value: error: REFUND_SERVICE_UNAVAILABLE errorCode: REFUND_SERVICE_UNAVAILABLE message: REFUND_SERVICE_UNAVAILABLE status: false statusCode: 503 schema: anyOf: - $ref: '#/components/schemas/AuthenticationUnavailableResponseDto' - $ref: '#/components/schemas/ApiErrorResponseDto' description: >- API-key validation or refund core is unavailable. A create may have committed; retry with the same Idempotency-Key. security: - X-API-Key: [] components: schemas: CreateRefundDto: properties: amount: description: >- Positive decimal string in the payment currency, within its currency precision. Omit to refund the remaining refundable amount. example: '10.00' maxLength: 80 pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string metadata: additionalProperties: true description: >- JSON object, at most 16384 UTF-8 bytes when serialized; maximum container depth 10 (root depth 0). Do not include sensitive customer or payment data. type: object reason: default: requested_by_customer enum: - requested_by_customer - duplicate - fraudulent - other type: string type: object RefundResponseDto: properties: data: $ref: '#/components/schemas/RefundDto' required: - data type: object ValidationErrorResponseDto: properties: error: example: Bad Request type: string message: example: - >- amount must be a decimal string in major units, e.g. "12.30"; JSON numbers are not accepted for money (got 12.3) items: type: string type: array statusCode: example: 400 type: number required: - statusCode - error - message type: object ApiErrorResponseDto: properties: error: description: Same as errorCode example: DUPLICATE_ORDER_ID type: string errorCode: description: >- Machine-readable, extensible code. Known values: ADYEN_REFUSED, CARD_DATA_NOT_ACCEPTED, RATE_LIMITED, PAYMENT_LINK_INVALID_AMOUNT, PAYMENT_LINK_UNSUPPORTED_CURRENCY, PAYMENT_LINK_INVALID_EXPIRY, PAYMENT_LINK_INVALID_MAX_USES, PAYMENT_LINK_REDIRECT_URL_NOT_ALLOWED, PAYMENT_LINK_METADATA_TOO_LARGE, PAYMENT_LINK_INVALID_TEXT, PAYMENT_LINK_NOT_FOUND, PAYMENT_LINK_INVALID_LIMIT, PAYMENT_LINK_INVALID_CURSOR, API_KEY_ROTATION_REQUIRED, ORDER_ID_RESERVED, NO_CREDENTIALS_FOR_MODE, LIVEMODE_MISMATCH, PSP_OUTCOME_UNKNOWN, PAYMENT_METHOD_REQUIRED, PAYMENT_METHOD_INPUT_WITHOUT_METHOD, NO_PAYMENT_METHODS, IDEMPOTENCY_KEY_INVALID, DUPLICATE_ORDER_ID, IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, REFUND_INVALID_AMOUNT, REFUND_INVALID_REASON, REFUND_INVALID_METADATA, REFUND_INPUT_INVALID, REFUND_EXCEEDS_AMOUNT, TRANSACTION_NOT_REFUNDABLE, REFUND_NOT_FOUND, REFUND_NOT_SUPPORTED, IDEMPOTENCY_LEASE_LOST, REFUND_SERVICE_UNAVAILABLE. New codes may be added; clients must handle unknown values. example: DUPLICATE_ORDER_ID type: string existingTransactionId: description: >- DUPLICATE_ORDER_ID only: the transaction that already uses this orderId example: tr_x8k2p0q5scocndpejk0nud75q type: string fields: description: >- Invalid or missing buyer contact fields for CUSTOMER_CONTACT_REQUIRED example: - customer.email - customer.country items: type: string type: array idempotencyKey: description: IDEMPOTENCY_* errors only example: 0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10 type: string message: example: A transaction with orderId "A-1001" already exists for this merchant type: string orderId: description: DUPLICATE_ORDER_ID only example: A-1001 type: string status: example: false type: boolean statusCode: example: 409 type: number required: - status - statusCode - errorCode - error - message type: object UnauthorizedErrorResponseDto: properties: error: example: Unauthorized type: string errorCode: description: Stable authentication error code when available example: API_KEY_ROTATION_REQUIRED type: string message: example: Invalid API key type: string statusCode: description: HTTP status when included by the error handler example: 401 type: number required: - message type: object AuthenticationUnavailableResponseDto: properties: error: example: Service Unavailable type: string message: example: API_KEY_VALIDATION_UNAVAILABLE type: string statusCode: example: 503 type: number required: - statusCode - error - message type: object RefundDto: properties: amount: example: '10.00' pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$ type: string createdAt: format: date-time type: string currency: example: EUR type: string errorCode: anyOf: - type: string - type: 'null' id: example: rf_example type: string metadata: additionalProperties: true type: object providerRefundId: anyOf: - type: string - type: 'null' reason: enum: - requested_by_customer - duplicate - fraudulent - other type: string status: enum: - PENDING - PROCESSING - SUCCEEDED - FAILED - CANCELED type: string transactionId: example: tr_example type: string updatedAt: format: date-time type: string required: - id - transactionId - amount - currency - status - reason - providerRefundId - errorCode - metadata - createdAt - updatedAt type: object securitySchemes: X-API-Key: in: header name: x-api-key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.