Create a refund

curl --request POST \
  --url https://api.fintoc.com/v1/refunds \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "resource_id": "pi_jsperFI9bnyM2RTo",
  "resource_type": "payment_intent",
  "amount": 5000,
  "metadata": {
    "order_id": "9182"
  }
}
'

{
  "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"
}

{
  "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"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API Key: invalid-*oken"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "forbidden_request",
    "param": null,
    "message": "Refundable resource must be succeeded",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_resource",
    "param": "id",
    "message": "No such payment: pi_jsperFI9bnyM2RTo",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "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"
  }
}

POST

refunds

curl --request POST \
  --url https://api.fintoc.com/v1/refunds \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "resource_id": "pi_jsperFI9bnyM2RTo",
  "resource_type": "payment_intent",
  "amount": 5000,
  "metadata": {
    "order_id": "9182"
  }
}
'

{
  "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"
}

{
  "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"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API Key: invalid-*oken"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "forbidden_request",
    "param": null,
    "message": "Refundable resource must be succeeded",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_resource",
    "param": "id",
    "message": "No such payment: pi_jsperFI9bnyM2RTo",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

{
  "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"
  }
}

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

Authorizations

Authorization

string

header

required

Body

application/json

resource_id

string

required

ID of the resource to refund.

Example:

"pi_jsperFI9bnyM2RTo"

resource_type

enum<string>

required

Type of the resource to refund. Currently only payment_intent is supported.

Available options:

payment_intent

Example:

"payment_intent"

amount

integer

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.

Example:

5000

metadata

object

Set of key-value pairs you can attach to the refund. Useful for storing additional information in a structured format.

Example:

{ "order_id": "9182" }

recipient_account

object

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.

Show child attributes

Response

Refund created. The refund starts in pending status and the funds are disbursed asynchronously.

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.

string

required

Unique identifier of the refund.

Example:

"ref_8XzNbCv1LqKjWp4R"

object

any

required

Type of the object. Always refund.

amount

integer

required

Amount refunded, as an integer in the smallest unit of currency (for example, 5000 for $5000 CLP, since CLP has no minor unit).

Example:

5000

created_at

string<date-time>

required

ISO 8601 timestamp of when the refund was created.

Example:

"2026-03-04T17:04:10Z"

currency

enum<string>

required

Three-letter ISO 4217 currency code. Always matches the currency of the refunded resource.

Available options:

CLP,

MXN

Example:

"CLP"

failure_code

string | null

required

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

object

required

Set of key-value pairs attached to the refund when it was created.

Example:

{ "order_id": "9182" }

mode

enum<string>

required

Mode of the object. live objects use real institution data, test objects use fake data for integration testing.

Available options:

test,

live

Example:

"live"

recipient_account

object | null

required

Bank account that receives the refunded funds. null for refunds that are not disbursed by bank transfer (for example, card refunds).

Show child attributes

resource_id

string

required

ID of the refunded resource.

Example:

"pi_jsperFI9bnyM2RTo"

resource_type

enum<string>

required

Type of the refunded resource. Always payment_intent.

Available options:

payment_intent

Example:

"payment_intent"

status

enum<string>

required

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

Available options:

pending,

in_progress,

succeeded,

failed,

canceled

Example:

"succeeded"

updated_at

string<date-time>

required

ISO 8601 timestamp of when the refund was last updated.

Example:

"2026-03-04T17:04:10Z"

The Refund object List refunds

Fintoc API

Main Resources

Payments API

Transfers API

Movements API

Direct Debit (Legacy)

Fiscal API

Create a refund

Authorizations

Body

Response