Docs

Fincore · Guides

Receive money

Receive SPEI and internal deposits through the MONEY_IN webhook, accept or reject them, and refund payments you received.

Money In is how you receive funds into your Monato accounts. Your system does not start it: it happens when funds arrive, usually from an external SPEI deposit or an internal Monato credit. Fincore notifies you with a MONEY_IN webhook.

Even though you do not initiate it, Money In is a core integration flow. Your system must persist the event, deduplicate it, classify the origin, return the expected HTTP status and reconcile it later.

Flow

Step Action Where
1 Configure a MONEY_IN webhook Create webhook configuration
2 Receive and answer the event Money In webhook
3 Reconcile Reports
Configure the MONEY_IN webhook
curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "url": "https://example.com/webhooks/money-in",
    "token": "'"$WEBHOOK_TOKEN"'",
    "webhook_type": "MONEY_IN",
    "auth_type": "AUTH"
  }'

The event

MONEY_IN event
{
  "id_msg": "a7a126e8-fa74-411c-ad2b-b000f277bb0d",
  "msg_name": "MONEY_IN",
  "msg_date": "2025-04-02",
  "body": {
    "id": "0196da9a-8947-703e-9a3b-bf8c7d9f6059",
    "beneficiary_account": "734180000000000001",
    "beneficiary_name": "John Smith",
    "beneficiary_rfc": "XAXX010101000",
    "payer_account": "123456789012345678",
    "payer_name": "Jane Doe",
    "payer_rfc": "XAXX010101000",
    "payer_institution": "40002",
    "amount": "1500.00",
    "transaction_date": "2025-04-02 10:14:05",
    "tracking_key": "50118609TBRNZ00I07219647",
    "payment_concept": "Payment for invoice 4567",
    "numeric_reference": "2504021",
    "sub_category": "SPEI_CREDIT",
    "registered_at": "2025-04-02T10:14:05.915184-06:00",
    "owner_id": "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef"
  }
}

The full field list is in Webhook events.

Classify the origin

Use sub_category and payer_institution to tell external and internal credits apart. The Money In event is the source of truth for these fields.

Origin sub_category payer_institution How to handle it
External SPEI deposit SPEI_CREDIT Banxico institution code of the originating bank, for example 40002. Your HTTP response can accept or reject the deposit.
Internal Monato credit INT_CREDIT Monato internal institution code, for example 90734. Funds have already moved when the webhook is delivered. Your HTTP response does not reverse the movement.

An INT_CREDIT can come from a Money Out whose destination instrument belongs to a Monato account. It is emitted only when the credit is for a different owner than the initiator (a different owner_id, even under the same client_id). Self-transfers under the same client_id and owner_id do not generate a MONEY_IN event. See Internal transfers.

Accept or reject a deposit

Your webhook HTTP response controls external SPEI deposits. Return it within 5 seconds of receiving the request, and finish the business validations you need before you respond. See Respond to events.

Your response Effect
201 Created Recommended when you accept the deposit. Funds remain credited.
200 OK Technical acknowledgement, treated as equivalent to 201.
202 Accepted Event persisted; your extra validations continue asynchronously.
422 Unprocessable Entity You reject the external deposit. Monato automatically refunds it to the original source. Not applicable to INT_CREDIT.

To reject, return 422 with a refundReason. Monato uses it to populate the SPEI refund concept.

422 response body
{
  "refundReason": "Invalid amount"
}

The refund that follows a rejection is notified through the Refund webhook.

Operational recommendations

  • Deduplicate by the message identifier, id_msg. When an event was already processed correctly, return a success status again.
  • Never rely only on delivery order.
  • Store the tracking key and transaction ID for reconciliation. You can read a transaction later with Retrieve a transaction.
  • Return 2xx only after your system has safely persisted the event.
  • Do not log full CLABEs or payer data.
  • Use Reports to reconcile the final daily and monthly state.

Before go-live, run an end-to-end Money In test and confirm that your system can deduplicate the event, persist it, classify SPEI_CREDIT versus INT_CREDIT, return the expected HTTP status and reconcile it in reports.

Refund a received payment

To return a deposit you already accepted, use Refund a transaction. Use it only when the original transaction and your business rules allow a refund.

Partial refunds are not allowed: amount must equal the original amount received, with two decimals. description is the refund reason, up to 40 characters.

curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/transactions/$TRANSACTION_ID/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "description": "Refund due to incorrect amount"
  }'

The refund is a new transaction. You are also notified through the Refund webhook.

HTTP When it happens
400 Malformed IDs, missing or badly formatted amount, amount not equal to the original, invalid description, or the transaction cannot be refunded in its current state, was already refunded, or has a refund in progress.
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.
500 Unexpected server error.