Refund a transaction

POST /v1/clients/{clientId}/transactions/{transactionId}/refund

Base URL https://apicore.stg.finch.lat · operationId createRefund

Creates a refund for a transaction. Partial refunds are not allowed. The amount must equal the original transaction amount received.

Authorization

bearerAuth Bearer token

JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.

Path parameters

clientId string (uuid) required

Client UUID (must match the client_id embedded in the Authorization token).

transactionId string (uuid) required

Transaction UUID to be refunded.

Request body application/json · required

amount string required

Refund amount (full refund only). Must be exactly equal to the original transaction amount received. Use two decimal places.

description string required

Text with the refund reason

Responses

200 Refund successfully created application/json

id string (uuid) required

Refund transaction UUID.

bankId string (uuid) required

Bank UUID used by the original transaction account.

clientId string (uuid) required

Client UUID that owns the refund.

externalReference string required

Reference associated with the refund transaction.

trackingId string required

Tracking key assigned to the refund for reconciliation.

description string required

Refund concept or reason.

amount string required

Refund amount as a decimal string with two decimals.

currency string required

Refund currency.

MXN

category string required

Transaction category assigned to the refund.

CREDIT_TRANS DEBIT_TRANS INTER_TRANS OTHER

subCategory string required

Transaction sub-category assigned to the refund.

OTHERS SPEI_CREDIT SPEI_DEBIT INT_DEBIT INT_CREDIT SPEI_REFUNDED SPEI_REFUNDED_CREDIT SPEI_REFUNDED_DEBIT INT_ADJ_CREDIT INT_ADJ_DEBIT

transactionStatus string required

Current refund transaction status.

INITIALIZED IN_PROGRESS LIQUIDATED CANCELLED REFUNDED REJECTED DECLINED

audit object required

Refund lifecycle timestamps.

createdAt audit.createdAt string (date-time)

Timestamp when the refund was created.

updatedAt audit.updatedAt string (date-time)

Timestamp when the refund was last updated.

deletedAt audit.deletedAt string (date-time) | null

Timestamp when the refund was deleted, or null.

blockedAt audit.blockedAt string (date-time) | null

Timestamp when the refund was blocked, or null.

400 Refund request is invalid. Possible causes: malformed clientId or transactionId, missing amount, invalid amount format, amount not equal to the original transaction amount, or invalid description. It also fails when the transaction cannot be refunded in its current state, was already refunded, or a refund is already in progress. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Missing, expired, invalid, or environment-mismatched API key or bearer token. See Authentication. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

404 Transaction was not found for the supplied client. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

This request is in the Monato · Fincore Postman collection, folder Transactions.Download collection

Request

curl -X POST "https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "5.00",
  "description": "Invalid Amount"
}'

const body = JSON.stringify({
  "amount": "5.00",
  "description": "Invalid Amount"
});

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}/refund", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

payload = {
  "amount": "5.00",
  "description": "Invalid Amount"
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}/refund",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

Response

{
  "id": "957459ce-d4e3-40b5-b759-373e844ba1e8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "2505091",
  "trackingId": "20250510FINCHFL2SFGP9KT",
  "description": "Refund due to incorrect amount",
  "amount": "100.00",
  "currency": "MXN",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "transactionStatus": "INITIALIZED",
  "audit": {
    "createdAt": "2025-05-09 18:02:31.979746-06:00",
    "updatedAt": "2025-05-09 18:02:31.979746-06:00",
    "deletedAt": null,
    "blockedAt": null
  }
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}