# Cash API

Monato Cash API provides secure cash-in and cash-out operations for physical locations in Mexico.
This API enables businesses to create cash operations that users can complete at physical payment locations,
with real-time webhook notifications for status updates.

## Webhook Events

After configuring your webhook endpoint, Monato will send the following events to your server:
{% admonition type="info" name="Note" %}
  Only one webhook can be enabled at a time per client.
{% /admonition %}

### Webhook Activation Test
- **Event**: `webhook.activation`
- **Purpose**: Test your endpoint during webhook configuration
- **Payload**: `{"event": "webhook.activation", "processed_at": "2025-01-15T10:30:00Z"}`

## Operation Status

There are several operation statuses used across `cash in` & `cash out` processes:
* `unpaid`: Initial status when a reference is created. The operation is ready to be paid.
* `paid`: Once the end customer completes a cash deposit or cash withdrawal and all required validations succeed.
* `expired`: Each generated reference has an expiration window. For cash-in, the reference expires after 3 days. For cash-out, it expires after 60 minutes, For Open References it expires based on the custom date you set during creation.
* `reversed`: If an issue occurs during processing at the physical location, the transaction is voided.

### Operation Status Updates
**Please note that webhooks are triggered exclusively for operations of the type closed references. Operations involving open references do not currently support automated status updates via webhook.**

- `paid`
  - **Event**: `webhook.paid.success`
  - **Purpose**: Notify when cash operation was paid.
  - **Payload**: `{"event": "webhook.paid.success", "operation_id": 123, "external_user_id": "USER123456", "type": "cash_in", "amount": 500, "reference": "10511175512161627448", "status": "paid", "processed_at": "2025-01-15T10:30:00Z"}`
- `expired`
  - **Event**: `webhook.expired.success`
  - **Purpose**: Notify when cash operation expired.
  - **Payload**: `{"event": "webhook.expired.success", "operation_id": 123, "external_user_id": "USER123456", "type": "cash_in", "amount": 500, "reference": "10511175512161627448", "status": "expired", "processed_at": "2025-01-15T10:30:00Z"}`
- `reversed`
  - **Event**: `webhook.reversed.success`
  - **Purpose**: Notify when cash operation was reversed.
  - **Payload**: `{"event": "webhook.reversed.success", "operation_id": 123, "external_user_id": "USER123456", "type": "cash_in", "amount": 500, "reference": "10511175512161627448", "status": "reversed", "processed_at": "2025-01-15T10:30:00Z"}`

All webhook requests include signature headers for verification:
- `X-Webhook-Timestamp`: Unix timestamp
- `X-Webhook-Signature`: HMAC-SHA256 signature

## Authentication

All API requests require HMAC-SHA256 authentication using three headers:
- `X-Client-Id`: Your 32-character API key
- `X-Signature`: HMAC-SHA256 signature of `timestamp + "." + requestBody` using your API secret
- `X-Timestamp`: Unix timestamp (seconds since epoch) to prevent replay attacks

**Signature Generation**: `HMAC-SHA256(timestamp + "." + JSON.stringify(requestBody), api_secret)`

## Handling Errors

Responses may return different HTTP status codes depending on request data and authorization.

{% table %}
  - Status
  - Description
  - Client action
  ---
  - 401
  - Unauthorized
  - Invalid X-Client-Id or signature verification failed
  ---
  - 400
  - Bad request
  - The request parameters are invalid. This may be due to malformed values, incorrect formatting, or missing required parameters.
  ---
  - 404
  - Not found
  - The requested resource doesn't exist.
  ---
  - 503
  - Service Unavailable
  - The service is under maintenance.
  ---
  - 422
  - Unprocessable Content
  - The request is syntactically valid, but it cannot be processed because one or more business rules or semantic validations failed.
  ---
  - 500
  - Internal Server Error
  - The server encountered an unexpected condition that prevented it from fulfilling the request.
{% /table %}


Version: 1.0.0

## Servers

Production server
```
https://api.finco.lat
```

Staging server
```
https://dev-api.finco.lat
```

## Security

### ClientAuth

Client API key (32-character hex) obtained from client creation process.
Must be used with X-Signature and X-Timestamp headers for HMAC authentication.


Type: apiKey
In: header
Name: X-Client-Id

### HMACSignature

HMAC-SHA256 signature generated using your api_secret.
Format: HMAC-SHA256(timestamp + "." + requestBody, api_secret)


Type: apiKey
In: header
Name: X-Signature

### Timestamp

Unix timestamp (seconds since epoch) when the request was created.
Used in HMAC signature generation to prevent replay attacks.


Type: apiKey
In: header
Name: X-Timestamp

## Download OpenAPI description

[Cash API](https://docs.monato.com/_bundle/products/cash/cash-openapi.yaml)

## Other

### Create Webhook

 - [POST /api/v1/cash/webhooks](https://docs.monato.com/products/cash/cash-openapi/other/createwebhook.md): Allows authenticated clients to configure webhook endpoints for receiving real-time
notifications about operation status changes. The webhook is only activated if the activation test is successful.

Webhook Events: After configuration, your endpoint will receive:
- Activation test: See WebhookActivationEvent schema below
- Status updates: See OperationStatusUpdateEvent schema below

Note: Only one active webhook is allowed per client. Creating a new webhook will deactivate any existing ones after successful activation.

### Get Active Webhook

 - [GET /api/v1/cash/webhooks/active](https://docs.monato.com/products/cash/cash-openapi/other/getactivewebhook.md): Retrieves the currently active webhook configuration for the authenticated client.
Returns 404 if no active webhook is configured.

### Update Webhook

 - [PUT /api/v1/cash/webhooks/active](https://docs.monato.com/products/cash/cash-openapi/other/updatewebhook.md): Updates an existing webhook configuration. The webhook will be deactivated and a new activation test will be sent.
The webhook will only become active again if the new endpoint responds successfully to the activation test.

### Create Cash-In

 - [POST /api/v1/cash/cash_in](https://docs.monato.com/products/cash/cash-openapi/other/createcashin.md): Creates a new cash-in operation that allows users to deposit money at physical locations.

- Amount Limits: 10 - 6000 MXN (may vary by physical location)
- Expiration: 3 days from creation (on closed references)
- Reference: 20-digit unique reference number

Open References: Some clients can create "open references" without specifying an amount upfront.
When creating an open reference, the amount parameter can be omitted, and the actual amount
will be determined at the time of payment at the physical location.

### Create Cash-Out

 - [POST /api/v1/cash/cash_out](https://docs.monato.com/products/cash/cash-openapi/other/createcashout.md): Creates a new cash-out operation that allows users to withdraw money at physical locations.

- Amount Limits: 50 - 3000 MXN (may vary by physical location)
- Expiration: 60 minutes from creation (default)
- Reference: 20-digit unique reference number
- Note: Maximum and minimum amount may vary by physical location.

### Create Bulk Cash-In Operations

 - [POST /api/v1/cash/bulk_operations](https://docs.monato.com/products/cash/cash-openapi/other/createbulkcashin.md): Creates multiple cash-in operations in bulk. This endpoint accepts a quantity and expiration date,
and will generate the specified number of cash-in references asynchronously.

- Limits: 1 - 1000 operations per request
- Processing: Operations are created asynchronously via background job
- Use Case: Useful for pre-generating multiple payment references for distribution

### Consult Operation

 - [GET /api/v1/cash/consult](https://docs.monato.com/products/cash/cash-openapi/other/consultoperation.md): Retrieves the current status and details of a cash operation using its reference number.
Use this endpoint to check the status of cash-in or cash-out operations.