Create a money out transaction

POST /v1/transactions/money_out

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

Initiate an outbound transfer. If the destination instrument belongs to a Finco Pay (Monato) account, the system automatically routes the transaction as an internal book-to-book transfer; no SPEI, near-real-time settlement. Routing is handled transparently; no changes to the request body are required. Money Out can also be used for Penny Validation when the transfer amount is 0.01 MXN and the validation flow is enabled for the client. In that case, the transaction can include CEP validation metadata in metadata.dataCep; see the Penny Validation guide for the flow-specific contract. This endpoint supports Idempotency via the Idempotency-Key header (TTL: 24h). Reuse the same key with the exact same body for safe retries. See the Idempotency guide for details.

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

source_instrument_id string (uuid) required

Source instrument UUID used to fund the transaction.

destination_instrument_id string (uuid) required

Destination instrument UUID that will receive the funds.

transaction_request object required

Transfer amount, concept, currency, and references.

external_reference transaction_request.external_reference string required

Numeric reference with a maximum of 7 digits.

description transaction_request.description string required

Payment concept. Must be 40 characters or fewer.

amount transaction_request.amount string required

Amount greater than or equal to 0.01. A 0.01 MXN transfer can be treated as Penny Validation when the validation flow is enabled and the destination is eligible.

currency transaction_request.currency string required

Currency for the transaction.

MXN

client_reference transaction_request.client_reference string

Optional reference supplied by the client.

latitude transaction_request.latitude string

Optional latitude as a string.

longitude transaction_request.longitude string

Optional longitude as a string.

Responses

200 Successfully created 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.

400 Money Out validation failed. Possible causes: insufficient funds, inactive source or destination instrument, invalid amount, unsupported currency, invalid external reference, invalid description, or missing required transaction fields. It also covers client or rail state that prevents the transfer. 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/money_out" \
  -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",
  "transaction_request": {
    "external_reference": "1234567",
    "description": "Supplier payment",
    "amount": "1.95",
    "currency": "MXN"
  }
}'

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",
  "transaction_request": {
    "external_reference": "1234567",
    "description": "Supplier payment",
    "amount": "1.95",
    "currency": "MXN"
  }
});

const res = await fetch("https://apicore.stg.finch.lat/v1/transactions/money_out", {
  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",
  "transaction_request": {
    "external_reference": "1234567",
    "description": "Supplier payment",
    "amount": "1.95",
    "currency": "MXN"
  }
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/transactions/money_out",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Idempotency-Key": "66c0b04f-97d6-592d-8396-199819064afa",
        "Content-Type": "application/json",
    },
    json=payload,
)
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": "1.95",
  "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": "None",
    "blockedAt": "None"
  }
}

{
  "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": 3,
  "message": "API Error",
  "details": [
    {
      "reason": "DATA_ERROR",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Transaction description must have less than 40 characters length.",
        "http_code": "400"
      }
    }
  ]
}

{
  "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": "Idempotency key does not match the request payload",
        "http_code": "409"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Operation money_out in progress",
        "http_code": "409"
      }
    }
  ]
}

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