> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # List refunds > Lists the refunds of your organization for the `live` or `test` mode of the API key used. Use `since`, `until`, and `status` to filter the results. **`v1`** ยท Base URL `https://api.fintoc.com/v1` ## OpenAPI ````yaml reference/fintoc-api.json GET /refunds openapi: 3.1.0 info: title: fintoc-api version: v2026-02-01 servers: - url: https://api.fintoc.com/v1 security: [] paths: /refunds: get: tags: - Refunds summary: List refunds description: >- Lists the refunds of your organization for the `live` or `test` mode of the API key used. Use `since`, `until`, and `status` to filter the results. operationId: refunds-list parameters: - name: since in: query required: false schema: type: string example: '2026-01-01T00:00:00.000Z' description: Filters refunds created on or after this ISO 8601 date-time, in UTC. - name: until in: query required: false schema: type: string example: '2026-02-01T00:00:00.000Z' description: >- Filters refunds created on or before this ISO 8601 date-time, in UTC. - name: status in: query required: false schema: type: string enum: - pending - in_progress - succeeded - failed - canceled example: succeeded description: Filters refunds by their current status. - name: per_page in: query required: false schema: type: integer format: int32 description: Number of refunds per page. Defaults to `30`. The maximum is `300`. - name: page in: query required: false schema: type: integer format: int32 description: Page number to retrieve. Starts at `1`. responses: '200': description: List of refunds for the current mode. headers: Link: schema: type: string description: >- Pagination links for the collection (`first`, `prev`, `next`, and `last`). X-Total-Count: schema: type: integer description: Total number of refunds matching the query. content: application/json: examples: refunds_list: value: - id: ref_8XzNbCv1LqKjWp4R object: refund amount: 5000 created_at: '2026-03-04T17:04:10Z' currency: CLP failure_code: null metadata: order_id: '9182' mode: live recipient_account: holder_id: '111111111' holder_name: Jane Doe institution_id: cl_banco_de_chile number: '123456789' type: checking_account resource_id: pi_jsperFI9bnyM2RTo resource_type: payment_intent status: pending updated_at: '2026-03-04T17:04:10Z' schema: type: array items: $ref: '#/components/schemas/refunds_refund' '400': description: >- Invalid request: `since` or `until` is not an ISO 8601 date, or `status` is not a valid status. content: application/json: examples: invalid_since_date: value: error: type: invalid_request_error code: invalid_date param: since message: >- Invalid date: not-a-date. You need to provide a date in ISO 8601 format (YYYY-MM-DD) doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: refunds_refund: type: object description: >- A refund returns funds from a succeeded payment to the payer. Fintoc disburses refunds asynchronously, so a refund moves through `pending`, `in_progress`, and `succeeded`, or ends in `failed` or `canceled`. The `amount` and `currency` are denominated in the smallest unit of the refunded resource's currency. properties: id: type: string example: ref_8XzNbCv1LqKjWp4R description: Unique identifier of the refund. object: const: refund description: Type of the object. Always `refund`. amount: type: integer example: 5000 description: >- Amount refunded, as an integer in the smallest unit of `currency` (for example, `5000` for $5000 CLP, since CLP has no minor unit). created_at: type: string format: date-time example: '2026-03-04T17:04:10Z' description: ISO 8601 timestamp of when the refund was created. currency: type: string enum: - CLP - MXN example: CLP description: >- Three-letter ISO 4217 currency code. Always matches the currency of the refunded resource. failure_code: type: - string - 'null' description: >- Reason why the refund failed. One of `fraud_risk` (the disbursement was blocked by Fintoc's fraud checks) or `insufficient_funds` (your organization did not have enough funds to cover the refund). `null` unless the refund failed. metadata: type: object example: order_id: '9182' description: Set of key-value pairs attached to the refund when it was created. mode: $ref: '#/components/schemas/mode' recipient_account: type: - object - 'null' description: >- Bank account that receives the refunded funds. `null` for refunds that are not disbursed by bank transfer (for example, card refunds). properties: holder_id: type: string example: '111111111' description: Tax ID of the account holder, without dots or hyphen. holder_name: type: string example: Jane Doe description: Name of the account holder. institution_id: type: string example: cl_banco_de_chile description: Identifier of the institution where the account lives. number: type: string example: '123456789' description: Number of the account that receives the funds. type: type: string enum: - checking_account - sight_account example: checking_account description: >- Type of the bank account. One of `checking_account` or `sight_account`. required: - holder_id - holder_name - institution_id - number - type resource_id: type: string example: pi_jsperFI9bnyM2RTo description: ID of the refunded resource. resource_type: type: string example: payment_intent enum: - payment_intent description: Type of the refunded resource. Always `payment_intent`. status: type: string enum: - pending - in_progress - succeeded - failed - canceled example: succeeded description: >- Current status of the refund. One of `pending` (the disbursement has not started), `in_progress` (Fintoc is disbursing the funds), `succeeded` (the funds reached the recipient account), `failed` (the disbursement failed; see `failure_code`), or `canceled` (the refund was canceled before disbursing). updated_at: type: string format: date-time example: '2026-03-04T17:04:10Z' description: ISO 8601 timestamp of when the refund was last updated. required: - id - object - amount - created_at - currency - failure_code - metadata - mode - recipient_account - resource_id - resource_type - status - updated_at error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message mode: type: string enum: - test - live description: >- Mode of the object. `live` objects use real institution data, `test` objects use fake data for integration testing. example: live securitySchemes: api_key: type: apiKey name: Authorization in: header ````