> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Refund > Request a refund for a payment. This API endpoint is used to initiate a refund for a payment that has been successfully captured. Refunds can be in full or partial. Depending on the payment method, the refund may take a few days to be processed. ## OpenAPI ````yaml /products/commerce/v2/openapi.yaml post /payments/{id}/refunds openapi: 3.1.0 info: title: Commerce API version: '2.0' description: > The Commerce V2 API provides a comprehensive payment orchestration platform designed to streamline and optimize payment processing for modern businesses. Built with flexibility and security at its core, our API enables you to process payments, manage authentications, and handle cardholder data across multiple payment processors without vendor lock-in. contact: name: Starfish GmbH & Co. KG email: hello@starfish.team url: https://hellgate.io/cpa/commerce license: name: Commerce API Terms url: https://hellgate.io/terms-and-conditions servers: - url: https://sandbox.hellgate.io description: Commerce SaaS Sandbox - url: https://api.hellgate.io description: Commerce SaaS Production security: [] tags: - name: payments_ci description: >- Handle payment processing where the customer is actively present and authorizing the transaction. - name: payments_mi description: >- Process transactions without direct customer interaction at the time of payment. - name: payments_modifications description: >- Modify existing payment transactions after initial authorization (capture, void, refund). - name: payments_data description: >- Access comprehensive payment transaction data for reporting, reconciliation, and analysis. - name: refunds_data description: Access detailed refund transaction data for tracking and reconciliation. - name: authentications_ci description: >- Process EMVCo 3-D Secure authentication requests as standalone transactions (one-off, recurring, installment). - name: authentications_mi description: >- Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI) as standalone transactions. - name: authentications_data description: Access the results of prior authentications for reference. - name: credentials_management description: >- Manage stored payment credentials for repeat customers across all operating models. - name: tokens_create description: >- Create and import Commerce tokens to securely store cardholder data while maintaining PCI DSS compliance. - name: tokens_management description: Manage stored Commerce tokens including CVC2 security code management. - name: compliance_service description: >- Safely handle sensitive cardholder data while maintaining PCI DSS compliance via a secure proxy service. - name: network_tokens description: >- Manage network tokens with major card schemes with automatic lifecycle management. - name: merchants description: >- Configure and manage merchant accounts based on your chosen operating model. - name: reconciliation description: Reconcile imported token data. - name: processor_backup description: >- Migrate payment tokens from third-party processors (currently supports stripe.com). paths: /payments/{id}/refunds: post: tags: - payments_modifications summary: Refund description: > Request a refund for a payment. This API endpoint is used to initiate a refund for a payment that has been successfully captured. Refunds can be in full or partial. Depending on the payment method, the refund may take a few days to be processed. operationId: create_refund parameters: - in: path name: id description: The ID of the payment. schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundCreate' examples: full_refund: summary: Full refund value: amount: 1000 currency_code: EUR reference: 'Refund order #12345' full_refund_on_platform: summary: Full refund on platform value: amount: 1000 currency_code: EUR reference: 'Refund order #12345' splits: - type: seller amount: 900 merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 reference: 'Refund order #12345 - Seller 1' - type: commission amount: 100 reference: 'Refund order #12345 - Commission' responses: '200': description: Refund accepted content: application/json: schema: $ref: '#/components/schemas/RefundResponse' examples: full_refund: summary: Full refund (Processing) value: id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 amount: 1000 currency_code: EUR created_at: '2023-10-10T00:00:00Z' payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5 reference: 'Refund order #12345' status: processing full_refund_on_platform: summary: Full refund on platform (Processing) value: id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 amount: 1000 currency_code: EUR created_at: '2023-10-10T00:00:00Z' payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5 reference: 'Refund order #12345' splits: - type: seller amount: 900 merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 reference: 'Refund order #12345 - Seller 1' - type: commission amount: 100 reference: 'Refund order #12345 - Commission' status: processing completed: summary: Refund (completed) value: id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 amount: 1000 currency_code: EUR created_at: '2023-10-10T00:00:00Z' payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5 reference: 'Refund order #12345' status: completed failed: summary: Refund (Failed) value: id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8 amount: 1000 currency_code: EUR created_at: '2023-10-10T00:00:00Z' failure_details: - classifier: TRANSACTION_ERROR message: 'Transaction failed: No refund possible.' source: processor - classifier: PAYMENT_FAILURE message: 'Refund failed: Transaction not successful.' source: protocol payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5 reference: 'Refund order #12345' status: failed '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '404': $ref: '#/components/responses/404_NotFoundError' '409': $ref: '#/components/responses/409_ConflictError' '422': $ref: '#/components/responses/422_ValidationError' security: - APIKeyAuth: [] components: schemas: RefundCreate: type: object properties: amount: $ref: '#/components/schemas/Amount' currency_code: $ref: '#/components/schemas/CurrencyCode' reference: type: string maxLength: 80 description: A description of the refund for later reference splits: $ref: '#/components/schemas/PaymentSplitsRequest' metadata: $ref: '#/components/schemas/Metadata' required: - reference RefundResponse: type: object properties: id: type: string format: uuid amount: $ref: '#/components/schemas/Amount' currency_code: $ref: '#/components/schemas/CurrencyCode' created_at: type: string description: The date-time the refund was created (following ISO 8601) format: date-time failure_details: type: array description: > The reasons why a refund failed during processing in Commerce. This can be due to processing errors on the side of the processor, as well as errors in the processing of the underlying flow. In case the failure is due to a processing problem, the transaction history of the payment can give more information on the exact failure details. items: type: object properties: classifier: type: string message: type: string source: type: string enum: - processor - integration - protocol payment_id: type: string format: uuid reference: type: string maxLength: 80 description: A description of the refund for later reference splits: $ref: '#/components/schemas/PaymentSplitsResponse' status: type: string enum: - processing - completed - failed metadata: $ref: '#/components/schemas/Metadata' required: - id - amount - currency_code - reference - payment_id - status ErrorGeneric: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' Amount: type: integer minimum: 0 description: > The amount given in minor units (e.g. use 700 for 7€). Some currencies do not support minor units (e.g. Japanese Yen). In this case send in the full value, .i.e. 100 for 100 JPY. CurrencyCode: type: string description: | The three letter currency code. See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) PaymentSplitsRequest: description: > An optional array of split instructions. Data in this array is only processed on a Commerce account in the platform operating model. If you are in doubt, please reach out to your account representative. In order to have a valid split instruction, the total amount of the payment needs to be the sum of all splits. | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | seller | Sending the given amount to the seller referenced by the `merchant_id` in the payload. The seller needs to be onboarded to the account and linked to the processor in order to receive funds from a payment split. | | commission | An already existing Commerce token can be used as source for the payment. | type: array minItems: 1 items: type: object discriminator: propertyName: type mapping: seller: $ref: '#/components/schemas/PaymentSplitSeller' commission: $ref: '#/components/schemas/PaymentSplitCommission' oneOf: - $ref: '#/components/schemas/PaymentSplitSeller' - $ref: '#/components/schemas/PaymentSplitCommission' Metadata: type: object description: > Metadata consisting of entries, each of which each includes a key and an associated value: * Maximum 20 key-value pairs. * Maximum 20 characters per key. * Maximum 80 characters per value. example: my_key_one: my_value_one my_key_two: my_value_two PaymentSplitsResponse: description: > An array of split instructions. Data in this array is only processed on a Commerce account in the platform operating model. If you are in doubt, please reach out to your account representative. | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | seller | Sending the given amount to the seller referenced by the `merchant_id` in the payload. The seller needs to be onboarded to the account and linked to the processor in order to receive funds from a payment split. | | commission | An already existing Commerce token can be used as source for the payment. | type: array minItems: 1 items: type: object discriminator: propertyName: type mapping: seller: $ref: '#/components/schemas/PaymentSplitSeller' commission: $ref: '#/components/schemas/PaymentSplitCommission' oneOf: - $ref: '#/components/schemas/PaymentSplitSeller' - $ref: '#/components/schemas/PaymentSplitCommission' ErrorStatusCode: type: integer description: The corresponding HTTP status code for the error ErrorClassifier: type: string description: Technical code that helps to identify the error ErrorMessage: type: string description: Human readable representation of the error ErrorValidation: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' validation_errors: type: array items: type: object properties: path: type: string description: Json-path in the request which points to the validation error message: type: string description: Human readable validation message PaymentSplitSeller: type: object properties: type: type: string merchant_id: type: string format: uuid amount: type: integer description: | The amount to be sent to the respective merchant account. It considers the payment's currency selection. reference: type: string description: A reference for the seller split. required: - type - merchant_id - amount - reference PaymentSplitCommission: type: object properties: type: type: string amount: type: integer description: > The amount to be sent to the platform account in terms of a commission. It considers the payment's currency selection. reference: type: string description: A reference for the commission split. required: - type - amount - reference responses: 401_UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 401 message: No valid means of authentication was provided classifier: UNAUTHORIZED 403_ForbiddenError: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 403 message: Not allowed to access this resource or feature classifier: FORBIDDEN 404_NotFoundError: description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 404 message: The requested resource was not found. classifier: NOT_FOUND 409_ConflictError: description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 409 message: Conflict classifier: CONFLICT 422_ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorValidation' example: code: 422 classifier: VALIDATION_ERROR message: Validation error validation_errors: - path: json-path message: human readable error message securitySchemes: APIKeyAuth: type: apiKey name: X-API-Key in: header ````