# Transactions

Operations that apply to a transaction regardless of how it was created. Use
them for Money Out, Money In, and Penny Validation alike.

| Need | Operation |
|  --- | --- |
| Read the current state of a transaction | [Retrieve a transaction](#retrieve-a-transaction) |
| Return a received payment to the payer | [Refund transaction](#refund-transaction) |


Webhooks remain the primary signal for state changes. Use the read operation to
reconcile a specific transaction, not as a polling loop.

## Related pages

- [Money Out](/products/fincore/guides/money-out)
- [Money In](/products/fincore/guides/money-in)
- [Penny Validation](/products/fincore/guides/penny-validation)
- [CEP Statuses](/products/fincore/guides/cep-statuses)
- [Webhooks](/products/fincore/guides/webhooks)
- [Error catalog](/products/fincore/guides/error-catalog)


## API contracts

### Retrieve a transaction

Endpoint: `GET /v1/clients/{clientId}/transactions/{transactionId}`

Returns a single transaction owned by the client. It works for Money Out, Money
In, and Penny Validation, so it is the read counterpart to every transaction
webhook. Use the `transactionId` delivered in the webhook or stored by your
system.

For Penny Validation, `metadata.dataCep` carries the CEP data. See
[CEP Statuses](/products/fincore/guides/cep-statuses) for how that status evolves.

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client UUID that owns the transaction."
    },
    "transactionId": {
      "type": "string",
      "format": "uuid",
      "description": "Transaction UUID, as delivered in webhooks or stored by your system."
    }
  },
  "required": [
    "clientId",
    "transactionId"
  ]
}
```

#### Request body

No request body.

#### 200 response body

```json
{
  "$ref": "#/components/schemas/TransactionResponse",
  "components": {
    "schemas": {
      "MoneyAmount": {
        "type": "string",
        "description": "Decimal amount as a string with exactly two decimal places.",
        "pattern": "^[0-9]+\\.[0-9]{2}$",
        "example": "5000.00"
      },
      "Currency": {
        "type": "string",
        "enum": [
          "MXN"
        ],
        "example": "MXN"
      },
      "TransactionCategory": {
        "type": "string",
        "enum": [
          "CREDIT_TRANS",
          "DEBIT_TRANS",
          "INTER_TRANS",
          "OTHER"
        ],
        "example": "DEBIT_TRANS"
      },
      "TransactionSubCategory": {
        "type": "string",
        "enum": [
          "OTHERS",
          "SPEI_CREDIT",
          "SPEI_DEBIT",
          "INT_DEBIT",
          "INT_CREDIT",
          "SPEI_REFUNDED",
          "SPEI_REFUNDED_CREDIT",
          "SPEI_REFUNDED_DEBIT",
          "INT_ADJ_CREDIT",
          "INT_ADJ_DEBIT"
        ],
        "example": "SPEI_DEBIT"
      },
      "TransactionStatus": {
        "type": "string",
        "enum": [
          "INITIALIZED",
          "IN_PROGRESS",
          "LIQUIDATED",
          "CANCELLED",
          "REFUNDED",
          "REJECTED",
          "DECLINED"
        ],
        "example": "INITIALIZED"
      },
      "InstrumentType": {
        "type": "string",
        "enum": [
          "RECEIVER",
          "SENDER_RECEIVER"
        ],
        "example": "RECEIVER"
      },
      "CardInstrumentDetail": {
        "type": "object",
        "description": "Debit-card instrument details returned by Fincore.",
        "properties": {
          "cardNumber": {
            "type": "string",
            "description": "Debit card number associated with the instrument.",
            "example": "5579072268574100"
          },
          "expirationDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card expiration date when available; null otherwise.",
            "example": null
          },
          "holderName": {
            "type": "string",
            "description": "Debit-card holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "cardNumber",
          "holderName"
        ]
      },
      "ClabeInstrumentDetail": {
        "type": "object",
        "description": "CLABE instrument details returned by Fincore.",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "Account number without bank prefix.",
            "example": "006487113111"
          },
          "clabeNumber": {
            "type": "string",
            "description": "Full 18-digit CLABE.",
            "example": "002118006487113111"
          },
          "holderName": {
            "type": "string",
            "description": "CLABE account holder name.",
            "example": "John Smith"
          }
        },
        "required": [
          "accountNumber",
          "clabeNumber",
          "holderName"
        ]
      },
      "TransactionInstrument": {
        "type": "object",
        "description": "Instrument snapshot associated with a transaction.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID.",
            "example": "709448c3-7cbf-454d-a87e-feb23801269a"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the instrument.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the instrument.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or customer that owns the instrument.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "instrumentAlias": {
            "type": "string",
            "description": "Human-friendly label for the instrument.",
            "example": "Centralizing account"
          },
          "instrumentStatus": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "BLOCKED",
              "DELETED"
            ],
            "description": "Current instrument lifecycle status.",
            "example": "ACTIVE"
          },
          "instrumentType": {
            "description": "Instrument usage type.",
            "$ref": "#/components/schemas/InstrumentType"
          },
          "instrumentDetail": {
            "description": "Details of the instrument as stored on the transaction. The shape depends on the instrument type: card destinations return `cardNumber`, `expirationDate` and `holderName`; CLABE instruments return `accountNumber`, `clabeNumber` and `holderName`.\n",
            "oneOf": [
              {
                "$ref": "#/components/schemas/CardInstrumentDetail"
              },
              {
                "$ref": "#/components/schemas/ClabeInstrumentDetail"
              }
            ]
          },
          "rfc": {
            "type": "string",
            "description": "RFC associated with the instrument holder.",
            "example": "XAXX010101000"
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer UUID when the instrument belongs to a Business Unit.",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          }
        }
      },
      "TransactionDataCep": {
        "type": "object",
        "description": "CEP validation metadata associated with a transaction.",
        "properties": {
          "cepUrl": {
            "type": "string",
            "format": "uri",
            "description": "Banxico CEP URL when the CEP document is available.",
            "example": "https://www.banxico.org.mx/cep/..."
          },
          "validationId": {
            "type": "string",
            "format": "uuid",
            "description": "Internal UUID for the CEP validation process.",
            "example": "f4ebe9af-50ac-42e5-97c7-3164d2693d6e"
          },
          "beneficiaryName": {
            "type": "string",
            "description": "Beneficiary name returned by the CEP validation process.",
            "example": "John Smith"
          },
          "beneficiaryRfc": {
            "type": "string",
            "description": "Beneficiary RFC returned by the CEP validation process.",
            "example": "XAXX010101000"
          },
          "status": {
            "type": "string",
            "enum": [
              "INITIALIZED",
              "PENDING",
              "DELAYED",
              "COMPLETED",
              "FAILED"
            ],
            "description": "Current CEP validation status.",
            "example": "PENDING"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the CEP validation record was created.",
            "example": "2025-08-15T22:42:39.327Z"
          },
          "processedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp when CEP processing finished, or null while pending.",
            "example": null
          }
        }
      },
      "TransactionMetadata": {
        "type": "object",
        "description": "Optional transaction metadata returned for CEP validations and returns.",
        "properties": {
          "dataCep": {
            "description": "CEP validation metadata when available.",
            "$ref": "#/components/schemas/TransactionDataCep"
          },
          "dataReturn": {
            "type": "object",
            "description": "Return or refund metadata when available.",
            "properties": {
              "trackingId": {
                "type": "string",
                "example": "20250510FINCHFL2SFGP9KT"
              },
              "originalTrackingId": {
                "type": "string",
                "example": "20250509FINCHARNJK5NHQG"
              },
              "reason": {
                "type": "string",
                "example": "CANCELLED_ACCOUNT"
              },
              "reasonDescription": {
                "type": "string",
                "example": "Cuenta cancelada"
              }
            }
          }
        }
      },
      "MoneyOutResponse": {
        "type": "object",
        "description": "Money Out transaction accepted by Fincore.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "externalReference",
          "trackingId",
          "description",
          "amount",
          "currency",
          "category",
          "subCategory",
          "transactionStatus"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Transaction UUID.",
            "example": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID used by the source account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID that owns the transaction.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "externalReference": {
            "type": "string",
            "description": "Client-provided numeric reference.",
            "example": "1234567"
          },
          "trackingId": {
            "type": "string",
            "description": "Tracking key assigned to the transaction for reconciliation.",
            "example": "20250306FINCHVLIKQ5SKUM"
          },
          "description": {
            "type": "string",
            "description": "Payment concept sent with the transaction.",
            "example": "Supplier payment"
          },
          "amount": {
            "description": "Transaction amount as a decimal string with two decimals.",
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "currency": {
            "description": "Transaction currency.",
            "$ref": "#/components/schemas/Currency"
          },
          "category": {
            "description": "Transaction category.",
            "$ref": "#/components/schemas/TransactionCategory"
          },
          "subCategory": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TransactionSubCategory"
              }
            ],
            "description": "Transaction sub-type based on the destination:\n  - SPEI_DEBIT – external transfer to a non-Finco Pay bank account.\n  - INT_DEBIT – internal transfer routed to a Finco Pay account.\n"
          },
          "transactionStatus": {
            "description": "Current transaction status.",
            "$ref": "#/components/schemas/TransactionStatus"
          },
          "audit": {
            "type": "object",
            "description": "Transaction lifecycle timestamps.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the transaction was created.",
                "example": "2025-03-06 11:57:55.408000-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the transaction was last updated.",
                "example": "2025-03-06 11:57:55.408000-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the transaction was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the transaction was blocked, or null.",
                "example": null
              }
            }
          },
          "sourceInstrument": {
            "description": "Source instrument used to fund the transaction.",
            "$ref": "#/components/schemas/TransactionInstrument"
          },
          "destinationInstrument": {
            "description": "Destination instrument that receives the transaction.",
            "$ref": "#/components/schemas/TransactionInstrument"
          },
          "originalTransactionId": {
            "type": "string",
            "format": "uuid",
            "description": "Present on refund-related transactions.",
            "example": "a1392ef1-23f5-4e15-90cd-5d3d8d24d839"
          },
          "refundTransactionId": {
            "type": "string",
            "format": "uuid",
            "description": "Present on original transactions after refund.",
            "example": "957459ce-d4e3-40b5-b759-373e844ba1e8"
          },
          "metadata": {
            "description": "Optional additional transaction metadata, such as CEP or return details when available. Penny Validation responses use the `PennyValidationResponse` schema because `metadata.dataCep` is required for that flow.\n",
            "$ref": "#/components/schemas/TransactionMetadata"
          },
          "clientReference": {
            "type": "string",
            "description": "Optional client reference returned when it was supplied in the request.",
            "example": "INV-4567"
          }
        }
      },
      "TransactionResponse": {
        "description": "Shared representation of a transaction returned by transaction reads. It carries the same fields as a Money Out response, plus the read-only fields below. Which optional fields are present depends on the transaction category and the flows enabled for the client.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MoneyOutResponse"
          },
          {
            "type": "object",
            "properties": {
              "jsonReference": {
                "type": "string",
                "description": "Raw reference payload stored for the transaction. Can be empty.",
                "example": ""
              },
              "transactionDate": {
                "type": "string",
                "description": "Mexico City local time (UTC-6) when the transaction was processed. Returned without a UTC offset, unlike the timestamps in `audit`.\n",
                "example": "2026-09-23 14:24:58"
              }
            }
          }
        ]
      }
    }
  }
}
```

| Error | When it happens |
|  --- | --- |
| `400` | `clientId` or `transactionId` is not a valid UUID. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | The transaction was not found for the supplied client. |
| `500` | Unexpected server error. |


### Refund transaction

Endpoint: `POST /v1/clients/{clientId}/transactions/{transactionId}/refund`

Use this operation only when the original transaction and business rules allow a
refund.

The resulting refund transaction is also notified through the
[Refund webhook event](/products/fincore/guides/webhooks#refund-webhook-event), which is emitted for
reversals initiated by the banking network as well.

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client UUID (must match the client_id embedded in the Authorization token)."
    },
    "transactionId": {
      "type": "string",
      "format": "uuid",
      "description": "Transaction UUID to be refunded."
    }
  },
  "required": [
    "clientId",
    "transactionId"
  ]
}
```

#### Request body

```json
{
  "$ref": "#/components/schemas/RefundRequest",
  "components": {
    "schemas": {
      "MoneyAmount": {
        "type": "string",
        "description": "Decimal amount as a string with exactly two decimal places.",
        "pattern": "^[0-9]+\\.[0-9]{2}$",
        "example": "5000.00"
      },
      "RefundRequest": {
        "type": "object",
        "required": [
          "amount",
          "description"
        ],
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MoneyAmount"
              }
            ],
            "description": "Refund amount (full refund only). Must be exactly equal to the original transaction amount received. Use two decimal places."
          },
          "description": {
            "type": "string",
            "description": "Text with the refund reason",
            "maxLength": 40,
            "example": "Invalid amount"
          }
        }
      }
    }
  }
}
```

#### Request example

```json Payload application/json
{
  "amount": "5.00",
  "description": "Invalid Amount"
}
```

#### 200 response body

```json
{
  "$ref": "#/components/schemas/RefundResponse",
  "components": {
    "schemas": {
      "MoneyAmount": {
        "type": "string",
        "description": "Decimal amount as a string with exactly two decimal places.",
        "pattern": "^[0-9]+\\.[0-9]{2}$",
        "example": "5000.00"
      },
      "Currency": {
        "type": "string",
        "enum": [
          "MXN"
        ],
        "example": "MXN"
      },
      "TransactionCategory": {
        "type": "string",
        "enum": [
          "CREDIT_TRANS",
          "DEBIT_TRANS",
          "INTER_TRANS",
          "OTHER"
        ],
        "example": "DEBIT_TRANS"
      },
      "TransactionSubCategory": {
        "type": "string",
        "enum": [
          "OTHERS",
          "SPEI_CREDIT",
          "SPEI_DEBIT",
          "INT_DEBIT",
          "INT_CREDIT",
          "SPEI_REFUNDED",
          "SPEI_REFUNDED_CREDIT",
          "SPEI_REFUNDED_DEBIT",
          "INT_ADJ_CREDIT",
          "INT_ADJ_DEBIT"
        ],
        "example": "SPEI_DEBIT"
      },
      "TransactionStatus": {
        "type": "string",
        "enum": [
          "INITIALIZED",
          "IN_PROGRESS",
          "LIQUIDATED",
          "CANCELLED",
          "REFUNDED",
          "REJECTED",
          "DECLINED"
        ],
        "example": "INITIALIZED"
      },
      "RefundResponse": {
        "type": "object",
        "description": "Refund transaction accepted by Fincore.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "externalReference",
          "trackingId",
          "description",
          "amount",
          "currency",
          "category",
          "subCategory",
          "transactionStatus",
          "audit"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Refund transaction UUID.",
            "example": "957459ce-d4e3-40b5-b759-373e844ba1e8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID used by the original transaction account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID that owns the refund.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "externalReference": {
            "type": "string",
            "description": "Reference associated with the refund transaction.",
            "example": "2505091"
          },
          "trackingId": {
            "type": "string",
            "description": "Tracking key assigned to the refund for reconciliation.",
            "example": "20250510FINCHFL2SFGP9KT"
          },
          "description": {
            "type": "string",
            "description": "Refund concept or reason.",
            "example": "Supplier payment"
          },
          "amount": {
            "description": "Refund amount as a decimal string with two decimals.",
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "currency": {
            "description": "Refund currency.",
            "$ref": "#/components/schemas/Currency"
          },
          "category": {
            "description": "Transaction category assigned to the refund.",
            "$ref": "#/components/schemas/TransactionCategory"
          },
          "subCategory": {
            "description": "Transaction sub-category assigned to the refund.",
            "$ref": "#/components/schemas/TransactionSubCategory"
          },
          "transactionStatus": {
            "description": "Current refund transaction status.",
            "$ref": "#/components/schemas/TransactionStatus"
          },
          "audit": {
            "type": "object",
            "description": "Refund lifecycle timestamps.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the refund was created.",
                "example": "2025-05-09 18:02:31.979746-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the refund was last updated.",
                "example": "2025-05-09 18:02:31.979746-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "format": "date-time",
                "description": "Timestamp when the refund was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "format": "date-time",
                "description": "Timestamp when the refund was blocked, or null.",
                "example": null
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "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
  }
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

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

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Refund request fields are missing, malformed, or invalid for the original transaction. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `404` | The original transaction or related account data was not found. |
| `409` | The idempotency key conflicts with a previous request. |
| `500` | Unexpected server error. |