> ## 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.

# Create a refund

> Creates a refund for a succeeded payment in the `live` or `test` mode of the API key used. The refund starts in `pending` status and Fintoc disburses the funds asynchronously. Omit `amount` to refund the resource in full, or pass a lower value for a partial refund. The sum of all refunds for a resource cannot exceed the resource's amount.

**`v1`** · Base URL `https://api.fintoc.com/v1`


## OpenAPI

````yaml reference/fintoc-api.json POST /refunds
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v1
security: []
paths:
  /refunds:
    post:
      tags:
        - Refunds
      summary: Create a refund
      description: >-
        Creates a refund for a succeeded payment in the `live` or `test` mode of
        the API key used. The refund starts in `pending` status and Fintoc
        disburses the funds asynchronously. Omit `amount` to refund the resource
        in full, or pass a lower value for a partial refund. The sum of all
        refunds for a resource cannot exceed the resource's amount.
      operationId: refunds-create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resource_id:
                  type: string
                  example: pi_jsperFI9bnyM2RTo
                  description: ID of the resource to refund.
                resource_type:
                  type: string
                  enum:
                    - payment_intent
                  example: payment_intent
                  description: >-
                    Type of the resource to refund. Currently only
                    `payment_intent` is supported.
                amount:
                  type: integer
                  example: 5000
                  description: >-
                    Amount to refund, as an integer in the smallest unit of the
                    resource's currency (for example, `5000` for $5000 CLP,
                    since CLP has no minor unit). Defaults to the full amount of
                    the resource.
                metadata:
                  type: object
                  example:
                    order_id: '9182'
                  description: >-
                    Set of key-value pairs you can attach to the refund. Useful
                    for storing additional information in a structured format.
                recipient_account:
                  type: object
                  description: >-
                    Bank account that receives the refunded funds. Required for
                    payments where Fintoc cannot determine the payer's account
                    (for example, Botón BancoEstado payments), and not allowed
                    otherwise.
                  properties:
                    holder_id:
                      type: string
                      example: '111111111'
                      description: >-
                        Tax ID of the account holder. For Chilean accounts, a
                        valid RUT; dots and hyphen are optional.
                    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.
                        Must belong to the same country as the payment.
                    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
              required:
                - resource_id
                - resource_type
            examples:
              create_refund:
                summary: Create a refund
                value:
                  resource_id: pi_jsperFI9bnyM2RTo
                  resource_type: payment_intent
                  amount: 5000
                  metadata:
                    order_id: '9182'
              create_refund_with_recipient_account:
                summary: Create a refund specifying the recipient account
                value:
                  resource_id: pi_jsperFI9bnyM2RTo
                  resource_type: payment_intent
                  recipient_account:
                    holder_id: '111111111'
                    holder_name: Jane Doe
                    institution_id: cl_banco_de_chile
                    number: '123456789'
                    type: checking_account
      responses:
        '201':
          description: >-
            Refund created. The refund starts in `pending` status and the funds
            are disbursed asynchronously.
          content:
            application/json:
              examples:
                refund_created:
                  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:
                $ref: '#/components/schemas/refunds_refund'
        '400':
          description: >-
            Invalid request: the `resource_type` is not supported or the
            `recipient_account` is invalid.
          content:
            application/json:
              examples:
                not_supported_resource_type:
                  value:
                    error:
                      type: invalid_request_error
                      code: not_supported_refundable_resource_type
                      param: resource_type
                      message: >-
                        Not supported refundable resource type:
                        checkout_sessions. Currently, supported resources are:
                        payment_intent.
                      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'
        '403':
          description: >-
            The resource cannot be refunded: it has not succeeded, the `amount`
            exceeds the available refundable amount, or your organization does
            not have access to the refunds product.
          content:
            application/json:
              examples:
                resource_not_succeeded:
                  value:
                    error:
                      type: invalid_request_error
                      code: forbidden_request
                      param: null
                      message: Refundable resource must be succeeded
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '404':
          description: >-
            The resource does not exist or belongs to a different mode than the
            API key.
          content:
            application/json:
              examples:
                resource_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      param: id
                      message: 'No such payment: pi_jsperFI9bnyM2RTo'
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '422':
          description: >-
            The `recipient_account` is not allowed for this payment type, is
            required for this payment type, or belongs to a different country
            than the payment.
          content:
            application/json:
              examples:
                recipient_account_not_allowed:
                  value:
                    error:
                      type: invalid_request_error
                      code: recipient_account_not_allowed
                      param: null
                      message: recipient_account is not allowed for this payment type
                      doc_url: https://docs.fintoc.com/reference/errors
              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

````