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.

    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 %}
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

        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.
      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

                with operation status updates. All requests include signature
                headers for verification.
              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.

            The webhook will be marked as active only if your endpoint responds
            successfully to the test.
          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.

        Returns 404 if no active webhook is configured.
      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.

        The webhook will only become active again if the new endpoint responds
        successfully to the activation test.
      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.


        - **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.
      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.


        - **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.
      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,

        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
      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.

        Use this endpoint to check the status of cash-in or cash-out operations.
      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.

        Must be used with X-Signature and X-Timestamp headers for HMAC
        authentication.
    HMACSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: |
        HMAC-SHA256 signature generated using your api_secret.
        Format: HMAC-SHA256(timestamp + "." + requestBody, api_secret)
    Timestamp:
      type: apiKey
      in: header
      name: X-Timestamp
      description: |
        Unix timestamp (seconds since epoch) when the request was created.
        Used in HMAC signature generation to prevent replay attacks.
  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: []
