# Money In

Money In is how you receive funds into Monato accounts. Fincore notifies your
system through a Money In webhook.

This guide includes the Money In webhook contract, examples, enums, and response
codes.

## Flow

| Step | Action | OpenAPI contract |
|  --- | --- | --- |
| 1 | Configure Money In webhook | [Create webhook configuration](/products/fincore/guides/webhooks#create-webhook-configuration) |
| 2 | Receive Money In event | [Money In webhook event](#money-in-webhook-event) |
| 3 | Reconcile reports | [Download report file](/products/fincore/guides/reports#download-report-file) |


## Origin classification

| Origin | How to handle it |
|  --- | --- |
| External SPEI deposit | Your webhook response can accept or reject the deposit according to the Money In event contract. |
| Internal Monato credit | Funds have already moved by the time the webhook is delivered; your HTTP response does not reverse the movement. |


Use [Money In webhook event](#money-in-webhook-event) as the source of truth for
fields used to classify origin.

## Accept or reject a Money In

Your webhook HTTP response controls external SPEI deposits:

Return your acceptance or rejection response within **5 seconds** of receiving
the webhook request. Complete the required business validations before responding.
See [Webhook response timeout](/products/fincore/guides/webhooks#response-timeout).

| Your response | Effect |
|  --- | --- |
| `201 Created` | You accept the deposit. Funds remain credited. |
| `200 OK` or `202 Accepted` | Technical acknowledgement. Use only if your integration treats it as accepted. |
| `422 Unprocessable Entity` | You reject the external deposit. Fincore starts refund behavior. |


The rejection body is documented in the [Money In webhook event](#money-in-webhook-event)
contract. The refund that follows a rejection is notified through the
[Refund webhook event](/products/fincore/guides/webhooks#refund-webhook-event). To refund a deposit
you already accepted, use
[Refund transaction](/products/fincore/guides/transactions#refund-transaction).

## Operational recommendations

- Deduplicate by message identifier.
- Store tracking key and transaction ID for reconciliation. You can read a
transaction later with
[Retrieve a transaction](/products/fincore/guides/transactions#retrieve-a-transaction).
- Do not log full CLABEs or payer data.
- Return `2xx` only after your system has safely persisted the event.
- Use reports to reconcile final daily/monthly state.


## API contracts

### Money In webhook event

Webhook event: `POST money-in`

Monato sends this event when funds arrive into one of your accounts.

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Request body

```json
{
  "$ref": "#/components/schemas/WebhookMoneyInEvent",
  "components": {
    "schemas": {
      "MoneyAmount": {
        "type": "string",
        "description": "Decimal amount as a string with exactly two decimal places.",
        "pattern": "^[0-9]+\\.[0-9]{2}$",
        "example": "5000.00"
      },
      "TransactionSubCategory": {
        "type": "string",
        "enum": [
          "OTHERS",
          "SPEI_CREDIT",
          "SPEI_DEBIT",
          "INT_DEBIT",
          "INT_CREDIT",
          "SPEI_REFUNDED",
          "SPEI_REFUNDED_CREDIT",
          "SPEI_REFUNDED_DEBIT",
          "INT_ADJ_CREDIT",
          "INT_ADJ_DEBIT"
        ],
        "example": "SPEI_DEBIT"
      },
      "WebhookMoneyInEvent": {
        "type": "object",
        "properties": {
          "id_msg": {
            "type": "string",
            "format": "uuid",
            "description": "Unique message identifier (use for idempotency/deduplication).",
            "example": "a7a126e8-fa74-411c-ad2b-b000f277bb0d"
          },
          "msg_name": {
            "type": "string",
            "description": "Event name. For Money In notifications it is always \"MONEY_IN\".",
            "enum": [
              "MONEY_IN"
            ],
            "example": "MONEY_IN"
          },
          "msg_date": {
            "type": "string",
            "format": "date",
            "description": "Event date (YYYY-MM-DD).",
            "example": "2025-04-02"
          },
          "body": {
            "type": "object",
            "description": "Money In event payload.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "example": "0196da9a-8947-703e-9a3b-bf8c7d9f6059"
              },
              "beneficiary_account": {
                "type": "string",
                "example": "734180123045603216"
              },
              "beneficiary_name": {
                "type": "string",
                "example": "John Smith"
              },
              "beneficiary_rfc": {
                "type": "string",
                "example": "XYZ123456789"
              },
              "payer_account": {
                "type": "string",
                "example": "137180210044008609"
              },
              "payer_name": {
                "type": "string",
                "example": "Juan Perez"
              },
              "payer_rfc": {
                "type": "string",
                "example": "XYZ987654321"
              },
              "payer_institution": {
                "type": "string",
                "description": "SPEI: Banxico institution code of the originating bank (e.g. 40002). Internal: Monato internal institution code (e.g. 90734).\n",
                "example": "40002"
              },
              "amount": {
                "$ref": "#/components/schemas/MoneyAmount",
                "description": "Amount credited, with two decimal places."
              },
              "transaction_date": {
                "type": "string",
                "description": "Date and time when the transaction was registered in the rail. Format: YYYY-MM-DD HH:MM:SS.\n",
                "example": "2025-04-02 10:14:05"
              },
              "tracking_key": {
                "type": "string",
                "example": "50118609TBRNZ00I07219647"
              },
              "payment_concept": {
                "type": "string",
                "example": "Payment for invoice 4567"
              },
              "numeric_reference": {
                "type": "string",
                "example": "2504021"
              },
              "sub_category": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/TransactionSubCategory"
                  }
                ],
                "description": "Internal classification of the credit. Possible values:\n  - SPEI_CREDIT – external SPEI credit from a non-Finco Pay institution.\n  - INT_CREDIT – internal credit (book-to-book). Can originate from\n    `POST /v1/transactions/money_out` when the destination instrument\n    belongs to a Monato account.\n",
                "example": "SPEI_CREDIT"
              },
              "registered_at": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp in Monato when the transaction was created / persisted (ISO-8601 with timezone).",
                "example": "2025-04-02T10:14:05.915184-06:00"
              },
              "owner_id": {
                "type": "string",
                "format": "uuid",
                "description": "Identifier of the owner of the destination instrument (e.g. the customer that owns the receiving account).",
                "example": "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef"
              }
            },
            "required": [
              "id",
              "beneficiary_account",
              "payer_account",
              "payer_institution",
              "amount",
              "tracking_key",
              "sub_category",
              "owner_id"
            ]
          }
        },
        "required": [
          "id_msg",
          "msg_name",
          "msg_date",
          "body"
        ]
      }
    }
  }
}
```

#### Request example

```json
{
  "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": "734180123045603216",
    "beneficiary_name": "John Smith",
    "beneficiary_rfc": "XYZ123456789",
    "payer_account": "137180210044008609",
    "payer_name": "Juan Perez",
    "payer_rfc": "XYZ987654321",
    "payer_institution": "40002",
    "amount": "5000.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"
  }
}
```

#### 200 response body

No response body.

#### Response example

No response body for successful acknowledgements.

| Response | When to use it |
|  --- | --- |
| `200` | Technical acknowledgement. Treat as accepted only if your integration maps it that way. |
| `201` | Recommended response when you accept an external SPEI Money In. |
| `202` | Event persisted and additional validation continues asynchronously on your side. |
| `422` | Event rejected by your validation. For external SPEI credits, Monato starts refund behavior. |