Docs

Fincore · Reference

Transaction statuses

Transaction status, category and sub-category values, and the full Penny Validation CEP status lifecycle.

Transaction status

Every transaction has a transactionStatus (status in the status update webhook). These are the values in the API contract:

Value
INITIALIZED
IN_PROGRESS
LIQUIDATED
CANCELLED
REFUNDED
REJECTED
DECLINED

What the sources say about them:

  • In the API examples, the synchronous responses of Money Out, Penny Validation and Refund show the transaction as INITIALIZED. That only means Fincore accepted the request; it is not the final state.
  • Status changes of a Money Out arrive in the STATUS_UPDATE webhook, which can include a reason and reason_description.
  • To read the current status of one transaction, use Retrieve a transaction. It works for Money Out, Money In and Penny Validation. Webhooks remain the primary signal; do not use the read operation as a polling loop.
  • After a refund, the original transaction carries refundTransactionId, and the refund transaction carries originalTransactionId.

Category and sub-category

category
CREDIT_TRANS
DEBIT_TRANS
INTER_TRANS
OTHER
subCategory Meaning in the sources
SPEI_DEBIT External transfer to a non-Finco Pay bank account.
INT_DEBIT Internal transfer routed to a Finco Pay account. See Internal transfers.
SPEI_CREDIT External SPEI credit from a non-Finco Pay institution.
INT_CREDIT Internal (book-to-book) credit.
SPEI_REFUNDED_CREDIT Appears on refund events, for example in the Refund webhook.
SPEI_REFUNDED, SPEI_REFUNDED_DEBIT, INT_ADJ_CREDIT, INT_ADJ_DEBIT, OTHERS Listed in the contract without a description.

CEP statuses

Penny Validation resolves asynchronously. Its status is in metadata.dataCep.status on API reads and in status of the CEP webhook. For the request, see Validate a bank account.

Status Meaning Final
INITIALIZED Transient state right after the validation is created. Appears on API reads only; the webhook never emits it. Treat it exactly like PENDING. No
PENDING The CEP lookup is in progress and the result is still expected within the usual window. No
DELAYED The CEP is taking longer than usual. Lookups continue automatically in the background. No action is required from you. No
COMPLETED The CEP was retrieved and the ownership data is available. Yes
FAILED The CEP could not be obtained, or the underlying transfer was rejected. Yes

Do not build distinct flows for INITIALIZED. Collapse it into PENDING in your logic and UI.

Status flow

Text
INITIALIZED
     ├── PENDING ──── DELAYED ──── FAILED
     │      │            │
     │      └── COMPLETED┘
     │
     └── FAILED   (underlying transfer rejected)

What this guarantees for your integration:

  • A validation always ends in COMPLETED or FAILED. It never stays open indefinitely.
  • COMPLETED and FAILED are final. Once reached, the status is never overwritten, so a late event cannot move a validation back to PENDING or DELAYED.
  • COMPLETED can be reached from any non-final state, as soon as the CEP becomes available.
  • PENDING always comes before DELAYED. DELAYED does not mean anything went wrong; it means the CEP is taking longer than usual.
  • If the underlying transfer is rejected, the validation goes straight to FAILED without passing through PENDING or DELAYED. No CEP is generated.

Handling each status

Status Recommended handling
INITIALIZED, PENDING Show the validation as in progress. Wait for the webhook.
DELAYED Keep waiting. Show it as “taking longer than usual” if your UI needs to explain the wait, but do not treat it as an error or start a new validation.
COMPLETED Read beneficiaryName and beneficiaryRfc to confirm ownership, and store cepUrl for your records.
FAILED Treat ownership as unverified. Starting a new validation is a business decision; the account may simply belong to a slow bank.

processedAt is set whenever the validation record is updated, including intermediate updates. Do not use it as a signal that the validation finished; use status.

Other statuses

Object Field Values Where
Account accountStatus ACTIVE, BLOCKED, SUSPENDED, CANCELLED Private accounts
Business Unit customerStatus ACTIVE, INACTIVE, BLOCKED Business units
Business Unit customerValidationStatus PENDING, VALIDATED, REJECTED Business units
Instrument on a transaction instrumentStatus ACTIVE, BLOCKED, DELETED API reference
Whitelist entry instrumentWhitelistStatus ACTIVE, INACTIVE, BLOCKED, EXPIRED, DELETED, CANCELLED Send money to a CLABE
Webhook configuration webhookStatus ACTIVE, INACTIVE Webhook events