Start Penny Validation

POST /v1/transactions/penny_validation

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

Sends a $0.01 MXN validation transfer to the destination instrument and starts the CEP lookup process. Register a CEP webhook before using this endpoint so you receive status updates. INITIALIZED in the API response should be treated like PENDING; webhook statuses are PENDING, DELAYED, COMPLETED, or FAILED.

Authorization

bearerAuth Bearer token

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

Headers

Idempotency-Key string

Optional deterministic UUID v5 used for safe retries. See Idempotency for key generation, TTL, and conflict behavior.

Example 66c0b04f-97d6-592d-8396-199819064afa

Request body application/json · required

client_id string (uuid) required

Client UUID that owns the validation transaction.

source_instrument_id string (uuid) required

Source instrument UUID used to send the validation amount.

destination_instrument_id string (uuid) required

Destination instrument UUID to validate.

description string

Optional concept for the validation transaction.

Default Penny Validation

external_reference string

Optional numeric reference with a maximum of 7 digits.

Default 0000001

Responses

200 Penny Validation transaction created. 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 required

Required CEP validation metadata for Penny Validation.

dataCep metadata.dataCep object required

CEP validation metadata produced by the Penny Validation flow.

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.

clientReference string

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

400 Penny Validation request is invalid. Possible causes: missing source or destination instrument, invalid description, invalid external reference, unsupported currency/amount rule, or malformed UUIDs. It also covers client or rail state that prevents validation. 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 Source instrument, destination instrument, client, bank, or related account was not found. 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.

409 Idempotency conflict. Possible causes: same Idempotency-Key reused with a different payload, or the original request is still 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.

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/transactions/penny_validation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 66c0b04f-97d6-592d-8396-199819064afa" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "source_instrument_id": "709448c3-7cbf-454d-a87e-feb23801269a",
  "destination_instrument_id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "description": "Account validation",
  "external_reference": "1234567"
}'

const body = JSON.stringify({
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "source_instrument_id": "709448c3-7cbf-454d-a87e-feb23801269a",
  "destination_instrument_id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "description": "Account validation",
  "external_reference": "1234567"
});

const res = await fetch("https://apicore.stg.finch.lat/v1/transactions/penny_validation", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Idempotency-Key": "66c0b04f-97d6-592d-8396-199819064afa",
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

payload = {
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "source_instrument_id": "709448c3-7cbf-454d-a87e-feb23801269a",
  "destination_instrument_id": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "description": "Account validation",
  "external_reference": "1234567"
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/transactions/penny_validation",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Idempotency-Key": "66c0b04f-97d6-592d-8396-199819064afa",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

Response

{
  "id": "1eb4b5ac-09ac-4a64-b853-6939728621d2",
  "trackingId": "20250815FINCHPV123456",
  "transactionStatus": "INITIALIZED",
  "amount": "0.01",
  "currency": "MXN",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "externalReference": "1234567",
  "description": "Account validation",
  "category": "DEBIT_TRANS",
  "subCategory": "SPEI_DEBIT",
  "metadata": {
    "dataCep": {
      "status": "PENDING",
      "cepUrl": "https://www.banxico.org.mx/cep/...",
      "validationId": "f4ebe9af-50ac-42e5-97c7-3164d2693d6e"
    }
  }
}

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

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