{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "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"
  },
  "servers": [
    {
      "url": "https://api.finco.lat",
      "description": "Production server"
    },
    {
      "url": "https://dev-api.finco.lat",
      "description": "Staging server"
    }
  ],
  "paths": {
    "/api/v1/cash/webhooks": {
      "post": {
        "summary": "Create Webhook",
        "description": "Allows authenticated clients to configure webhook endpoints for receiving real-time\nnotifications about operation status changes. The webhook is only activated if the activation test is successful.\n\n**Webhook Events**: After configuration, your endpoint will receive:\n- Activation test: See `WebhookActivationEvent` schema below\n- Status updates: See `OperationStatusUpdateEvent` schema below\n\n**Note**: Only one active webhook is allowed per client. Creating a new webhook will deactivate any existing ones after successful activation.\n",
        "operationId": "createWebhook",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookConfigRequest"
              },
              "example": {
                "endpoint_url": "https://your-webhook-endpoint.com/webhooks"
              }
            }
          }
        },
        "callbacks": {
          "webhookEvents": {
            "{$request.body#/endpoint_url}": {
              "x-displayName": "Customer Webhook Endpoint",
              "post": {
                "summary": "Webhook notifications sent by Monato",
                "description": "After webhook activation, Monato will send POST requests to your configured endpoint\nwith operation status updates. All requests include signature headers for verification.\n",
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "oneOf": [
                          {
                            "$ref": "#/components/schemas/WebhookActivationEvent"
                          },
                          {
                            "$ref": "#/components/schemas/OperationStatusUpdateEvent"
                          }
                        ]
                      },
                      "examples": {
                        "activation": {
                          "summary": "Webhook activation test",
                          "value": {
                            "event": "webhook.activation",
                            "processed_at": "2025-01-15T10:30:00Z"
                          }
                        },
                        "paid": {
                          "summary": "Operation paid successfully",
                          "value": {
                            "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": {
                          "summary": "Operation expired",
                          "value": {
                            "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": {
                          "summary": "Operation reversed",
                          "value": {
                            "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"
                          }
                        }
                      }
                    }
                  }
                },
                "parameters": [
                  {
                    "name": "X-Webhook-Timestamp",
                    "in": "header",
                    "required": true,
                    "description": "Unix timestamp when the webhook was sent",
                    "schema": {
                      "type": "string",
                      "pattern": "^\\d{10}$"
                    },
                    "example": "1705312200"
                  },
                  {
                    "name": "X-Webhook-Signature",
                    "in": "header",
                    "required": true,
                    "description": "HMAC-SHA256 signature for webhook verification",
                    "schema": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "example": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
                  }
                ],
                "responses": {
                  "200": {
                    "description": "Webhook received and processed successfully by client"
                  },
                  "400": {
                    "description": "Client rejected the webhook (invalid data)"
                  },
                  "500": {
                    "description": "Client server error processing webhook"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook configured successfully. An activation test will be sent to your endpoint.\nThe webhook will be marked as active only if your endpoint responds successfully to the test.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookConfigResponse"
                },
                "example": {
                  "event": "webhook.created",
                  "id": 456,
                  "endpoint_url": "https://your-webhook-endpoint.com/webhooks",
                  "secret_token": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c",
                  "created_at": "2025-01-15T10:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WebhookBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/cash/webhooks/active": {
      "get": {
        "summary": "Get Active Webhook",
        "description": "Retrieves the currently active webhook configuration for the authenticated client.\nReturns 404 if no active webhook is configured.\n",
        "operationId": "getActiveWebhook",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Active webhook configuration found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookActiveResponse"
                },
                "example": {
                  "id": 456,
                  "endpoint_url": "https://your-webhook-endpoint.com/webhooks",
                  "is_active": true,
                  "created_at": "2025-01-15T10:30:00Z",
                  "updated_at": "2025-01-15T10:30:00Z"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ActiveWebhookNotFound"
          }
        }
      },
      "put": {
        "summary": "Update Webhook",
        "description": "Updates an existing webhook configuration. The webhook will be deactivated and a new activation test will be sent.\nThe webhook will only become active again if the new endpoint responds successfully to the activation test.\n",
        "operationId": "updateWebhook",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookUpdateRequest"
              },
              "example": {
                "id": 456,
                "endpoint_url": "https://new-webhook-endpoint.com/webhooks"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated successfully and activation test initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookUpdateResponse"
                },
                "example": {
                  "event": "webhook.updated",
                  "id": 456,
                  "endpoint_url": "https://new-webhook-endpoint.com/webhooks",
                  "secret_token": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c",
                  "updated_at": "2025-01-15T11:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/WebhookBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/WebhookNotFound"
          }
        }
      }
    },
    "/api/v1/cash/cash_in": {
      "post": {
        "summary": "Create Cash-In",
        "description": "Creates a new cash-in operation that allows users to deposit money at physical locations.\n\n- **Amount Limits**: 10 - 6000 MXN (may vary by physical location)\n- **Expiration**: 3 days from creation (on closed references)\n- **Reference**: 20-digit unique reference number\n\n**Open References**: Some clients can create \"open references\" without specifying an amount upfront.\nWhen creating an open reference, the `amount` parameter can be omitted, and the actual amount\nwill be determined at the time of payment at the physical location.\n",
        "operationId": "createCashIn",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CashInOperationRequest"
              },
              "examples": {
                "standard_cash_in": {
                  "summary": "Standard cash-in with amount",
                  "value": {
                    "amount": 500,
                    "external_user_id": "USER123456",
                    "document_type": "INE",
                    "document_id": "1234567890123",
                    "phone": "5512345678"
                  }
                },
                "open_reference": {
                  "summary": "Open reference, amount determined at payment",
                  "value": {
                    "external_user_id": "USER123456",
                    "document_type": "INE",
                    "document_id": "1234567890123",
                    "phone": "5512345678"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cash-in created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CashOperationResponse"
                },
                "example": {
                  "response_code": "0",
                  "response_text": "Operacion creada",
                  "result": {
                    "operation_id": 123,
                    "kind": "cash_in",
                    "reference": "10511175512161627448",
                    "status": "close",
                    "transaction_id": "FMXdbnBuiw2SHqSyfzSkqN71q",
                    "amount": 500,
                    "created_at": "2025-01-15T10:30:00Z",
                    "expire_at": "2025-01-18T10:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/CashBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/cash/cash_out": {
      "post": {
        "summary": "Create Cash-Out",
        "description": "Creates a new cash-out operation that allows users to withdraw money at physical locations.\n\n- **Amount Limits**: 50 - 3000 MXN (may vary by physical location)\n- **Expiration**: 60 minutes from creation (default)\n- **Reference**: 20-digit unique reference number\n- **Note**: Maximum and minimum amount may vary by physical location.\n",
        "operationId": "createCashOut",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CashOutOperationRequest"
              },
              "example": {
                "amount": 250,
                "external_user_id": "USER789012",
                "document_type": "CURP",
                "document_id": "ABCD123456HMNMNL01",
                "phone": "5587654321"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cash-out created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CashOperationResponse"
                },
                "example": {
                  "response_code": "0",
                  "response_text": "Operacion creada",
                  "result": {
                    "operation_id": 124,
                    "kind": "cash_out",
                    "reference": "20511175512161627449",
                    "status": "close",
                    "transaction_id": "FMXdbnBuiw2SHqSyfzSkqN72q",
                    "amount": 250,
                    "created_at": "2025-01-15T10:30:00Z",
                    "expire_at": "2025-01-15T11:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/CashBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/cash/bulk_operations": {
      "post": {
        "summary": "Create Bulk Cash-In Operations",
        "description": "Creates multiple cash-in operations in bulk. This endpoint accepts a quantity and expiration date,\nand will generate the specified number of cash-in references asynchronously.\n\n- **Limits**: 1 - 1000 operations per request\n- **Processing**: Operations are created asynchronously via background job\n- **Use Case**: Useful for pre-generating multiple payment references for distribution\n",
        "operationId": "createBulkCashIn",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkOperationRequest"
              },
              "example": {
                "quantity": 100,
                "expiration_date": "2025-01-20"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bulk operation request accepted and processing started",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkOperationResponse"
                },
                "example": {
                  "response_code": "0",
                  "response_text": "Operacion bulk creada",
                  "result": {
                    "bulk_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/CashBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/cash/consult": {
      "get": {
        "summary": "Consult Operation",
        "description": "Retrieves the current status and details of a cash operation using its reference number.\nUse this endpoint to check the status of cash-in or cash-out operations.\n",
        "operationId": "consultOperation",
        "security": [
          {
            "ClientAuth": []
          },
          {
            "HMACSignature": []
          },
          {
            "Timestamp": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Client-Id"
          },
          {
            "$ref": "#/components/parameters/X-Signature"
          },
          {
            "$ref": "#/components/parameters/X-Timestamp"
          },
          {
            "name": "reference",
            "in": "query",
            "required": true,
            "description": "20-digit operation reference number",
            "schema": {
              "type": "string",
              "pattern": "^\\d{20}$",
              "example": "10511175512161627448"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsultOperationResponse"
                },
                "example": {
                  "response_code": "0",
                  "response_text": "Operacion encontrada",
                  "result": {
                    "operation_id": 123,
                    "kind": "cash_in",
                    "reference": "10511175512161627448",
                    "status": "paid",
                    "amount": 500,
                    "created_at": "2025-01-15T10:30:00Z",
                    "expire_at": "2025-01-18T10:30:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/CashBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/OperationNotFound"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "X-Client-Id": {
        "name": "X-Client-Id",
        "in": "header",
        "required": true,
        "description": "Client API key (32-character hex)",
        "schema": {
          "type": "string",
          "pattern": "^[a-f0-9]{32}$"
        },
        "example": "4a8a08f09d37b73795649038408b5f33"
      },
      "X-Signature": {
        "name": "X-Signature",
        "in": "header",
        "required": true,
        "description": "HMAC-SHA256 signature generated using api_secret",
        "schema": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "X-Timestamp": {
        "name": "X-Timestamp",
        "in": "header",
        "required": true,
        "description": "Unix timestamp (seconds since epoch)",
        "schema": {
          "type": "string",
          "pattern": "^\\d{10}$"
        },
        "example": "1705312200"
      }
    },
    "securitySchemes": {
      "ClientAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Client-Id",
        "description": "Client API key (32-character hex) obtained from client creation process.\nMust be used with X-Signature and X-Timestamp headers for HMAC authentication.\n"
      },
      "HMACSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature",
        "description": "HMAC-SHA256 signature generated using your api_secret.\nFormat: HMAC-SHA256(timestamp + \".\" + requestBody, api_secret)\n"
      },
      "Timestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Timestamp",
        "description": "Unix timestamp (seconds since epoch) when the request was created.\nUsed in HMAC signature generation to prevent replay attacks.\n"
      }
    },
    "schemas": {
      "WebhookConfigRequest": {
        "type": "object",
        "required": [
          "endpoint_url"
        ],
        "properties": {
          "endpoint_url": {
            "type": "string",
            "format": "uri",
            "description": "The webhook endpoint URL where notifications will be sent (must use http or https protocol)",
            "example": "https://your-webhook-endpoint.com/webhooks"
          }
        }
      },
      "WebhookUpdateRequest": {
        "type": "object",
        "required": [
          "id",
          "endpoint_url"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Webhook configuration ID to update",
            "example": 456
          },
          "endpoint_url": {
            "type": "string",
            "format": "uri",
            "description": "New webhook endpoint URL",
            "example": "https://new-webhook-endpoint.com/webhooks"
          }
        }
      },
      "WebhookConfigResponse": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "webhook.created"
            ],
            "description": "Event type identifier",
            "example": "webhook.created"
          },
          "id": {
            "type": "integer",
            "description": "Unique identifier for the webhook configuration",
            "example": 456
          },
          "endpoint_url": {
            "type": "string",
            "format": "uri",
            "description": "The configured webhook endpoint URL",
            "example": "https://your-webhook-endpoint.com/webhooks"
          },
          "secret_token": {
            "type": "string",
            "description": "64-character hexadecimal secret token for webhook signature verification",
            "pattern": "^[a-f0-9]{64}$",
            "example": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of webhook configuration creation",
            "example": "2025-01-15T10:30:00Z"
          }
        }
      },
      "WebhookUpdateResponse": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "webhook.updated"
            ],
            "description": "Event type identifier",
            "example": "webhook.updated"
          },
          "id": {
            "type": "integer",
            "description": "Webhook configuration ID",
            "example": 456
          },
          "endpoint_url": {
            "type": "string",
            "format": "uri",
            "description": "Updated webhook endpoint URL",
            "example": "https://new-webhook-endpoint.com/webhooks"
          },
          "secret_token": {
            "type": "string",
            "description": "64-character hexadecimal secret token (unchanged)",
            "pattern": "^[a-f0-9]{64}$",
            "example": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of last update",
            "example": "2025-01-15T11:30:00Z"
          }
        }
      },
      "WebhookActiveResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Webhook configuration ID",
            "example": 456
          },
          "endpoint_url": {
            "type": "string",
            "format": "uri",
            "description": "Active webhook endpoint URL",
            "example": "https://your-webhook-endpoint.com/webhooks"
          },
          "is_active": {
            "type": "boolean",
            "description": "Webhook active status",
            "example": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of creation",
            "example": "2025-01-15T10:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of last update",
            "example": "2025-01-15T10:30:00Z"
          }
        }
      },
      "CashInOperationRequest": {
        "type": "object",
        "required": [
          "external_user_id"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "description": "Transaction amount in MXN (required for standard cash-in, optional for open references)",
            "minimum": 10,
            "maximum": 6000,
            "example": 500
          },
          "external_user_id": {
            "type": "string",
            "description": "Unique identifier for the end user",
            "minLength": 1,
            "example": "USER123456"
          },
          "document_type": {
            "type": "string",
            "enum": [
              "INE",
              "CURP",
              "RFC"
            ],
            "description": "Type of identification document (optional)",
            "example": "INE"
          },
          "document_id": {
            "type": "string",
            "description": "Document identification number (optional)",
            "example": "1234567890123"
          },
          "phone": {
            "type": "string",
            "pattern": "^\\d{10}$",
            "description": "User's phone number - exactly 10 digits (optional)",
            "example": "5512345678"
          }
        }
      },
      "CashOutOperationRequest": {
        "type": "object",
        "required": [
          "amount",
          "external_user_id"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "description": "Transaction amount in MXN",
            "minimum": 50,
            "maximum": 3000,
            "example": 250
          },
          "external_user_id": {
            "type": "string",
            "description": "Unique identifier for the end user",
            "minLength": 1,
            "example": "USER789012"
          },
          "document_type": {
            "type": "string",
            "enum": [
              "INE",
              "CURP",
              "RFC"
            ],
            "description": "Type of identification document (optional)",
            "example": "CURP"
          },
          "document_id": {
            "type": "string",
            "description": "Document identification number (optional)",
            "example": "ABCD123456HMNMNL01"
          },
          "phone": {
            "type": "string",
            "pattern": "^\\d{10}$",
            "description": "User's phone number - exactly 10 digits (optional)",
            "example": "5587654321"
          }
        }
      },
      "BulkOperationRequest": {
        "type": "object",
        "required": [
          "quantity",
          "expiration_date"
        ],
        "properties": {
          "quantity": {
            "type": "integer",
            "description": "Number of cash-in operations to create",
            "minimum": 1,
            "maximum": 1000,
            "example": 100
          },
          "expiration_date": {
            "type": "string",
            "format": "date",
            "description": "Expiration date for all generated operations (YYYY-MM-DD)",
            "example": "2025-01-20"
          }
        }
      },
      "BulkOperationResponse": {
        "type": "object",
        "properties": {
          "response_code": {
            "type": "string",
            "description": "Response code (\"0\" for success)",
            "example": "0"
          },
          "response_text": {
            "type": "string",
            "description": "Response message",
            "example": "Operacion bulk creada"
          },
          "result": {
            "type": "object",
            "properties": {
              "bulk_id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for tracking the bulk operation",
                "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              }
            }
          }
        }
      },
      "CashOperationResponse": {
        "type": "object",
        "properties": {
          "response_code": {
            "type": "string",
            "description": "Response code (\"0\" for success)",
            "example": "0"
          },
          "response_text": {
            "type": "string",
            "description": "Response message",
            "example": "Operacion creada"
          },
          "result": {
            "type": "object",
            "properties": {
              "operation_id": {
                "type": "integer",
                "description": "Unique identifier for the operation",
                "example": 123
              },
              "kind": {
                "type": "string",
                "enum": [
                  "cash_in",
                  "cash_out"
                ],
                "description": "Operation type",
                "example": "cash_in"
              },
              "reference": {
                "type": "string",
                "pattern": "^\\d{20}$",
                "description": "20-digit unique reference number for payment at physical locations",
                "example": "10511175512161627448"
              },
              "status": {
                "type": "string",
                "enum": [
                  "close",
                  "paid",
                  "expired",
                  "reversed"
                ],
                "description": "Current operation status",
                "example": "close"
              },
              "transaction_id": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{25}$",
                "description": "25-character unique transaction identifier",
                "example": "FMXdbnBuiw2SHqSyfzSkqN71q"
              },
              "amount": {
                "type": "integer",
                "description": "Transaction amount in MXN (0 for open references until paid)",
                "example": 500
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of operation creation",
                "example": "2025-01-15T10:30:00Z"
              },
              "expire_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp when operation expires",
                "example": "2025-01-18T10:30:00Z"
              }
            }
          }
        }
      },
      "ConsultOperationResponse": {
        "type": "object",
        "properties": {
          "response_code": {
            "type": "string",
            "description": "Response code (\"0\" for success)",
            "example": "0"
          },
          "response_text": {
            "type": "string",
            "description": "Response message",
            "example": "Operacion encontrada"
          },
          "result": {
            "type": "object",
            "properties": {
              "operation_id": {
                "type": "integer",
                "description": "Unique identifier for the operation",
                "example": 123
              },
              "kind": {
                "type": "string",
                "enum": [
                  "cash_in",
                  "cash_out"
                ],
                "description": "Operation type",
                "example": "cash_in"
              },
              "reference": {
                "type": "string",
                "pattern": "^\\d{20}$",
                "description": "20-digit operation reference number",
                "example": "10511175512161627448"
              },
              "status": {
                "type": "string",
                "enum": [
                  "close",
                  "paid",
                  "expired",
                  "reversed"
                ],
                "description": "Current operation status",
                "example": "paid"
              },
              "amount": {
                "type": "integer",
                "description": "Transaction amount in MXN",
                "example": 500
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of operation creation",
                "example": "2025-01-15T10:30:00Z"
              },
              "expire_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp when operation expires",
                "example": "2025-01-18T10:30:00Z"
              }
            }
          }
        }
      },
      "WebhookActivationEvent": {
        "type": "object",
        "description": "Webhook activation test event sent to your endpoint during configuration",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "webhook.activation"
            ],
            "description": "Event type identifier",
            "example": "webhook.activation"
          },
          "processed_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the activation test was processed",
            "example": "2025-01-15T10:30:00Z"
          }
        }
      },
      "OperationStatusUpdateEvent": {
        "type": "object",
        "description": "Operation status update event sent to your webhook endpoint",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "webhook.paid.success",
              "webhook.expired.success",
              "webhook.reversed.success"
            ],
            "description": "Event type identifier",
            "example": "webhook.paid.success"
          },
          "operation_id": {
            "type": "integer",
            "description": "Unique identifier for the operation",
            "example": 123
          },
          "external_user_id": {
            "type": "string",
            "description": "Unique identifier for the end user",
            "example": "USER123456"
          },
          "type": {
            "type": "string",
            "enum": [
              "cash_in",
              "cash_out"
            ],
            "description": "Operation type",
            "example": "cash_in"
          },
          "amount": {
            "type": "integer",
            "description": "Transaction amount in MXN",
            "example": 500
          },
          "reference": {
            "type": "string",
            "pattern": "^\\d{20}$",
            "description": "20-digit operation reference number",
            "example": "10511175512161627448"
          },
          "status": {
            "type": "string",
            "enum": [
              "paid",
              "expired",
              "reversed"
            ],
            "description": "New operation status",
            "example": "paid"
          },
          "processed_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the status was updated",
            "example": "2025-01-15T10:30:00Z"
          }
        }
      },
      "WebhookErrorResponse": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "webhook.failed"
            ],
            "description": "Event type identifier",
            "example": "webhook.failed"
          },
          "errors": {
            "oneOf": [
              {
                "type": "object",
                "description": "Validation errors with field-specific messages"
              },
              {
                "type": "string",
                "description": "System error message"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Array of error messages"
              }
            ],
            "example": {
              "endpoint_url": [
                "must be a valid URL"
              ]
            }
          }
        }
      },
      "CashErrorResponse": {
        "type": "object",
        "properties": {
          "response_code": {
            "type": "string",
            "description": "Error code identifier",
            "enum": [
              "1",
              "60",
              "64"
            ],
            "example": "60"
          },
          "response_text": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Parámetros Incorrectos"
          },
          "result": {
            "type": "object",
            "description": "Additional error context",
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Requested amount (if applicable)",
                "example": 100
              },
              "external_user_id": {
                "type": "string",
                "description": "User identifier (if applicable)",
                "example": "12345"
              },
              "reference": {
                "type": "string",
                "description": "Reference number (if applicable)",
                "example": "10511397875282322627"
              }
            }
          }
        }
      },
      "UnauthorizedResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Unauthorized"
          }
        }
      }
    },
    "responses": {
      "WebhookBadRequest": {
        "description": "Bad Request - Invalid webhook configuration",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WebhookErrorResponse"
            }
          }
        }
      },
      "WebhookNotFound": {
        "description": "Webhook configuration not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WebhookErrorResponse"
            },
            "example": {
              "event": "webhook.failed",
              "errors": "Webhook config not found"
            }
          }
        }
      },
      "ActiveWebhookNotFound": {
        "description": "No active webhook configuration found for this client",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "not_found"
                },
                "error_type": {
                  "type": "string",
                  "example": "DOMAIN"
                },
                "message": {
                  "type": "string",
                  "example": "Active webhook configuration not found"
                }
              }
            }
          }
        }
      },
      "CashBadRequest": {
        "description": "Bad Request - Invalid operation parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CashErrorResponse"
            },
            "examples": {
              "invalid_parameters": {
                "summary": "Invalid parameters",
                "value": {
                  "response_code": "60",
                  "response_text": "Parámetros Incorrectos",
                  "result": {
                    "amount": 500,
                    "external_user_id": "USER123456"
                  }
                }
              },
              "invalid_amount": {
                "summary": "Invalid amount",
                "value": {
                  "response_code": "60",
                  "response_text": "Parámetros Incorrectos, Monto invalido",
                  "result": {
                    "amount": 5,
                    "external_user_id": "USER123456"
                  }
                }
              },
              "operation_rejected": {
                "summary": "Operation rejected",
                "value": {
                  "response_code": "1",
                  "response_text": "Operacion rechazada",
                  "result": {
                    "amount": 500,
                    "external_user_id": "USER123456"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - Invalid or missing authentication",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/UnauthorizedResponse"
            }
          }
        }
      },
      "OperationNotFound": {
        "description": "Operation not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CashErrorResponse"
            },
            "example": {
              "response_code": "64",
              "response_text": "Operacion no encontrada",
              "result": {
                "reference": "10511175512161627448"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ClientAuth": []
    },
    {
      "HMACSignature": []
    },
    {
      "Timestamp": []
    }
  ]
}