Retrieve a transaction

GET /v1/clients/{clientId}/transactions/{transactionId}

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

Returns a single transaction owned by the client. Use it to check the current status of a Money Out, a Money In, or a Penny Validation outside the webhook flow. For Penny Validation, metadata.dataCep carries the CEP data; see the CEP statuses guide for how that status evolves.

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 that owns the transaction.

transactionId string (uuid) required

Transaction UUID, as delivered in webhooks or stored by your system.

Responses

200 The requested transaction. application/json

id string (uuid) required

Transaction UUID.

bankId string (uuid) required

Bank UUID used by the source account.

clientId string (uuid) required

Client UUID that owns the transaction.

externalReference string required

Client-provided numeric reference.

trackingId string required

Tracking key assigned to the transaction for reconciliation.

description string required

Payment concept sent with the transaction.

amount string required

Transaction amount as a decimal string with two decimals.

currency string required

Transaction currency.

MXN

category string required

Transaction category.

CREDIT_TRANS DEBIT_TRANS INTER_TRANS OTHER

subCategory string required

Transaction sub-type based on the destination:

SPEI_DEBIT – external transfer to a non-Finco Pay bank account.
INT_DEBIT – internal transfer routed to a Finco Pay account.

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 transaction status.

INITIALIZED IN_PROGRESS LIQUIDATED CANCELLED REFUNDED REJECTED DECLINED

audit object

Transaction lifecycle timestamps.

createdAt audit.createdAt string (date-time)

Timestamp when the transaction was created.

updatedAt audit.updatedAt string (date-time)

Timestamp when the transaction was last updated.

deletedAt audit.deletedAt string | null

Timestamp when the transaction was deleted, or null.

blockedAt audit.blockedAt string | null

Timestamp when the transaction was blocked, or null.

sourceInstrument object

Source instrument used to fund the transaction.

id sourceInstrument.id string (uuid)

Instrument UUID.

bankId sourceInstrument.bankId string (uuid)

Bank UUID associated with the instrument.

clientId sourceInstrument.clientId string (uuid)

Client UUID associated with the instrument.

ownerId sourceInstrument.ownerId string (uuid)

UUID of the client or customer that owns the instrument.

instrumentAlias sourceInstrument.instrumentAlias string

Human-friendly label for the instrument.

instrumentStatus sourceInstrument.instrumentStatus string

Current instrument lifecycle status.

ACTIVE BLOCKED DELETED

instrumentType sourceInstrument.instrumentType string

Instrument usage type.

RECEIVER SENDER_RECEIVER

instrumentDetail sourceInstrument.instrumentDetail CardInstrumentDetail | ClabeInstrumentDetail

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.

One of CardInstrumentDetail

Debit-card instrument details returned by Fincore.

cardNumber sourceInstrument.instrumentDetail.cardNumber string required

Debit card number associated with the instrument.

expirationDate sourceInstrument.instrumentDetail.expirationDate string | null

Card expiration date when available; null otherwise.

holderName sourceInstrument.instrumentDetail.holderName string required

Debit-card holder name.

One of ClabeInstrumentDetail

CLABE instrument details returned by Fincore.

accountNumber sourceInstrument.instrumentDetail.accountNumber string required

Account number without bank prefix.

clabeNumber sourceInstrument.instrumentDetail.clabeNumber string required

Full 18-digit CLABE.

holderName sourceInstrument.instrumentDetail.holderName string required

CLABE account holder name.

rfc sourceInstrument.rfc string

RFC associated with the instrument holder.

customerId sourceInstrument.customerId string (uuid)

Customer UUID when the instrument belongs to a Business Unit.

destinationInstrument object

Destination instrument that receives the transaction.

id destinationInstrument.id string (uuid)

Instrument UUID.

bankId destinationInstrument.bankId string (uuid)

Bank UUID associated with the instrument.

clientId destinationInstrument.clientId string (uuid)

Client UUID associated with the instrument.

ownerId destinationInstrument.ownerId string (uuid)

UUID of the client or customer that owns the instrument.

instrumentAlias destinationInstrument.instrumentAlias string

Human-friendly label for the instrument.

instrumentStatus destinationInstrument.instrumentStatus string

Current instrument lifecycle status.

ACTIVE BLOCKED DELETED

instrumentType destinationInstrument.instrumentType string

Instrument usage type.

RECEIVER SENDER_RECEIVER

instrumentDetail destinationInstrument.instrumentDetail CardInstrumentDetail | ClabeInstrumentDetail

One of CardInstrumentDetail

Debit-card instrument details returned by Fincore.

cardNumber destinationInstrument.instrumentDetail.cardNumber string required

Debit card number associated with the instrument.

expirationDate destinationInstrument.instrumentDetail.expirationDate string | null

Card expiration date when available; null otherwise.

holderName destinationInstrument.instrumentDetail.holderName string required

Debit-card holder name.

One of ClabeInstrumentDetail

CLABE instrument details returned by Fincore.

accountNumber destinationInstrument.instrumentDetail.accountNumber string required

Account number without bank prefix.

clabeNumber destinationInstrument.instrumentDetail.clabeNumber string required

Full 18-digit CLABE.

holderName destinationInstrument.instrumentDetail.holderName string required

CLABE account holder name.

rfc destinationInstrument.rfc string

RFC associated with the instrument holder.

customerId destinationInstrument.customerId string (uuid)

Customer UUID when the instrument belongs to a Business Unit.

originalTransactionId string (uuid)

Present on refund-related transactions.

refundTransactionId string (uuid)

Present on original transactions after refund.

metadata object

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.

dataCep metadata.dataCep object

CEP validation metadata when available.

cepUrl metadata.dataCep.cepUrl string (uri)

Banxico CEP URL when the CEP document is available.

validationId metadata.dataCep.validationId string (uuid)

Internal UUID for the CEP validation process.

beneficiaryName metadata.dataCep.beneficiaryName string

Beneficiary name returned by the CEP validation process.

beneficiaryRfc metadata.dataCep.beneficiaryRfc string

Beneficiary RFC returned by the CEP validation process.

status metadata.dataCep.status string

Current CEP validation status.

INITIALIZED PENDING DELAYED COMPLETED FAILED

createdAt metadata.dataCep.createdAt string (date-time)

Timestamp when the CEP validation record was created.

processedAt metadata.dataCep.processedAt string (date-time) | null

Timestamp when CEP processing finished, or null while pending.

dataReturn metadata.dataReturn object

Return or refund metadata when available.

trackingId metadata.dataReturn.trackingId string

originalTrackingId metadata.dataReturn.originalTrackingId string

reason metadata.dataReturn.reason string

reasonDescription metadata.dataReturn.reasonDescription string

clientReference string

Optional client reference returned when it was supplied in the request.

jsonReference string

Raw reference payload stored for the transaction. Can be empty.

transactionDate string

Mexico City local time (UTC-6) when the transaction was processed. Returned without a UTC offset, unlike the timestamps in audit.

400 The supplied clientId or transactionId is not a valid UUID. 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 The bearer token is missing, expired, invalid, or not valid for the environment. 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 The 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. 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 GET "https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

res = requests.get(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/transactions/{transactionId}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
    },
)
data = res.json()

Response

{
  "id": "16811ee8-1ef9-4dd4-8d84-9c2df89cf302",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "1234567",
  "trackingId": "20250306FINCHVLIKQ5SKUM",
  "description": "Supplier payment",
  "amount": "5000.00",
  "currency": "MXN",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "transactionStatus": "INITIALIZED",
  "audit": {
    "createdAt": "2025-03-06 11:57:55.408000-06:00",
    "updatedAt": "2025-03-06 11:57:55.408000-06:00",
    "deletedAt": null,
    "blockedAt": null
  },
  "sourceInstrument": {
    "id": "709448c3-7cbf-454d-a87e-feb23801269a",
    "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
    "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "instrumentAlias": "Centralizing account",
    "instrumentStatus": "ACTIVE",
    "instrumentType": "RECEIVER",
    "instrumentDetail": {
      "cardNumber": "5579072268574100",
      "expirationDate": null,
      "holderName": "John Smith"
    },
    "rfc": "XAXX010101000",
    "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
  },
  "destinationInstrument": {
    "id": "709448c3-7cbf-454d-a87e-feb23801269a",
    "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
    "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "instrumentAlias": "Centralizing account",
    "instrumentStatus": "ACTIVE",
    "instrumentType": "RECEIVER",
    "instrumentDetail": {
      "cardNumber": "5579072268574100",
      "expirationDate": null,
      "holderName": "John Smith"
    },
    "rfc": "XAXX010101000",
    "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
  },
  "originalTransactionId": "a1392ef1-23f5-4e15-90cd-5d3d8d24d839",
  "refundTransactionId": "957459ce-d4e3-40b5-b759-373e844ba1e8",
  "metadata": {
    "dataCep": {
      "cepUrl": "https://www.banxico.org.mx/cep/...",
      "validationId": "f4ebe9af-50ac-42e5-97c7-3164d2693d6e",
      "beneficiaryName": "John Smith",
      "beneficiaryRfc": "XAXX010101000",
      "status": "PENDING",
      "createdAt": "2025-08-15T22:42:39.327Z",
      "processedAt": null
    },
    "dataReturn": {
      "trackingId": "20250510FINCHFL2SFGP9KT",
      "originalTrackingId": "20250509FINCHARNJK5NHQG",
      "reason": "CANCELLED_ACCOUNT",
      "reasonDescription": "Cuenta cancelada"
    }
  },
  "clientReference": "INV-4567",
  "jsonReference": "",
  "transactionDate": "2026-09-23 14:24:58"
}

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

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