{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-products/cash/cash-openapi.yaml","sidebar":"sidebar-products/cash/sidebars.yaml"},"props":{"definitionId":"products/cash/cash-openapi.yaml","dynamicMarkdocComponents":[],"baseSlug":"/products/cash/cash-openapi","seo":{"title":"Cash API","siteUrl":"https://docs.monato.com","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"Cash API","description":"Monato Cash API provides secure cash-in and cash-out operations for physical locations in Mexico.\nThis API enables businesses to create cash operations that users can complete at physical payment locations,\nwith real-time webhook notifications for status updates.\n\n## Webhook Events\n\nAfter configuring your webhook endpoint, Monato will send the following events to your server:\n{% admonition type=\"info\" name=\"Note\" %}\n  Only one webhook can be enabled at a time per client.\n{% /admonition %}\n\n### Webhook Activation Test\n- **Event**: `webhook.activation`\n- **Purpose**: Test your endpoint during webhook configuration\n- **Payload**: `{\"event\": \"webhook.activation\", \"processed_at\": \"2025-01-15T10:30:00Z\"}`\n\n## Operation Status\n\nThere are several operation statuses used across `cash in` & `cash out` processes:\n* `unpaid`: Initial status when a reference is created. The operation is ready to be paid.\n* `paid`: Once the end customer completes a cash deposit or cash withdrawal and all required validations succeed.\n* `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.\n* `reversed`: If an issue occurs during processing at the physical location, the transaction is voided.\n\n### Operation Status Updates\n**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.**\n\n- `paid`\n  - **Event**: `webhook.paid.success`\n  - **Purpose**: Notify when cash operation was paid.\n  - **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\"}`\n- `expired`\n  - **Event**: `webhook.expired.success`\n  - **Purpose**: Notify when cash operation expired.\n  - **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\"}`\n- `reversed`\n  - **Event**: `webhook.reversed.success`\n  - **Purpose**: Notify when cash operation was reversed.\n  - **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\"}`\n\nAll webhook requests include signature headers for verification:\n- `X-Webhook-Timestamp`: Unix timestamp\n- `X-Webhook-Signature`: HMAC-SHA256 signature\n\n## Authentication\n\nAll API requests require HMAC-SHA256 authentication using three headers:\n- `X-Client-Id`: Your 32-character API key\n- `X-Signature`: HMAC-SHA256 signature of `timestamp + \".\" + requestBody` using your API secret\n- `X-Timestamp`: Unix timestamp (seconds since epoch) to prevent replay attacks\n\n**Signature Generation**: `HMAC-SHA256(timestamp + \".\" + JSON.stringify(requestBody), api_secret)`\n\n## Handling Errors\n\nResponses may return different HTTP status codes depending on request data and authorization.\n\n{% table %}\n  - Status\n  - Description\n  - Client action\n  ---\n  - 401\n  - Unauthorized\n  - Invalid X-Client-Id or signature verification failed\n  ---\n  - 400\n  - Bad request\n  - The request parameters are invalid. This may be due to malformed values, incorrect formatting, or missing required parameters.\n  ---\n  - 404\n  - Not found\n  - The requested resource doesn't exist.\n  ---\n  - 503\n  - Service Unavailable\n  - The service is under maintenance.\n  ---\n  - 422\n  - Unprocessable Content\n  - The request is syntactically valid, but it cannot be processed because one or more business rules or semantic validations failed.\n  ---\n  - 500\n  - Internal Server Error\n  - The server encountered an unexpected condition that prevented it from fulfilling the request.\n{% /table %}\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.monato.com","port":4000,"ipAddress":"216.73.216.7"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/products/cash/cash-openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}