openapi: 3.0.3
info:
  title: Tilopay API BaaS
  version: 1.0.0
  description: |
    The Tilopay API BaaS lets merchants and integrated clients initiate
    payments (PIN and SINPE Móvil), check their status, manage accounts, and
    subscribe to payment event webhooks — all scoped to the accounts the access
    token is authorized for.

    **Authentication**
    1. `POST /auth/login` — authenticates the client with its credentials and
       returns a GIDP ID token plus the available assignments (tenant/account
       contexts the client can act as).
    2. `POST /auth/token/exchange` — exchanges that ID token, together with the
       chosen `assignment_id`, for an access token (JWT).
    3. Send that JWT as `Authorization: Bearer <token>` on every subsequent call.
       The token determines the visible accounts automatically — never send
       `tenant_id`, `owner_id`, or `owner_type` in the body or query params of
       other endpoints.

    **Response format**
    Every response uses the same envelope:
    ```json
    {
      "success": true,
      "http_status_code": 200,
      "response_code": "OK",
      "message": "The request was processed successfully.",
      "correlation_id": "...",
      "data": { }
    }
    ```
    On error, `success` is `false`, `data` is absent, and `errors` carries
    additional detail instead. `response_code` is always one of the values in
    the `ResponseCode` schema — never a free-form string.

    **Correlation.** Send `X-Correlation-Id` on any request to trace it end-to-end; the
    same value is always echoed back as `correlation_id` in the response envelope. If
    omitted, one is generated for you and still returned.

    **Idempotency.** `Idempotency-Key` is only implemented on
    `POST /api/public/v1/transactions/payments` (payment creation). Other POST endpoints
    do not read or honor this header today — retries there are not deduplicated by key.

    **Walking the API**
    - **Payments** — create, check, and search payments (PIN, SINPE Móvil).
    - **Accounts** — validate destination accounts, list accounts and balances, request statements.
    - **Webhooks** — subscribe to payment events (succeeded, failed, reversed, payin
      received) with HMAC signing or optional encryption.
    - **Catalogs** — supporting catalogs (identification types by country).

    ## Account identification standard

    Accounts are always identified by an **identifier scheme** plus a **value**
    (for example `type=IBAN` and the IBAN string). This is **not** the internal
    account classification (e.g. `operational`).

    - **Request/response bodies:** `account: { type, value }`
    - **Query parameters:** `type` + `value` (same meaning as the body fields)

    See `docs/ACCOUNT-IDENTIFIERS.md`.

    ## Party identification (`identification.number`)

    Payment `source.identification` / `destination.identification` use platform catalog
    keys (`cedula`, `juridica`, `dimex`, …) and a **public number**: the value submitted
    on create, digits without SINPE hyphenation (not `01-1234-3005`).

    Create stores that public value separately from the internal GX/SINPE form used to
    talk to the rail. Subsequent reads (`GET /transactions/payments`,
    `GET /transactions/payments/{payment_id}`, `POST /transactions/payments/search`)
    return the same public number. Create `data` remains the compact ack
    (`payment_id`, `public_id`, `status`, …); identification is on the read APIs.

    Payments created **before** this persistence may still return the hyphenated SINPE
    display form previously stored for GX resend. Those historical values are not
    rewritten. See `docs/PAYMENT-IDENTIFICATION.md`.

    ## Webhook naming: payment vs payin/payout vs transaction

    - **payment**: the money-movement resource. The webhook envelope object is always
      `payment`. Outcome events use the `payment.*` prefix (`payment.succeeded`,
      `payment.succeeded`, `payment.failed`, `payment.reversed`). Correlate with REST `GET /transactions/payments` using
      `payment.public_id` or `payment.payment_id`.
    - **payin / payout**: direction of that payment (`PAYIN` inbound, `PAYOUT` outbound),
      same as REST `type`. `payin.posted` fires only when an inbound payment is
      ledger-posted (funds received). There is no public `payout.posted`.
      `payment.succeeded`, `payment.failed`, and `payment.reversed` apply to both directions.
    - **transaction**: REST URL namespace only (`/api/public/v1/transactions/...`).
      Not a webhook object and not an `event_type` prefix. There are no `transaction.*` events.

    ## status vs result vs event_type

    These fields are orthogonal. Do not treat them as aliases.

    - **status** — processing/lifecycle of the payment resource (`pending`, `processing`,
      `confirmed`, `posted`, `failed`). A later reversal does **not** change `status`
      to `failed`; a posted payment stays `posted`.
    - **result** — business outcome for reconciliation (`pending`, `succeeded`, `failed`,
      `reversed`). `reversed` when `has_reversal` is true.
    - **has_reversal** — boolean fact that a reversal was applied.
    - **event_type** (webhooks) — what just happened: `payment.succeeded` (provider
      confirmed success), `payment.failed` (processing ended in failure), `payment.reversed`
      (subsequent reversal of a payment that already progressed).

    ## REST ↔ webhook payment contract (`payment.succeeded` / `payment.failed`)

    REST payment reads (`GET /transactions/payments`, `POST /transactions/payments/search`,
    `GET /transactions/payments/{payment_id}`) and webhooks `payment.succeeded` /
    `payment.failed` use the **same name, location, and meaning** for:

    - `schema_version` — `1.0.0` (REST: on `data` / each payment; webhook: envelope root)
    - `payment.external_reference` — rail/SINPE id (`metadata.sinpe_reference`, else
      `external_provider_tx_id`). Sibling of `client_reference`. `null` if none.
    - `payment.error` — `domain` + `platform.code` / `platform.message` (failed/reversed only)
    - `provider` — shared object on REST and webhooks: `correlation_id`, `occurred_at`,
      `provider_status_code`, `provider_status_desc`, `provider_status_semantic`.
      `provider.correlation_id` is the transaction UUID (`execution.correlation_id`),
      not `channel_reference`. Rail reference lives only on `payment.external_reference`.

    See `docs/WEBHOOKS.md` §6.

    Deduplicate webhook deliveries with `event.event_id`.

    ## Timestamps (RFC 3339)

    All public datetime fields (REST and webhooks) use **RFC 3339** with this precision policy:

    - **UTC** with a `Z` suffix (never a numeric offset such as `+00:00`)
    - **Second precision** — fractional seconds are never emitted
    - Canonical example: `2026-01-15T12:00:00Z`

    Requests (`date_from`, `date_to`, and similar filters) may include a numeric offset
    or fractional seconds; they are interpreted as UTC and truncated to seconds.
    Integrators should parse RFC 3339 rather than requiring a single incoming string
    layout, but responses are stable for strict validators
    (`YYYY-MM-DDTHH:MM:SSZ`).
servers:
  - url: https://api-baas-sandbox.tilopay.com
security:
  - BearerAuth: []
tags:
  - name: General
    description: Health check and other cross-cutting endpoints.
  - name: Docs
    description: "Meta endpoints: raw spec and interactive docs UI."
  - name: Auth
    description: Login and token exchange. These endpoints do not require a Bearer token.
  - name: Payments
    description: Create, check, and search payments (PIN, SINPE Móvil), and validate destination accounts.
  - name: Accounts
    description: List accessible accounts and their balances, and request account statements.
  - name: Webhooks
    description: Manage webhook destinations and inspect the outbound payload contract for each event type.
  - name: Catalogs
    description: Supporting reference catalogs (e.g. identification types by country).
paths:
  /openapi.yaml:
    get:
      summary: OpenAPI specification file
      security: []
      tags:
        - Docs
      responses:
        "200":
          description: OpenAPI yaml
          content:
            application/yaml:
              schema:
                type: string
  /docs:
    get:
      summary: Scalar API documentation UI
      security: []
      tags:
        - Docs
      responses:
        "200":
          description: HTML docs page
          content:
            text/html:
              schema:
                type: string
  /api/public/v1/healthz:
    get:
      summary: Health check
      security: []
      tags:
        - General
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      message:
                        type: string
                      service:
                        type: string
                      version:
                        type: string
                    required:
                      - message
                      - service
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "500":
          content:
            application/json:
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 2
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
          description: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 1
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/auth/login:
    post:
      summary: Login
      description: |
        Authenticates a customer and returns a GIDP ID token plus the available
        customer assignments for context selection. Use `assignment_id` with
        `gidp_id_token` in `POST /api/public/v1/auth/token/exchange` to obtain an access token.
      security: []
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerLoginRequest"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      assignments:
                        items:
                          properties:
                            assignment_id:
                              type: string
                            country_code:
                              type: string
                            owner_id:
                              type: string
                            owner_type:
                              type: string
                            role:
                              type: string
                            roles:
                              items:
                                type: string
                              type: array
                            status:
                              type: string
                            tenant_code:
                              type: string
                            tenant_id:
                              type: string
                          required:
                            - assignment_id
                            - owner_type
                            - owner_id
                            - tenant_id
                            - tenant_code
                            - country_code
                            - role
                            - roles
                            - status
                          type: object
                        type: array
                      gidp_id_token:
                        type: string
                    required:
                      - assignments
                      - gidp_id_token
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 1
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Invalid email or password.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INVALID_CREDENTIALS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_INVALID_CREDENTIALS:
                  $ref: "#/components/examples/Error_INVALID_CREDENTIALS"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_CREDENTIALS
                  message: Invalid email or password.
                http_status_code: 401
                message: Invalid email or password.
                response_code: INVALID_CREDENTIALS
                success: false
          x-error-codes:
            - number: 2
              code: INVALID_CREDENTIALS
              message: Invalid email or password.
        "403":
          content:
            application/json:
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 3
              code: FORBIDDEN
              message: You do not have permission to perform this action.
          description: You do not have permission to perform this action.
        "500":
          content:
            application/json:
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 5
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
          description: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 4
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/auth/token/exchange:
    post:
      summary: Exchange external token
      description: |
        Exchanges the `gidp_id_token` obtained from login, together with the
        chosen `assignment_id`, for an access token (JWT). Send that token as
        `Authorization: Bearer <token>` on every other endpoint.
      security: []
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerExchangeRequest"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      claims:
                        properties:
                          channel:
                            type: string
                          country_code:
                            type: string
                          idempotency_key:
                            type: string
                          idp:
                            type: string
                          idp_sub:
                            type: string
                          locale:
                            type: string
                          owner_id:
                            type: string
                          owner_type:
                            type: string
                          roles:
                            items:
                              type: string
                            type: array
                          scopes:
                            items:
                              type: string
                            type: array
                          sub:
                            type: string
                          subject_kind:
                            type: string
                          tenant_id:
                            type: string
                          user_type:
                            type: string
                        required:
                          - channel
                          - country_code
                          - idempotency_key
                          - idp
                          - idp_sub
                          - locale
                          - owner_id
                          - owner_type
                          - roles
                          - scopes
                          - sub
                          - subject_kind
                          - tenant_id
                          - user_type
                        type: object
                      expires_in:
                        type: integer
                      token:
                        type: string
                    required:
                      - claims
                      - expires_in
                      - token
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 1
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 2
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          content:
            application/json:
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 3
              code: FORBIDDEN
              message: You do not have permission to perform this action.
          description: You do not have permission to perform this action.
        "500":
          content:
            application/json:
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 5
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
          description: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 4
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/auth/request-set-password:
    post:
      summary: Request set password
      description: |
        Starts the password set/reset process for the given email. Does not
        require prior authentication. Always responds the same way whether or
        not the email exists, to avoid revealing account existence.
      security: []
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerPasswordResetRequest"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      message:
                        type: string
                    required:
                      - message
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 1
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "500":
          content:
            application/json:
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 3
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
          description: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 2
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/transactions/payments:
    get:
      operationId: getPublicListPayments
      summary: List customer payments
      description: |
        Simple REST list of payments for an owned account (IBAN).

        Filters are query parameters. Ownership (`tenant_id`, `owner_type`, `owner_id`)
        is derived from the access token; clients must not send ownership filters.

        **Account identification (required):** `type` + `value` (identifier
        scheme + value, e.g. `IBAN` + IBAN string). This is not the internal
        account classification.

        Pagination is cursor-based (`limit`, `cursor`). Default limit is 20 (max 100).

        `status` in the response and as a filter uses the public lowercase catalog
        (`pending`, `processing`, `confirmed`, `posted`, `failed`). Same values as webhooks.
        REST also returns `status_detail` (uppercase operational name).

        Each item includes a consolidated `result` (`succeeded`, `failed`, `reversed`, `pending`)
        for reconciliation when a webhook was missed. `status` is only the processing/lifecycle
        catalog and does not change to `failed` when a posted payment is later reversed —
        use `result=reversed` and `has_reversal=true` (webhook `payment.reversed`).
        `error` is `null` when there is no failure information; it is an object only when
        `domain` / `platform` is present (`result` is `failed` or `reversed`), same shape
        as webhook `payment.failed` `payment.error`.
        `source` / `destination` use `null` for unknown `account`, `name`, and `identification`;
        account values are IBAN or PHONE only (never ledger UUIDs).
        For PIN payments created after public identification persistence,
        `identification.number` is the partner-submitted public number (no SINPE hyphens);
        older payments may still show the hyphenated SINPE form. See `docs/PAYMENT-IDENTIFICATION.md`.
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - $ref: "#/components/parameters/AccountIdentifierType"
        - $ref: "#/components/parameters/AccountIdentifierValue"
        - name: status
          in: query
          required: false
          description: |
            Optional payment status filter. Public catalog is lowercase:
            `pending`, `processing`, `confirmed`, `posted`, `failed`.
            Uppercase aliases of the same values are accepted. Legacy values
            such as `INITIATED` map to `pending`.
          schema:
            $ref: "#/components/schemas/PublicPaymentStatus"
        - name: date_from
          in: query
          required: false
          description: Inclusive lower bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds).
          schema:
            $ref: "#/components/schemas/Rfc3339DateTimeInput"
          example: 2026-01-01T00:00:00Z
        - name: date_to
          in: query
          required: false
          description: Inclusive upper bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds).
          schema:
            $ref: "#/components/schemas/Rfc3339DateTimeInput"
          example: 2026-01-31T23:59:59Z
        - name: client_reference
          in: query
          required: false
          description: Filter by partner client reference (exact match against the value sent at payment creation).
          schema:
            type: string
        - name: currency
          in: query
          required: false
          description: Filter by payment currency (ISO 4217, e.g. CRC).
          schema:
            type: string
          example: CRC
        - name: payment_method_code
          in: query
          required: false
          description: Filter by public payment method code.
          schema:
            type: string
            enum:
              - PIN
              - SINPE_MOVIL
          example: PIN
        - name: direction
          in: query
          required: false
          description: |
            Filter by payment direction. Accepts public values `OUT`/`IN` or
            `PAYOUT`/`PAYIN` (internally normalized to `payout`/`payin`).
          schema:
            type: string
            enum:
              - OUT
              - IN
              - PAYOUT
              - PAYIN
          example: OUT
        - name: limit
          in: query
          required: false
          description: Page size (default 20, max 100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          required: false
          description: Opaque cursor from a previous response `pagination.next_cursor`.
          schema:
            type: string
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            amount:
                              properties:
                                amount:
                                  type: string
                                currency:
                                  type: string
                              required:
                                - amount
                                - currency
                              type: object
                            client_reference:
                              type: string
                            created_at:
                              type: string
                            destination:
                              properties:
                                account:
                                  properties:
                                    currency:
                                      type: string
                                    type:
                                      type: string
                                    value:
                                      type: string
                                  required:
                                    - type
                                    - value
                                  type: object
                                identification:
                                  properties:
                                    number:
                                      type: string
                                    type:
                                      type: string
                                  required:
                                    - type
                                    - number
                                  type: object
                                name:
                                  type: string
                              required:
                                - account
                                - name
                                - identification
                              type: object
                            error:
                              properties:
                                domain:
                                  type: string
                                platform:
                                  properties:
                                    code:
                                      type: string
                                    message:
                                      type: string
                                  required:
                                    - code
                                    - message
                                  type: object
                              required:
                                - domain
                                - platform
                              type: object
                            external_reference:
                              type: string
                            has_reversal:
                              type: boolean
                            payment_id:
                              type: string
                            payment_method_code:
                              type: string
                            provider:
                              properties:
                                correlation_id:
                                  type: string
                                occurred_at:
                                  type: string
                                provider_status_code:
                                  type: string
                                provider_status_desc:
                                  type: string
                                provider_status_semantic:
                                  type: string
                              required:
                                - correlation_id
                                - occurred_at
                                - provider_status_code
                                - provider_status_desc
                                - provider_status_semantic
                              type: object
                            public_id:
                              type: string
                            result:
                              type: string
                            reversed_at:
                              type: string
                            schema_version:
                              type: string
                            source:
                              properties:
                                account:
                                  properties:
                                    currency:
                                      type: string
                                    type:
                                      type: string
                                    value:
                                      type: string
                                  required:
                                    - type
                                    - value
                                  type: object
                                identification:
                                  properties:
                                    number:
                                      type: string
                                    type:
                                      type: string
                                  required:
                                    - type
                                    - number
                                  type: object
                                name:
                                  type: string
                              required:
                                - account
                                - name
                                - identification
                              type: object
                            status:
                              type: string
                            status_detail:
                              type: string
                            succeeded_at:
                              type: string
                            type:
                              type: string
                            updated_at:
                              type: string
                          required:
                            - schema_version
                            - payment_id
                            - public_id
                            - type
                            - payment_method_code
                            - status
                            - result
                            - succeeded_at
                            - has_reversal
                            - reversed_at
                            - created_at
                            - updated_at
                            - amount
                            - source
                            - destination
                            - client_reference
                            - external_reference
                            - provider
                            - error
                          type: object
                        type: array
                      pagination:
                        properties:
                          limit:
                            type: integer
                          next_cursor:
                            type: string
                        required:
                          - limit
                        type: object
                      schema_version:
                        type: string
                    required:
                      - schema_version
                      - items
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 5
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "429":
          description: Too many requests. Please retry after a short delay.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 8
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                payload: null
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 6
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
        "503":
          description: A required service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 7
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
    post:
      summary: Create payment
      description: |
        Creates a payment using an authorized internal source account. Processing may be asynchronous; HTTP 201 does not imply the payment is finalized.
        `source.identification.number` and `destination.identification.number` are stored in public form (the submitted digits, without SINPE hyphens) and returned on later payment reads. The GX/SINPE hyphenated form is used only internally and is not the public contract.
        Idempotency-Key is optional; if omitted, each request is treated as a new attempt. A repeated `client_reference` returns 409 PAYMENT_DUPLICATE when an in-flight or completed payment already uses it; a prior `failed` (or rejected/cancelled/expired) payment does not block a retry with the same `client_reference`. If Idempotency-Key is provided, the same key with the same payload replays the prior response; a different payload with the same key returns 409 IDEMPOTENCY_CONFLICT.
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 256
            pattern: ^[A-Za-z0-9._-]+$
            description: Optional opaque client key for safe retries. When omitted, each call is a new attempt (duplicates are detected by client_reference on in-flight or completed payments). Reusing a key with a different body returns 409.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: The resource was created successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      created_at:
                        type: string
                      payment_id:
                        type: string
                      payment_method_code:
                        type: string
                      public_id:
                        type: string
                      status:
                        type: string
                      status_detail:
                        type: string
                    required:
                      - payment_id
                      - public_id
                      - status
                      - status_detail
                      - payment_method_code
                      - created_at
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - CREATED
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid payment request payload.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PAYMENT_INVALID_PAYLOAD
                      - INVALID_PAYMENT_METHOD
                      - INVALID_ACCOUNT_TYPE
                      - ACCOUNT_INVALID
                      - ACCOUNT_HOLDER_MISMATCH
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PAYMENT_INVALID_PAYLOAD:
                  $ref: "#/components/examples/Error_PAYMENT_INVALID_PAYLOAD"
                Error_INVALID_PAYMENT_METHOD:
                  $ref: "#/components/examples/Error_INVALID_PAYMENT_METHOD"
                Error_INVALID_ACCOUNT_TYPE:
                  $ref: "#/components/examples/Error_INVALID_ACCOUNT_TYPE"
                Error_ACCOUNT_INVALID:
                  $ref: "#/components/examples/Error_ACCOUNT_INVALID"
                Error_ACCOUNT_HOLDER_MISMATCH:
                  $ref: "#/components/examples/Error_ACCOUNT_HOLDER_MISMATCH"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PAYMENT_INVALID_PAYLOAD
                  message: Invalid payment request payload.
                http_status_code: 400
                message: Invalid payment request payload.
                payload: null
                response_code: PAYMENT_INVALID_PAYLOAD
                success: false
          x-error-codes:
            - number: 4
              code: PAYMENT_INVALID_PAYLOAD
              message: Invalid payment request payload.
            - number: 5
              code: INVALID_PAYMENT_METHOD
              message: Invalid or unsupported payment method.
            - number: 6
              code: INVALID_ACCOUNT_TYPE
              message: Unsupported or invalid account type.
            - number: 8
              code: ACCOUNT_INVALID
              message: The account is invalid or not enabled for the service.
            - number: 9
              code: ACCOUNT_HOLDER_MISMATCH
              message: Account holder does not match the provided identification or name.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 7
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          content:
            application/json:
              examples:
                Error_ACCOUNT_NOT_FOUND:
                  $ref: "#/components/examples/Error_ACCOUNT_NOT_FOUND"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - ACCOUNT_NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: ACCOUNT_NOT_FOUND
                  message: Account not found.
                http_status_code: 404
                message: Account not found.
                payload: null
                response_code: ACCOUNT_NOT_FOUND
                success: false
          x-error-codes:
            - number: 10
              code: ACCOUNT_NOT_FOUND
              message: Account not found.
          description: Account not found.
        "409":
          description: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - IDEMPOTENCY_CONFLICT
                      - PAYMENT_DUPLICATE
                      - CONFLICT
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_IDEMPOTENCY_CONFLICT:
                  $ref: "#/components/examples/Error_IDEMPOTENCY_CONFLICT"
                Error_PAYMENT_DUPLICATE:
                  $ref: "#/components/examples/Error_PAYMENT_DUPLICATE"
                Error_CONFLICT:
                  $ref: "#/components/examples/Error_CONFLICT"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: IDEMPOTENCY_CONFLICT
                  message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
                http_status_code: 409
                message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
                payload: null
                response_code: IDEMPOTENCY_CONFLICT
                success: false
          x-error-codes:
            - number: 11
              code: IDEMPOTENCY_CONFLICT
              message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
            - number: 12
              code: PAYMENT_DUPLICATE
              message: An in-flight or completed payment with this client_reference already exists.
            - number: 13
              code: CONFLICT
              message: The request conflicts with the current state.
        "422":
          content:
            application/json:
              examples:
                Error_INSUFFICIENT_FUNDS:
                  $ref: "#/components/examples/Error_INSUFFICIENT_FUNDS"
                Error_LIMIT_EXCEEDED:
                  $ref: "#/components/examples/Error_LIMIT_EXCEEDED"
                Error_UNPROCESSABLE_ENTITY:
                  $ref: "#/components/examples/Error_UNPROCESSABLE_ENTITY"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INSUFFICIENT_FUNDS
                      - LIMIT_EXCEEDED
                      - UNPROCESSABLE_ENTITY
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INSUFFICIENT_FUNDS
                  message: Insufficient funds to complete the payment.
                http_status_code: 422
                message: Insufficient funds to complete the payment.
                payload: null
                response_code: INSUFFICIENT_FUNDS
                success: false
          x-error-codes:
            - number: 14
              code: INSUFFICIENT_FUNDS
              message: Insufficient funds to complete the payment.
            - number: 15
              code: LIMIT_EXCEEDED
              message: A transaction or accumulation limit was exceeded.
            - number: 16
              code: UNPROCESSABLE_ENTITY
              message: The request is well-formed but cannot be processed due to business rules.
          description: Insufficient funds to complete the payment.
        "429":
          description: Too many requests. Please retry after a short delay.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 19
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                payload: null
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 17
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
        "503":
          description: A required service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 18
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/transactions/payments/search:
    post:
      operationId: postPublicPaymentSearch
      summary: Search payment by identifier
      description: |
        Looks up a single payment within the supplied customer account by exactly one of:
        - `payment_id` (internal UUID)
        - `public_id` (numeric public identifier)
        - `client_reference` (partner reference sent at creation)

        Sending more than one identifier returns `400`. Response shape matches get-by-id
        (`schema_version`, payment-level `external_reference`, shared `provider` object,
        `provider.provider_status_*`, webhook-aligned `error`). Same public contract as
        `GET /transactions/payments`, including public `identification.number` for PIN
        payments created after public identification persistence.
        If several payments share a `client_reference` (failed attempt plus retry), the in-flight or completed payment is returned when one exists.
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchPaymentRequest"
            examples:
              byPaymentId:
                summary: Lookup by payment UUID
                value:
                  account:
                    type: IBAN
                    value: CR08036900101010933608
                  payment_id: 11111111-1111-1111-1111-111111111111
              byPublicId:
                summary: Lookup by public_id
                value:
                  account:
                    type: IBAN
                    value: CR08036900101010933608
                  public_id: "134729"
              byClientReference:
                summary: Lookup by client_reference
                value:
                  account:
                    type: IBAN
                    value: CR08036900101010933608
                  client_reference: INV-01082
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      amount:
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                        required:
                          - amount
                          - currency
                        type: object
                      client_reference:
                        type: string
                      created_at:
                        type: string
                      destination:
                        properties:
                          account:
                            properties:
                              currency:
                                type: string
                              type:
                                type: string
                              value:
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          identification:
                            properties:
                              number:
                                type: string
                              type:
                                type: string
                            required:
                              - type
                              - number
                            type: object
                          name:
                            type: string
                        required:
                          - account
                          - name
                          - identification
                        type: object
                      error:
                        properties:
                          domain:
                            type: string
                          platform:
                            properties:
                              code:
                                type: string
                              message:
                                type: string
                            required:
                              - code
                              - message
                            type: object
                        required:
                          - domain
                          - platform
                        type: object
                      external_reference:
                        type: string
                      has_reversal:
                        type: boolean
                      payment_id:
                        type: string
                      payment_method_code:
                        type: string
                      provider:
                        properties:
                          correlation_id:
                            type: string
                          occurred_at:
                            type: string
                          provider_status_code:
                            type: string
                          provider_status_desc:
                            type: string
                          provider_status_semantic:
                            type: string
                        required:
                          - correlation_id
                          - occurred_at
                          - provider_status_code
                          - provider_status_desc
                          - provider_status_semantic
                        type: object
                      public_id:
                        type: string
                      result:
                        type: string
                      reversed_at:
                        type: string
                      schema_version:
                        type: string
                      source:
                        properties:
                          account:
                            properties:
                              currency:
                                type: string
                              type:
                                type: string
                              value:
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          identification:
                            properties:
                              number:
                                type: string
                              type:
                                type: string
                            required:
                              - type
                              - number
                            type: object
                          name:
                            type: string
                        required:
                          - account
                          - name
                          - identification
                        type: object
                      status:
                        type: string
                      status_detail:
                        type: string
                      succeeded_at:
                        type: string
                      type:
                        type: string
                      updated_at:
                        type: string
                    required:
                      - schema_version
                      - payment_id
                      - public_id
                      - type
                      - payment_method_code
                      - status
                      - result
                      - succeeded_at
                      - has_reversal
                      - reversed_at
                      - created_at
                      - updated_at
                      - amount
                      - source
                      - destination
                      - client_reference
                      - external_reference
                      - provider
                      - error
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 5
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          description: Payment not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PAYMENT_NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PAYMENT_NOT_FOUND:
                  $ref: "#/components/examples/Error_PAYMENT_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PAYMENT_NOT_FOUND
                  message: Payment not found.
                http_status_code: 404
                message: Payment not found.
                payload: null
                response_code: PAYMENT_NOT_FOUND
                success: false
          x-error-codes:
            - number: 6
              code: PAYMENT_NOT_FOUND
              message: Payment not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 9
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                payload: null
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 7
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 8
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/transactions/payments/{payment_id}:
    get:
      operationId: getPublicPaymentById
      summary: Get payment by id
      description: |
        Returns a single payment using the same public contract as the list endpoint,
        including consolidated `result`, `succeeded_at`, `has_reversal`, and `error`.
        `error` is `null` when there is no failure information; it is an object only when
        `domain` / `platform` is present (`result` is `failed` or `reversed`), same shape
        as webhook `payment.failed` `payment.error`.
        `source` / `destination` use `null` for unknown nested fields and never expose ledger UUIDs.
        `identification.number` on PIN payments created after public identification persistence
        is the partner-submitted public number (digits, no SINPE hyphens). Older payments may
        still return the hyphenated SINPE form from processing metadata.
        Use this as a webhook backup.

        Looks up a payment by either identifier:
        - `payment_id` (internal UUID)
        - `public_id` (numeric public identifier)

        For `client_reference`, use `POST /api/public/v1/transactions/payments/search`.
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: payment_id
          in: path
          required: true
          description: Internal payment UUID or numeric public_id.
          schema:
            type: string
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      amount:
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                        required:
                          - amount
                          - currency
                        type: object
                      client_reference:
                        type: string
                      created_at:
                        type: string
                      destination:
                        properties:
                          account:
                            properties:
                              currency:
                                type: string
                              type:
                                type: string
                              value:
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          identification:
                            properties:
                              number:
                                type: string
                              type:
                                type: string
                            required:
                              - type
                              - number
                            type: object
                          name:
                            type: string
                        required:
                          - account
                          - name
                          - identification
                        type: object
                      error:
                        properties:
                          domain:
                            type: string
                          platform:
                            properties:
                              code:
                                type: string
                              message:
                                type: string
                            required:
                              - code
                              - message
                            type: object
                        required:
                          - domain
                          - platform
                        type: object
                      external_reference:
                        type: string
                      has_reversal:
                        type: boolean
                      payment_id:
                        type: string
                      payment_method_code:
                        type: string
                      provider:
                        properties:
                          correlation_id:
                            type: string
                          occurred_at:
                            type: string
                          provider_status_code:
                            type: string
                          provider_status_desc:
                            type: string
                          provider_status_semantic:
                            type: string
                        required:
                          - correlation_id
                          - occurred_at
                          - provider_status_code
                          - provider_status_desc
                          - provider_status_semantic
                        type: object
                      public_id:
                        type: string
                      result:
                        type: string
                      reversed_at:
                        type: string
                      schema_version:
                        type: string
                      source:
                        properties:
                          account:
                            properties:
                              currency:
                                type: string
                              type:
                                type: string
                              value:
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          identification:
                            properties:
                              number:
                                type: string
                              type:
                                type: string
                            required:
                              - type
                              - number
                            type: object
                          name:
                            type: string
                        required:
                          - account
                          - name
                          - identification
                        type: object
                      status:
                        type: string
                      status_detail:
                        type: string
                      succeeded_at:
                        type: string
                      type:
                        type: string
                      updated_at:
                        type: string
                    required:
                      - schema_version
                      - payment_id
                      - public_id
                      - type
                      - payment_method_code
                      - status
                      - result
                      - succeeded_at
                      - has_reversal
                      - reversed_at
                      - created_at
                      - updated_at
                      - amount
                      - source
                      - destination
                      - client_reference
                      - external_reference
                      - provider
                      - error
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          content:
            application/json:
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
          description: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 5
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          description: Payment not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PAYMENT_NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PAYMENT_NOT_FOUND:
                  $ref: "#/components/examples/Error_PAYMENT_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PAYMENT_NOT_FOUND
                  message: Payment not found.
                http_status_code: 404
                message: Payment not found.
                payload: null
                response_code: PAYMENT_NOT_FOUND
                success: false
          x-error-codes:
            - number: 6
              code: PAYMENT_NOT_FOUND
              message: Payment not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 9
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                payload: null
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 7
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 8
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/accounts/validate:
    post:
      summary: Validate external account for a payment method
      description: |
        Validates a counterparty account (IBAN or phone) via the SINPE provider for the given payment method.
        Does not validate internal ledger accounts.
        When valid, `data.holder.id_type` uses the same identification catalog keys as
        `identification.type` in `POST /payments` (e.g. `cedula`, `juridica`, `dimex`).

        ## SINPE_MOVIL field availability (expected, stable)

        For `payment_method_code = SINPE_MOVIL`, the backing wallet operation
        (`ObtenerInfoMonedero`) does not return identification type or institution name.
        A successful validation **may** therefore return:

        - `data.holder.id_type` = `unknown`
        - `data.financial_institution.entity_name` = `""` (empty string)

        This is **expected, stable behavior**, not a mapping bug or a transient provider error.
        PIN (`ObtenerInformacionCuentaSinpe`) does populate both fields.

        Integrators must not report these values as defects, and must not assume that
        `holder.id_type` or `financial_institution.entity_name` are always populated
        when `is_valid` is true.

        ## SINPE rejection codes (`data.rejection`)

        When `is_valid` is `false`, `data.rejection` explains why (see the `rejected`
        example on the `200` response below). `rejection.code` is one of a fixed set of
        normalized semantics (see the `WebhookRejection.code` schema enum). **Most rows in
        the table below do NOT get a distinct `code`** — only a subset of `reason_code`
        values has a dedicated semantic; every other `reason_code`, even one listed below
        with a specific `message`, returns `code = SINPE_REJECTED` (e.g. `reason_code = 21`
        "fondos insuficientes" still returns `SINPE_REJECTED`). This same object and
        catalog is also used by the `payment.failed` webhook's `rejection` field.
        A `reason_code` not listed here at all still produces a response — `message` falls
        back to a generic text and `code` falls back to `SINPE_REJECTED`.

        **Cuenta / perfil / límites**

        | Code | Message |
        |---|---|
        | 21 | Cuenta Cliente con fondos insuficientes |
        | 22 | Cuenta Cliente no admite créditos |
        | 23 | Cuenta Cliente cerrada |
        | 24 | Cuenta Cliente inactiva |
        | 25 | Cuenta Cliente no admite débitos |
        | 26 | Cuenta Cliente no es de fondos |
        | 27 | Moneda de la Cuenta Cliente no corresponde |
        | 28 | Cuenta cliente no existe |
        | 29 | Cuenta Cliente no registrada en el SINPE |
        | 30 | Cuenta Cliente no habilitada para el servicio |
        | 31 | Cuenta Cliente bloqueada |
        | 32 | Id cliente destino no coincide con registrado en la entidad |
        | 33 | Nombre del cliente destino no coincide con el registrado en la entidad |
        | 34 | Cuenta Cliente en proceso de cierre |
        | 35 | Cuenta Cliente embargada |
        | 36 | Cuenta Cliente con retención judicial |
        | 37 | Cuenta de expediente simplificado no permite el monto indicado |
        | 38 | Límite transaccional de la Cuenta Cliente excedido |
        | 39 | Cuenta Cliente incorrecta |
        | 40 | IBAN de la cuenta destino inválido |
        | 41 | IBAN de la cuenta origen inválido |
        | 42 | Tipo de cuenta no permite la transacción |
        | 43 | Cuenta Cliente no pertenece a la entidad indicada |
        | 44 | Producto de la cuenta no admite el servicio |
        | 45 | Cuenta Cliente en estado de cancelación |
        | 46 | Cuenta Cliente restringida por política de la entidad |
        | 47 | Cuenta Cliente no permite pagos inmediatos |
        | 48 | Cuenta Cliente no permite SINPE Móvil |
        | 49 | Titular de la cuenta destino fallecido |
        | 50 | Cuenta Cliente consolidada o migrada |
        | 51 | Identificación del cliente origen no coincide |
        | 52 | Identificación del cliente destino inválida |
        | 53 | Cliente destino no autorizado para recibir el pago |
        | 54 | Cliente origen no autorizado para enviar el pago |
        | 55 | Perfil del cliente origen no permite la transacción |
        | 56 | Monto inferior al mínimo permitido |
        | 57 | Monto superior al máximo permitido |
        | 58 | Cantidad de transacciones diarias excedida |
        | 59 | Cantidad de transacciones mensuales excedida |
        | 60 | Límite acumulado diario excedido |
        | 61 | Límite acumulado mensual excedido |
        | 62 | Comisión no pudo ser aplicada |
        | 63 | Tipo de cambio no disponible |
        | 64 | Transacción rechazada por control de lavado de dinero |
        | 65 | Transacción rechazada por listas de control |
        | 66 | Transacción en revisión de cumplimiento |
        | 67 | Documento de respaldo requerido no presente |
        | 68 | Firma o autenticación inválida |
        | 69 | Token o segundo factor inválido |
        | 70 | Sesión de usuario expirada |
        | 71 | Usuario no autorizado para el canal |
        | 72 | Dispositivo no registrado |
        | 73 | Geolocalización no permitida |
        | 74 | Operación no soportada en la moneda indicada |
        | 75 | Operación no soportada para el tipo de cliente |
        | 76 | Problemas de comunicación |
        | 77 | Tiempo de espera agotado en la entidad origen |
        | 78 | Tiempo de espera agotado en el SINPE |
        | 79 | Error interno de la entidad origen |
        | 80 | Error interno de la entidad destino |
        | 81 | Entidad origen no disponible |
        | 82 | Entidad destino no encontrada |
        | 83 | Problemas en la respuesta del destino |
        | 84 | Respuesta de la entidad origen incorrecta |
        | 85 | Mensaje con formato electrónico inválido |
        | 86 | Versión del estándar electrónico no soportada |
        | 87 | Campo obligatorio no informado |
        | 88 | Campo con valor fuera de catálogo |
        | 89 | Checksum o integridad del mensaje inválida |
        | 90 | Referencia SINPE duplicada |
        | 91 | Moneda no corresponde |
        | 92 | Transacción no autorizada por entidad destino |
        | 93 | Transacción no autorizada por cliente destino |
        | 94 | Transacción no autorizada por entidad origen |
        | 95 | Transacción no autorizada por cliente origen |
        | 96 | Reverso no permitido para el estado de la transacción |
        | 97 | Reverso ya aplicado |
        | 98 | Confirmación no permitida para el estado de la transacción |
        | 99 | Liquidación no permitida para el estado de la transacción |
        | 100 | Entidad Destino no disponible para procesar en tiempo real |
        | 101 | Entidad origen no disponible para procesar en tiempo real |
        | 102 | Servicio PIN no habilitado para la entidad destino |
        | 103 | Servicio PIN no habilitado para la entidad origen |
        | 104 | Código de entidad destino inválido |
        | 105 | Código de entidad origen inválido |
        | 106 | Código de país de la entidad destino inválido |
        | 107 | Código de país de la entidad origen inválido |
        | 108 | Número de referencia interna inválido |
        | 109 | Número de referencia SINPE inválido |
        | 110 | Transacción no se encuentra en un estado que permita la consulta |

        **Compensación con entidad destino**

        | Code | Message |
        |---|---|
        | 201 | Tiempo respuesta excedido por la entidad destino |
        | 202 | Respuesta de la entidad destino incorrecta según el estándar electrónico |
        | 203 | Se recibió una excepción de la entidad destino |
        | 204 | Error de comunicación con la entidad destino |
        | 205 | Falló procesamiento en el SINPE |
        | 206 | Transacción no autorizada por cliente destino |
        | 207 | Perfil transaccional del cliente destino no permite recibir el pago |
        | 208 | Falló la acreditación en la cuenta destino |
        | 209 | Falló el débito en la cuenta origen |
        | 210 | Conciliación de la transacción no fue posible |

        **Identificación**

        | Code | Message |
        |---|---|
        | 801 | Identificación inválida |
        | 802 | Identificación del cliente origen no encontrada |
        | 803 | Identificación del cliente destino no encontrada |
        | 804 | Identificación no vigente |
        | 805 | Identificación vencida |
        | 806 | Identificación no corresponde al tipo indicado |
        | 807 | Tipo de identificación inválido |
        | 808 | País de la identificación no soportado |
        | 809 | Identificación de menor de edad no permitida |
        | 810 | Identificación de persona jurídica no permitida para el servicio |

        **Validación de formato / Core Bancario**

        | Code | Message |
        |---|---|
        | 1001 | Cuenta cliente activa |
        | 1002 | El Id de cliente destino no cumple con el formato esperado por el SINPE |
        | 1003 | El Id de cliente origen no fue informado |
        | 1004 | El Id de cliente origen no cumple con el formato esperado por el SINPE |
        | 1005 | Monto con formato inválido |
        | 1006 | Moneda con formato inválido |
        | 1007 | Problemas de comunicación con el Core Bancario |
        | 1008 | Core Bancario no disponible |
        | 1009 | El valor para el campo no puede ser nulo o infringir su longitud mínima o máxima |
        | 1010 | El valor para el campo no corresponde al tipo de dato esperado |
        | 1011 | El valor para el campo no corresponde al catálogo permitido |
        | 1012 | Fecha con formato inválido |
        | 1013 | Hora con formato inválido |
        | 1014 | Número de referencia con formato inválido |
        | 1015 | IBAN con formato inválido |

        **Canal / tipo de identificación**

        | Code | Message |
        |---|---|
        | 1040 | Canal no informado |
        | 1041 | Canal inválido |
        | 1042 | Canal no corresponde |
        | 1043 | Canal no habilitado para la entidad |
        | 1044 | Canal no habilitado para el servicio |
        | 1045 | El formato de la identificación es inválido |
        | 1046 | Tipo de identificación no informado |
        | 1080 | Tipo de identificación no corresponde al cliente origen |
        | 1081 | Tipo de identificación no corresponde al cliente destino |
        | 1082 | Tipo de identificación no vigente |
        | 1083 | Tipo de identificación no soportado por el servicio |
        | 1084 | Tipo de identificación inválido |
        | 1085 | Tipo de identificación no soportado por la entidad |

        **SINPE Móvil (monedero)**

        | Code | Message |
        |---|---|
        | 15300 | El número de teléfono origen indicado es inválido |
        | 15301 | El número de teléfono origen no tiene activo el Servicio Monedero |
        | 15302 | El número de teléfono destino indicado es inválido |
        | 15303 | El número de teléfono destino no está registrado en el padrón móvil del BCCR |
        | 15304 | No es posible inactivar el monedero indicado pues no existe |
        | 15305 | El número de teléfono indicado ya se encuentra activo como monedero en el padrón local |

        ⚠️ This catalog is under review — some entries (notably `208` and `209`)
        are known to be pending verification against the official SINPE source and
        may be corrected in a future revision without notice.
      tags:
        - Payments
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountValidateRequest"
            examples:
              pin:
                summary: PIN (external IBAN)
                value:
                  payment_method_code: PIN
                  account:
                    type: IBAN
                    value: CR16010400000000000031
              sinpe_movil:
                summary: SINPE_MOVIL (phone wallet)
                value:
                  payment_method_code: SINPE_MOVIL
                  account:
                    type: PHONE
                    value: "88887777"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      account:
                        properties:
                          currency:
                            type: string
                          product_name:
                            type: string
                          type:
                            type: string
                          value:
                            type: string
                        required:
                          - type
                          - value
                          - currency
                          - product_name
                        type: object
                      financial_institution:
                        properties:
                          country_code:
                            type: string
                          entity_code:
                            type: string
                          entity_name:
                            type: string
                        required:
                          - country_code
                          - entity_code
                          - entity_name
                        type: object
                      holder:
                        properties:
                          id_number:
                            type: string
                          id_type:
                            type: string
                          name:
                            type: string
                        required:
                          - name
                          - id_type
                          - id_number
                        type: object
                      is_valid:
                        type: boolean
                      provider:
                        properties:
                          correlation_id:
                            type: string
                          occurred_at:
                            type: string
                          operation:
                            type: string
                        required:
                          - operation
                        type: object
                      rejection:
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                          reason_code:
                            type: string
                        required:
                          - code
                          - reason_code
                          - message
                        type: object
                    required:
                      - is_valid
                      - account
                      - holder
                      - financial_institution
                      - rejection
                      - provider
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INVALID_REQUEST
                      - INVALID_ACCOUNT_TYPE
                      - INVALID_ACCOUNT_FORMAT
                      - INVALID_PAYMENT_METHOD
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
                Error_INVALID_ACCOUNT_TYPE:
                  $ref: "#/components/examples/Error_INVALID_ACCOUNT_TYPE"
                Error_INVALID_ACCOUNT_FORMAT:
                  $ref: "#/components/examples/Error_INVALID_ACCOUNT_FORMAT"
                Error_INVALID_PAYMENT_METHOD:
                  $ref: "#/components/examples/Error_INVALID_PAYMENT_METHOD"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
            - number: 5
              code: INVALID_ACCOUNT_TYPE
              message: Unsupported or invalid account type.
            - number: 6
              code: INVALID_ACCOUNT_FORMAT
              message: Invalid account format.
            - number: 7
              code: INVALID_PAYMENT_METHOD
              message: Invalid or unsupported payment method.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 8
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "422":
          content:
            application/json:
              examples:
                Error_UNPROCESSABLE_ENTITY:
                  $ref: "#/components/examples/Error_UNPROCESSABLE_ENTITY"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - UNPROCESSABLE_ENTITY
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNPROCESSABLE_ENTITY
                  message: The request is well-formed but cannot be processed due to business rules.
                http_status_code: 422
                message: The request is well-formed but cannot be processed due to business rules.
                response_code: UNPROCESSABLE_ENTITY
                success: false
          x-error-codes:
            - number: 9
              code: UNPROCESSABLE_ENTITY
              message: The request is well-formed but cannot be processed due to business rules.
          description: The request is well-formed but cannot be processed due to business rules.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 11
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 10
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
  /api/public/v1/accounts/balances:
    get:
      summary: List balances for accessible accounts
      description: |
        Returns paginated account balances (`account`, `amounts`, `as_of`). This endpoint checks
        the current balance in real time and may respond more slowly than `GET /accounts`.
        For account attributes without amounts, use `GET /accounts`.

        Optional filters use the public account identification standard: `type` + `value`
        (identifier scheme + value). `type` is not the internal account classification.
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - $ref: "#/components/parameters/AccountIdentifierTypeOptional"
        - $ref: "#/components/parameters/AccountIdentifierValueOptional"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            account:
                              properties:
                                currency:
                                  type: string
                                type:
                                  type: string
                                value:
                                  type: string
                              required:
                                - type
                                - value
                              type: object
                            amounts:
                              properties:
                                available:
                                  type: string
                                inbound_in_transit:
                                  type: string
                                outbound_in_transit:
                                  type: string
                                posted:
                                  type: string
                              required:
                                - available
                                - posted
                                - inbound_in_transit
                                - outbound_in_transit
                              type: object
                            as_of:
                              type: string
                          required:
                            - account
                            - amounts
                            - as_of
                          type: object
                        type: array
                      pagination:
                        properties:
                          limit:
                            type: integer
                          offset:
                            type: integer
                          total:
                            type: integer
                        required:
                          - limit
                          - offset
                          - total
                        type: object
                    required:
                      - items
                      - pagination
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 6
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_NOT_FOUND:
                  $ref: "#/components/examples/Error_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                http_status_code: 404
                message: The requested resource was not found.
                payload: null
                response_code: NOT_FOUND
                success: false
          x-error-codes:
            - number: 5
              code: NOT_FOUND
              message: The requested resource was not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 8
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Dependency error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorResponse"
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 7
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/accounts:
    get:
      summary: List accessible accounts without balances
      description: |
        Returns paginated accessible accounts without querying current balances.
        Each item is account attributes only (`account.type`, `account.value`, `account.currency`).
        `amounts` and `as_of` are not included; use `GET /accounts/balances` or `POST /accounts/balance`.

        Optional filters use the public account identification standard: `type` + `value`
        (identifier scheme + value). `type` is not the internal account classification.
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - $ref: "#/components/parameters/AccountIdentifierTypeOptional"
        - $ref: "#/components/parameters/AccountIdentifierValueOptional"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            account:
                              properties:
                                currency:
                                  type: string
                                type:
                                  type: string
                                value:
                                  type: string
                              required:
                                - type
                                - value
                              type: object
                          required:
                            - account
                          type: object
                        type: array
                      pagination:
                        properties:
                          limit:
                            type: integer
                          offset:
                            type: integer
                          total:
                            type: integer
                        required:
                          - limit
                          - offset
                          - total
                        type: object
                    required:
                      - items
                      - pagination
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_NOT_FOUND:
                  $ref: "#/components/examples/Error_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                http_status_code: 404
                message: The requested resource was not found.
                payload: null
                response_code: NOT_FOUND
                success: false
          x-error-codes:
            - number: 5
              code: NOT_FOUND
              message: The requested resource was not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 7
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Dependency error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorResponse"
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 6
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/accounts/balance:
    post:
      summary: Get account balance
      description: |
        Returns a single account snapshot with `amounts` and `as_of`.
        For account attributes without balances, use `GET /accounts`.
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetAccountBalanceRequest"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      account:
                        properties:
                          currency:
                            type: string
                          type:
                            type: string
                          value:
                            type: string
                        required:
                          - type
                          - value
                        type: object
                      amounts:
                        properties:
                          available:
                            type: string
                          inbound_in_transit:
                            type: string
                          outbound_in_transit:
                            type: string
                          posted:
                            type: string
                        required:
                          - available
                          - posted
                          - inbound_in_transit
                          - outbound_in_transit
                        type: object
                      as_of:
                        type: string
                    required:
                      - account
                      - amounts
                      - as_of
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 5
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          description: Account not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - ACCOUNT_NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_ACCOUNT_NOT_FOUND:
                  $ref: "#/components/examples/Error_ACCOUNT_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: ACCOUNT_NOT_FOUND
                  message: Account not found.
                http_status_code: 404
                message: Account not found.
                payload: null
                response_code: ACCOUNT_NOT_FOUND
                success: false
          x-error-codes:
            - number: 6
              code: ACCOUNT_NOT_FOUND
              message: Account not found.
        "422":
          content:
            application/json:
              examples:
                Error_ACCOUNT_NOT_CONFIGURED:
                  $ref: "#/components/examples/Error_ACCOUNT_NOT_CONFIGURED"
                Error_UNPROCESSABLE_ENTITY:
                  $ref: "#/components/examples/Error_UNPROCESSABLE_ENTITY"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - ACCOUNT_NOT_CONFIGURED
                      - UNPROCESSABLE_ENTITY
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: ACCOUNT_NOT_CONFIGURED
                  message: This account is not mapped in the system. Please contact support to configure it correctly.
                http_status_code: 422
                message: This account is not mapped in the system. Please contact support to configure it correctly.
                payload: null
                response_code: ACCOUNT_NOT_CONFIGURED
                success: false
          x-error-codes:
            - number: 7
              code: ACCOUNT_NOT_CONFIGURED
              message: This account is not mapped in the system. Please contact support to configure it correctly.
            - number: 8
              code: UNPROCESSABLE_ENTITY
              message: The request is well-formed but cannot be processed due to business rules.
          description: This account is not mapped in the system. Please contact support to configure it correctly.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 11
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Unable to complete the request with the payment provider. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - PROVIDER_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_PROVIDER_ERROR:
                  $ref: "#/components/examples/Error_PROVIDER_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: PROVIDER_ERROR
                  message: Unable to complete the request with the payment provider. Please try again later.
                http_status_code: 502
                message: Unable to complete the request with the payment provider. Please try again later.
                payload: null
                response_code: PROVIDER_ERROR
                success: false
          x-error-codes:
            - number: 9
              code: PROVIDER_ERROR
              message: Unable to complete the request with the payment provider. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 10
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/accounts/statements:
    post:
      summary: Request account statement generation
      description: |
        Creates an asynchronous account statement request for a date range (max 60 days).
        Identify the account with `account.type` + `account.value` (identifier scheme + value,
        e.g. IBAN). This follows the public account identification standard.
        `account.type` is not the internal account classification.
        Returns `{request_id, status: PENDING}` immediately.
        Poll `GET /accounts/statements/{request_id}` for status; when `DONE`, the response includes a signed `download_url`.
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 256
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAccountStatementRequest"
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      request_id:
                        type: string
                      status:
                        type: string
                    required:
                      - request_id
                      - status
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "202":
          description: Statement request accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAccountStatementResponse"
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                      - ACCOUNT_ACCESS_DENIED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
                Error_ACCOUNT_ACCESS_DENIED:
                  $ref: "#/components/examples/Error_ACCOUNT_ACCESS_DENIED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
            - number: 5
              code: ACCOUNT_ACCESS_DENIED
              message: The actor does not have access to the requested account.
        "404":
          content:
            application/json:
              examples:
                Error_NOT_FOUND:
                  $ref: "#/components/examples/Error_NOT_FOUND"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                http_status_code: 404
                message: The requested resource was not found.
                payload: null
                response_code: NOT_FOUND
                success: false
          x-error-codes:
            - number: 7
              code: NOT_FOUND
              message: The requested resource was not found.
          description: The requested resource was not found.
        "409":
          content:
            application/json:
              examples:
                Error_IDEMPOTENCY_CONFLICT:
                  $ref: "#/components/examples/Error_IDEMPOTENCY_CONFLICT"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - IDEMPOTENCY_CONFLICT
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: IDEMPOTENCY_CONFLICT
                  message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
                http_status_code: 409
                message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
                payload: null
                response_code: IDEMPOTENCY_CONFLICT
                success: false
          x-error-codes:
            - number: 6
              code: IDEMPOTENCY_CONFLICT
              message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
          description: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 9
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Dependency error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorResponse"
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 8
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/accounts/statements/{request_id}:
    get:
      summary: Get account statement request status
      description: |
        Returns request status. When `DONE`, includes a GCS signed `download_url` (48h from generation) and `expires_at`.
        When `ERROR`, includes a generic `message` without internal details.
        Unknown or unauthorized `request_id` returns 404.
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      download_url:
                        type: string
                      expires_at:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      status:
                        type: string
                    required:
                      - request_id
                      - status
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_NOT_FOUND:
                  $ref: "#/components/examples/Error_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                http_status_code: 404
                message: The requested resource was not found.
                payload: null
                response_code: NOT_FOUND
                success: false
          x-error-codes:
            - number: 4
              code: NOT_FOUND
              message: The requested resource was not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 6
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 5
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/webhook/destination:
    post:
      summary: Create webhook destination
      description: |
        Valid fields depend on `destination_kind` and `scope_kind`. Send only the fields that apply to your combination; other scope fields must be omitted (not null placeholders).

        **Event payloads**
        Inspect outbound contracts with
        `GET /api/public/v1/webhook/event-contracts/{event_type}`
        (`payin.posted`, `payment.succeeded`, `payment.failed`, `payment.reversed`).

        **destination_kind**
        - `EXTERNAL_WEBHOOK` (only kind available on the public API): requires `webhook_url` (must start with `https://`) and `secret_ref`. Optional delivery tuning (`timeout_ms`, `max_attempts`). Payloads are always encrypted with `AES_GCM` using `secret_ref`; the HTTP body is `{"data":"<ciphertext>"}`.
        - `INTERNAL` is reserved for platform administration and cannot be created through this endpoint.

        **scope_kind**
        - `TENANT`: omit `scope_account_id`, `scope_owner_type`, and `scope_owner_id`.
        - `ACCOUNT`: require `scope_account_id`; omit owner fields.
        - `OWNER`: require `scope_owner_type` and `scope_owner_id`; omit `scope_account_id`. `scope_owner_type` is one of `tenant`, `partner`, `user`, `platform`, `customer` (lowercase in payload).

        ## Webhook encryption (EXTERNAL_WEBHOOK)

        Deliveries always send `Content-Type: application/json` and `Accept: application/json`.

        The HTTP body is always `{"data": "<base64>"}`. The base64-decoded bytes are:

        ```
        nonce (12 bytes, random) || AES-256-GCM ciphertext || 16-byte auth tag
        ```

        ```
        key                   = SHA256(secret_ref)              # 32 bytes → AES-256
        wire                  = base64_decode(data)
        nonce, sealed         = wire[:12], wire[12:]             # sealed = ciphertext || tag
        plaintext             = AES-GCM-Open(key, nonce, sealed, additional_data = none)
        ```

        No additional authenticated data (AAD) is used. `plaintext` is the same JSON
        envelope documented per event type in
        `GET /webhook/event-contracts/{event_type}` — decrypt first, then apply that
        contract. Authenticity is provided by the GCM auth tag (decryption fails if the
        body was tampered with).

        Deduplicate retries using `event.event_id` in the payload envelope — delivery
        retries can redeliver the same event with the same `event_id`.
      tags:
        - Webhooks
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddWebhookDestinationRequest"
            examples:
              external_webhook_tenant:
                summary: HTTPS callback for all events in scope tenant
                value:
                  feature_id: 11111111-1111-1111-1111-111111111111
                  destination_kind: EXTERNAL_WEBHOOK
                  scope_kind: TENANT
      responses:
        "201":
          description: The resource was created successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      created_at:
                        type: string
                      destination_kind:
                        type: string
                      destination_ref:
                        type: string
                      feature_id:
                        type: string
                      id:
                        type: string
                      is_enabled:
                        type: boolean
                      max_attempts:
                        type: integer
                      replay_window_sec:
                        type: integer
                      scope_account_id:
                        type: string
                      scope_kind:
                        type: string
                      scope_owner_id:
                        type: string
                      scope_owner_type:
                        type: string
                      secret_ref:
                        type: string
                      signature_algo:
                        type: string
                      timeout_ms:
                        type: integer
                      updated_at:
                        type: string
                      webhook_url:
                        type: string
                    required:
                      - id
                      - feature_id
                      - is_enabled
                      - destination_kind
                      - signature_algo
                      - replay_window_sec
                      - scope_kind
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - CREATED
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "400":
          description: Invalid request. Check the required fields and try again.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INVALID_REQUEST
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INVALID_REQUEST:
                  $ref: "#/components/examples/Error_INVALID_REQUEST"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INVALID_REQUEST
                  message: Invalid request. Check the required fields and try again.
                http_status_code: 400
                message: Invalid request. Check the required fields and try again.
                payload: null
                response_code: INVALID_REQUEST
                success: false
          x-error-codes:
            - number: 4
              code: INVALID_REQUEST
              message: Invalid request. Check the required fields and try again.
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 6
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 5
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/webhook/features:
    get:
      summary: List webhook features by payment method
      description: |
        Returns feature IDs and the `event_types` each feature can emit.
        Tenant scope is taken from the access token; clients must not send `tenant_id`.

        **Naming:** `event_types` use `payment.*` for resource-level outcomes
        (`payment.succeeded`, `payment.failed`, `payment.reversed`) and `payin.posted` for the inbound
        direction only (funds received). There is no `payout.posted` and no
        `transaction.*` events. The delivered JSON object is always `payment`.

        Inspect payload shapes with `GET /api/public/v1/webhook/event-contracts/{event_type}`
        (`payin.posted`, `payment.succeeded`, `payment.failed`, `payment.reversed`).
      tags:
        - Webhooks
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: country_code
          in: query
          required: false
          schema:
            type: string
        - name: payment_method_code
          in: query
          required: false
          schema:
            type: string
        - name: webhook_enabled
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            event_types:
                              items:
                                type: string
                              type: array
                            id:
                              type: string
                          required:
                            - id
                            - event_types
                          type: object
                        type: array
                    required:
                      - items
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 5
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 4
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/webhook/event-contracts/{event_type}:
    get:
      summary: Webhook event contract
      description: |
        Returns the outbound webhook payload contract for one public event type
        (`schema_version` 1.0.0). The envelope object is always `payment` (never
        `payin`, `payout`, or `transaction`).

        **When to use each name**
        - **payment** — resource and envelope. Outcome events: `payment.succeeded`,
          `payment.failed`, `payment.reversed` (both PAYIN and PAYOUT). Correlate with REST
          `/transactions/payments`.
        - **payin / payout** — direction (`PAYIN` inbound, `PAYOUT` outbound).
          `payin.posted` is inbound-only (ledger posted / funds received).
          There is no public `payout.posted`.
        - **transaction** — REST path prefix only. Not used in webhook `event_type`
          or payload objects.

        Supported `event_type` values:
        - `payin.posted` — inbound (PAYIN) payment reached public status `posted`.
          Envelope field is `payment`. `payment.local_payment` is a JSON boolean
          (`true`/`false`), not a string.
        - `payment.succeeded` — the provider confirmed success for a payment (PAYIN or
          PAYOUT; PIN or SINPE Móvil). Resource-level outcome, not direction-specific.
        - `payment.failed` — processing ended in a definitive failure (public `status=failed`),
          with structured `payment.error` (`domain` / `platform`). When the provider rejected
          the payment, the envelope also includes `rejection`. Not used for later reversals.
        - `payment.reversed` — subsequent reversal of a payment that already progressed
          (typically `status=posted` or `confirmed`). REST `result=reversed` and
          `has_reversal=true`. Processing `status` is unchanged. Not a `payment.failed`.

        Unknown `event_type` values (including internal-only `payment.status_changed`)
        return `404`.

        ## SINPE rejection codes (`rejection`, only on `payment.failed`)

        When `event_type = payment.failed` and the provider rejected the payment, the
        envelope includes `rejection` (same object and catalog as `data.rejection` on
        `POST /accounts/validate`). `rejection.code` is one of a fixed set of normalized
        semantics (see the `WebhookRejection.code` schema enum). **Most rows in the table
        below do NOT get a distinct `code`** — only a subset of `reason_code` values has a
        dedicated semantic; every other `reason_code`, even one listed below with a specific
        `message`, returns `code = SINPE_REJECTED` (e.g. `reason_code = 21` "fondos
        insuficientes" still returns `SINPE_REJECTED`). A `reason_code` not listed here at
        all still produces a response — `message` falls back to a generic text and `code`
        falls back to `SINPE_REJECTED`.

        **Cuenta / perfil / límites**

        | Code | Message |
        |---|---|
        | 21 | Cuenta Cliente con fondos insuficientes |
        | 22 | Cuenta Cliente no admite créditos |
        | 23 | Cuenta Cliente cerrada |
        | 24 | Cuenta Cliente inactiva |
        | 25 | Cuenta Cliente no admite débitos |
        | 26 | Cuenta Cliente no es de fondos |
        | 27 | Moneda de la Cuenta Cliente no corresponde |
        | 28 | Cuenta cliente no existe |
        | 29 | Cuenta Cliente no registrada en el SINPE |
        | 30 | Cuenta Cliente no habilitada para el servicio |
        | 31 | Cuenta Cliente bloqueada |
        | 32 | Id cliente destino no coincide con registrado en la entidad |
        | 33 | Nombre del cliente destino no coincide con el registrado en la entidad |
        | 34 | Cuenta Cliente en proceso de cierre |
        | 35 | Cuenta Cliente embargada |
        | 36 | Cuenta Cliente con retención judicial |
        | 37 | Cuenta de expediente simplificado no permite el monto indicado |
        | 38 | Límite transaccional de la Cuenta Cliente excedido |
        | 39 | Cuenta Cliente incorrecta |
        | 40 | IBAN de la cuenta destino inválido |
        | 41 | IBAN de la cuenta origen inválido |
        | 42 | Tipo de cuenta no permite la transacción |
        | 43 | Cuenta Cliente no pertenece a la entidad indicada |
        | 44 | Producto de la cuenta no admite el servicio |
        | 45 | Cuenta Cliente en estado de cancelación |
        | 46 | Cuenta Cliente restringida por política de la entidad |
        | 47 | Cuenta Cliente no permite pagos inmediatos |
        | 48 | Cuenta Cliente no permite SINPE Móvil |
        | 49 | Titular de la cuenta destino fallecido |
        | 50 | Cuenta Cliente consolidada o migrada |
        | 51 | Identificación del cliente origen no coincide |
        | 52 | Identificación del cliente destino inválida |
        | 53 | Cliente destino no autorizado para recibir el pago |
        | 54 | Cliente origen no autorizado para enviar el pago |
        | 55 | Perfil del cliente origen no permite la transacción |
        | 56 | Monto inferior al mínimo permitido |
        | 57 | Monto superior al máximo permitido |
        | 58 | Cantidad de transacciones diarias excedida |
        | 59 | Cantidad de transacciones mensuales excedida |
        | 60 | Límite acumulado diario excedido |
        | 61 | Límite acumulado mensual excedido |
        | 62 | Comisión no pudo ser aplicada |
        | 63 | Tipo de cambio no disponible |
        | 64 | Transacción rechazada por control de lavado de dinero |
        | 65 | Transacción rechazada por listas de control |
        | 66 | Transacción en revisión de cumplimiento |
        | 67 | Documento de respaldo requerido no presente |
        | 68 | Firma o autenticación inválida |
        | 69 | Token o segundo factor inválido |
        | 70 | Sesión de usuario expirada |
        | 71 | Usuario no autorizado para el canal |
        | 72 | Dispositivo no registrado |
        | 73 | Geolocalización no permitida |
        | 74 | Operación no soportada en la moneda indicada |
        | 75 | Operación no soportada para el tipo de cliente |
        | 76 | Problemas de comunicación |
        | 77 | Tiempo de espera agotado en la entidad origen |
        | 78 | Tiempo de espera agotado en el SINPE |
        | 79 | Error interno de la entidad origen |
        | 80 | Error interno de la entidad destino |
        | 81 | Entidad origen no disponible |
        | 82 | Entidad destino no encontrada |
        | 83 | Problemas en la respuesta del destino |
        | 84 | Respuesta de la entidad origen incorrecta |
        | 85 | Mensaje con formato electrónico inválido |
        | 86 | Versión del estándar electrónico no soportada |
        | 87 | Campo obligatorio no informado |
        | 88 | Campo con valor fuera de catálogo |
        | 89 | Checksum o integridad del mensaje inválida |
        | 90 | Referencia SINPE duplicada |
        | 91 | Moneda no corresponde |
        | 92 | Transacción no autorizada por entidad destino |
        | 93 | Transacción no autorizada por cliente destino |
        | 94 | Transacción no autorizada por entidad origen |
        | 95 | Transacción no autorizada por cliente origen |
        | 96 | Reverso no permitido para el estado de la transacción |
        | 97 | Reverso ya aplicado |
        | 98 | Confirmación no permitida para el estado de la transacción |
        | 99 | Liquidación no permitida para el estado de la transacción |
        | 100 | Entidad Destino no disponible para procesar en tiempo real |
        | 101 | Entidad origen no disponible para procesar en tiempo real |
        | 102 | Servicio PIN no habilitado para la entidad destino |
        | 103 | Servicio PIN no habilitado para la entidad origen |
        | 104 | Código de entidad destino inválido |
        | 105 | Código de entidad origen inválido |
        | 106 | Código de país de la entidad destino inválido |
        | 107 | Código de país de la entidad origen inválido |
        | 108 | Número de referencia interna inválido |
        | 109 | Número de referencia SINPE inválido |
        | 110 | Transacción no se encuentra en un estado que permita la consulta |

        **Compensación con entidad destino**

        | Code | Message |
        |---|---|
        | 201 | Tiempo respuesta excedido por la entidad destino |
        | 202 | Respuesta de la entidad destino incorrecta según el estándar electrónico |
        | 203 | Se recibió una excepción de la entidad destino |
        | 204 | Error de comunicación con la entidad destino |
        | 205 | Falló procesamiento en el SINPE |
        | 206 | Transacción no autorizada por cliente destino |
        | 207 | Perfil transaccional del cliente destino no permite recibir el pago |
        | 208 | Falló la acreditación en la cuenta destino |
        | 209 | Falló el débito en la cuenta origen |
        | 210 | Conciliación de la transacción no fue posible |

        **Identificación**

        | Code | Message |
        |---|---|
        | 801 | Identificación inválida |
        | 802 | Identificación del cliente origen no encontrada |
        | 803 | Identificación del cliente destino no encontrada |
        | 804 | Identificación no vigente |
        | 805 | Identificación vencida |
        | 806 | Identificación no corresponde al tipo indicado |
        | 807 | Tipo de identificación inválido |
        | 808 | País de la identificación no soportado |
        | 809 | Identificación de menor de edad no permitida |
        | 810 | Identificación de persona jurídica no permitida para el servicio |

        **Validación de formato / Core Bancario**

        | Code | Message |
        |---|---|
        | 1001 | Cuenta cliente activa |
        | 1002 | El Id de cliente destino no cumple con el formato esperado por el SINPE |
        | 1003 | El Id de cliente origen no fue informado |
        | 1004 | El Id de cliente origen no cumple con el formato esperado por el SINPE |
        | 1005 | Monto con formato inválido |
        | 1006 | Moneda con formato inválido |
        | 1007 | Problemas de comunicación con el Core Bancario |
        | 1008 | Core Bancario no disponible |
        | 1009 | El valor para el campo no puede ser nulo o infringir su longitud mínima o máxima |
        | 1010 | El valor para el campo no corresponde al tipo de dato esperado |
        | 1011 | El valor para el campo no corresponde al catálogo permitido |
        | 1012 | Fecha con formato inválido |
        | 1013 | Hora con formato inválido |
        | 1014 | Número de referencia con formato inválido |
        | 1015 | IBAN con formato inválido |

        **Canal / tipo de identificación**

        | Code | Message |
        |---|---|
        | 1040 | Canal no informado |
        | 1041 | Canal inválido |
        | 1042 | Canal no corresponde |
        | 1043 | Canal no habilitado para la entidad |
        | 1044 | Canal no habilitado para el servicio |
        | 1045 | El formato de la identificación es inválido |
        | 1046 | Tipo de identificación no informado |
        | 1080 | Tipo de identificación no corresponde al cliente origen |
        | 1081 | Tipo de identificación no corresponde al cliente destino |
        | 1082 | Tipo de identificación no vigente |
        | 1083 | Tipo de identificación no soportado por el servicio |
        | 1084 | Tipo de identificación inválido |
        | 1085 | Tipo de identificación no soportado por la entidad |

        **SINPE Móvil (monedero)**

        | Code | Message |
        |---|---|
        | 15300 | El número de teléfono origen indicado es inválido |
        | 15301 | El número de teléfono origen no tiene activo el Servicio Monedero |
        | 15302 | El número de teléfono destino indicado es inválido |
        | 15303 | El número de teléfono destino no está registrado en el padrón móvil del BCCR |
        | 15304 | No es posible inactivar el monedero indicado pues no existe |
        | 15305 | El número de teléfono indicado ya se encuentra activo como monedero en el padrón local |

        ⚠️ This catalog is under review — some entries (notably `208` and `209`)
        are known to be pending verification against the official SINPE source and
        may be corrected in a future revision without notice.

        Delivery body is JSON. `EXTERNAL_WEBHOOK` HTTP body is always `{"data":"<ciphertext>"}`
        (AES-256-GCM, key = SHA256(secret_ref)). Decrypt to obtain the event envelope documented
        per `GET /webhook/event-contracts/{event_type}`.
        and the decrypted plaintext matches this contract.
      operationId: getPublicWebhookEventContract
      tags:
        - Webhooks
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: event_type
          in: path
          required: true
          schema:
            type: string
            enum:
              - payin.posted
              - payment.succeeded
              - payment.failed
              - payment.reversed
          examples:
            payinPosted:
              value: payin.posted
            paymentSucceeded:
              value: payment.succeeded
            paymentFailed:
              value: payment.failed
            paymentReversed:
              value: payment.reversed
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      description:
                        type: string
                      event_type:
                        type: string
                      example:
                        additionalProperties: true
                        type: object
                      schema_version:
                        type: string
                    required:
                      - event_type
                      - schema_version
                      - description
                      - example
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "404":
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - NOT_FOUND
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_NOT_FOUND:
                  $ref: "#/components/examples/Error_NOT_FOUND"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                http_status_code: 404
                message: The requested resource was not found.
                payload: null
                response_code: NOT_FOUND
                success: false
          x-error-codes:
            - number: 4
              code: NOT_FOUND
              message: The requested resource was not found.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 6
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 5
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
  /api/public/v1/catalogs/customer-identification-types:
    get:
      summary: List customer identification person types
      description: |
        Returns the distinct customer person types (`individual`, `business`, `both`) available
        for the authenticated tenant, optionally filtered by country. This is a person-type
        classification, not the payment identification-document catalog (`cedula`, `juridica`,
        `dimex`, ...) used by `identification.type` on `POST /payments`.
      tags:
        - Catalogs
      parameters:
        - $ref: "#/components/parameters/CorrelationIdHeader"
        - name: country_code
          in: query
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 2
          description: |
            Optional ISO-2 country code used to filter results. A legacy `country` query
            parameter is also accepted as an alias when `country_code` is omitted; prefer
            `country_code`.
      responses:
        "200":
          description: The request was processed successfully.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  data:
                    properties:
                      items:
                        items:
                          properties:
                            code:
                              type: string
                          required:
                            - code
                          type: object
                        type: array
                    required:
                      - items
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - OK
                    type: string
                  success:
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
        "401":
          description: Unauthorized. Verify your session or credentials.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - UNAUTHORIZED
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_UNAUTHORIZED:
                  $ref: "#/components/examples/Error_UNAUTHORIZED"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: UNAUTHORIZED
                  message: Unauthorized. Verify your session or credentials.
                http_status_code: 401
                message: Unauthorized. Verify your session or credentials.
                payload: null
                response_code: UNAUTHORIZED
                success: false
          x-error-codes:
            - number: 1
              code: UNAUTHORIZED
              message: Unauthorized. Verify your session or credentials.
        "403":
          description: You do not have permission to perform this action.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - FORBIDDEN
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_FORBIDDEN:
                  $ref: "#/components/examples/Error_FORBIDDEN"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                http_status_code: 403
                message: You do not have permission to perform this action.
                payload: null
                response_code: FORBIDDEN
                success: false
          x-error-codes:
            - number: 2
              code: FORBIDDEN
              message: You do not have permission to perform this action.
        "429":
          content:
            application/json:
              examples:
                Error_TOO_MANY_REQUESTS:
                  $ref: "#/components/examples/Error_TOO_MANY_REQUESTS"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - TOO_MANY_REQUESTS
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: TOO_MANY_REQUESTS
                  message: Too many requests. Please retry after a short delay.
                http_status_code: 429
                message: Too many requests. Please retry after a short delay.
                payload: null
                response_code: TOO_MANY_REQUESTS
                success: false
          x-error-codes:
            - number: 3
              code: TOO_MANY_REQUESTS
              message: Too many requests. Please retry after a short delay.
          description: Too many requests. Please retry after a short delay.
        "500":
          description: An unexpected error occurred. Please try again later.
          content:
            application/json:
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - INTERNAL_ERROR
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              examples:
                Error_INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred. Please try again later.
                http_status_code: 500
                message: An unexpected error occurred. Please try again later.
                payload: null
                response_code: INTERNAL_ERROR
                success: false
          x-error-codes:
            - number: 5
              code: INTERNAL_ERROR
              message: An unexpected error occurred. Please try again later.
        "502":
          description: Dependency error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorResponse"
        "503":
          content:
            application/json:
              examples:
                Error_SERVICE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SERVICE_UNAVAILABLE"
              schema:
                properties:
                  correlation_id:
                    type: string
                  errors:
                    additionalProperties: true
                    description: "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail)."
                    type: object
                  http_status_code:
                    type: integer
                  message:
                    type: string
                  payload:
                    additionalProperties: true
                    type: object
                  response_code:
                    enum:
                      - SERVICE_UNAVAILABLE
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - http_status_code
                  - response_code
                  - message
                  - payload
                type: object
              example:
                correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                errors:
                  code: SERVICE_UNAVAILABLE
                  message: A required service is temporarily unavailable. Please try again later.
                http_status_code: 503
                message: A required service is temporarily unavailable. Please try again later.
                payload: null
                response_code: SERVICE_UNAVAILABLE
                success: false
          x-error-codes:
            - number: 4
              code: SERVICE_UNAVAILABLE
              message: A required service is temporarily unavailable. Please try again later.
          description: A required service is temporarily unavailable. Please try again later.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    CorrelationIdHeader:
      name: X-Correlation-Id
      in: header
      required: false
      description: |
        Optional client-supplied correlation id for end-to-end tracing.
        Echoed back as `correlation_id` in the response envelope. If omitted,
        the API generates one and still returns it.
      schema:
        type: string
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    AccountIdentifierType:
      name: type
      in: query
      required: true
      description: |
        Account **identifier scheme** (e.g. `IBAN`).
        This is **not** the internal account classification
        (e.g. operational).
      schema:
        type: string
        enum:
          - IBAN
      example: IBAN
    AccountIdentifierValue:
      name: value
      in: query
      required: true
      description: Account identifier value (IBAN). Spaces are ignored.
      schema:
        type: string
      example: CR12036900101019858991
    AccountIdentifierTypeOptional:
      name: type
      in: query
      required: false
      description: |
        Optional filter by account **identifier scheme** (e.g. `IBAN`).
        Not the internal account classification.
      schema:
        type: string
      example: IBAN
    AccountIdentifierValueOptional:
      name: value
      in: query
      required: false
      description: Optional filter by account identifier value (partial match supported for list endpoints).
      schema:
        type: string
      example: CR12036900101019858991
  schemas:
    HealthResponse:
      type: object
      properties:
        message:
          type: string
          example: public-api ok
        service:
          type: string
          example: public-api
    ResponseCode:
      type: string
      description: |
        Canonical `response_code` emitted by the public-api response envelope.
        Includes both generic envelope codes (OK, CREATED, ...) and specific
        business error codes (PAYMENT_DUPLICATE, ACCOUNT_ACCESS_DENIED, ...)
        returned by individual endpoints. See each endpoint's error responses
        for which of these codes it can actually produce.
      enum:
        - OK
        - CREATED
        - NO_CONTENT
        - UNAUTHORIZED
        - FORBIDDEN
        - TOO_MANY_REQUESTS
        - SERVICE_UNAVAILABLE
        - INTERNAL_ERROR
        - INVALID_REQUEST
        - ACCOUNT_ACCESS_DENIED
        - PROVIDER_ERROR
        - INVALID_CREDENTIALS
        - NOT_FOUND
        - ACCOUNT_NOT_FOUND
        - ACCOUNT_NOT_CONFIGURED
        - UNPROCESSABLE_ENTITY
        - PAYMENT_NOT_FOUND
        - INVALID_ACCOUNT_TYPE
        - INVALID_ACCOUNT_FORMAT
        - INVALID_PAYMENT_METHOD
        - PAYMENT_INVALID_PAYLOAD
        - ACCOUNT_INVALID
        - ACCOUNT_HOLDER_MISMATCH
        - IDEMPOTENCY_CONFLICT
        - PAYMENT_DUPLICATE
        - CONFLICT
        - INSUFFICIENT_FUNDS
        - LIMIT_EXCEEDED
      example: OK
    GenericSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        http_status_code:
          type: integer
          example: 200
        response_code:
          $ref: "#/components/schemas/ResponseCode"
        message:
          type: string
          description: |
            Standard success message from the API envelope.
            - 200: The request was processed successfully.
            - 201: The resource was created successfully.
          example: The request was processed successfully.
        correlation_id:
          type: string
        payload:
          description: Echo of the JSON request body. Omitted for login, token exchange, and account validation.
          nullable: true
        data:
          type: object
          additionalProperties: true
      additionalProperties: true
    GenericErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        http_status_code:
          type: integer
          example: 401
        response_code:
          allOf:
            - $ref: "#/components/schemas/ResponseCode"
          example: UNAUTHORIZED
        message:
          type: string
          example: Unauthorized. Verify your session or credentials.
        correlation_id:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        payload:
          description: Echo of the JSON request body. Omitted for login, token exchange, and account validation.
          nullable: true
        errors:
          type: object
          nullable: true
          additionalProperties: true
      additionalProperties: true
    Rfc3339DateTime:
      type: string
      format: date-time
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
      example: 2026-01-15T12:00:00Z
      description: |
        RFC 3339 timestamp in UTC with second precision and a `Z` suffix.
        Fractional seconds are never emitted. Example: `2026-01-15T12:00:00Z`.
    Rfc3339DateTimeInput:
      type: string
      format: date-time
      example: 2026-01-01T00:00:00Z
      description: |
        RFC 3339 timestamp accepted on requests. UTC `Z` or a numeric offset is allowed.
        Optional fractional seconds are accepted and truncated to seconds.
    WebhookFeatureSummary:
      type: object
      required:
        - id
        - event_types
      properties:
        id:
          type: string
          format: uuid
        event_types:
          type: array
          items:
            type: string
            enum:
              - payin.posted
              - payment.succeeded
              - payment.failed
              - payment.reversed
          description: |
            Public event types this feature can emit. `payment.*` = resource-level
            outcomes (any direction). `payin.posted` = inbound direction only
            (funds received). There is no `payout.posted` and no `transaction.*`.
            Inspect payload shapes with `GET /api/public/v1/webhook/event-contracts/{event_type}`.
    WebhookEventContract:
      type: object
      required:
        - event_type
        - schema_version
        - description
        - example
      properties:
        event_type:
          type: string
          enum:
            - payin.posted
            - payment.succeeded
            - payment.failed
            - payment.reversed
        schema_version:
          type: string
          example: 1.0.0
        description:
          type: string
        example:
          type: object
          additionalProperties: true
    WebhookEventContractPayinPosted:
      allOf:
        - $ref: "#/components/schemas/WebhookEventContract"
        - type: object
          properties:
            event_type:
              type: string
              enum:
                - payin.posted
            example:
              $ref: "#/components/schemas/WebhookPayloadPayinPosted"
    WebhookEventContractPaymentSucceeded:
      allOf:
        - $ref: "#/components/schemas/WebhookEventContract"
        - type: object
          properties:
            event_type:
              type: string
              enum:
                - payment.succeeded
            example:
              $ref: "#/components/schemas/WebhookPayloadPaymentSucceeded"
    WebhookEventContractPaymentFailed:
      allOf:
        - $ref: "#/components/schemas/WebhookEventContract"
        - type: object
          properties:
            event_type:
              type: string
              enum:
                - payment.failed
            example:
              $ref: "#/components/schemas/WebhookPayloadPaymentFailed"
    WebhookEventContractPaymentReversed:
      allOf:
        - $ref: "#/components/schemas/WebhookEventContract"
        - type: object
          properties:
            event_type:
              type: string
              enum:
                - payment.reversed
            example:
              $ref: "#/components/schemas/WebhookPayloadPaymentReversed"
    WebhookPayloadPayinPosted:
      type: object
      description: Envelope delivered for `payin.posted` (decrypt AES_GCM `data` field first).
      required:
        - schema_version
        - event
        - context
        - payment
        - provider
      properties:
        schema_version:
          type: string
          example: 1.0.0
        event:
          type: object
          required:
            - event_id
            - event_type
            - occurred_at
            - correlation_id
          properties:
            event_id:
              type: string
              format: uuid
            event_type:
              type: string
              enum:
                - payin.posted
            occurred_at:
              $ref: "#/components/schemas/Rfc3339DateTime"
            correlation_id:
              type: string
        context:
          $ref: "#/components/schemas/WebhookContext"
        payment:
          $ref: "#/components/schemas/WebhookPaymentPayinPosted"
        provider:
          $ref: "#/components/schemas/WebhookProvider"
    WebhookPayloadPaymentSucceeded:
      type: object
      description: Envelope delivered for `payment.succeeded` (decrypt AES_GCM `data` field first).
      required:
        - schema_version
        - event
        - context
        - payment
        - provider
      properties:
        schema_version:
          type: string
          example: 1.0.0
        event:
          type: object
          required:
            - event_id
            - event_type
            - occurred_at
            - correlation_id
          properties:
            event_id:
              type: string
              format: uuid
            event_type:
              type: string
              enum:
                - payment.succeeded
            occurred_at:
              $ref: "#/components/schemas/Rfc3339DateTime"
            correlation_id:
              type: string
        context:
          $ref: "#/components/schemas/WebhookContext"
        payment:
          $ref: "#/components/schemas/WebhookPaymentSucceeded"
        provider:
          $ref: "#/components/schemas/WebhookProvider"
    WebhookContext:
      type: object
      required:
        - country_code
        - payment_method_code
      properties:
        country_code:
          type: string
          example: CR
        payment_method_code:
          type: string
          description: Public payment method catalog. Same values as REST (`PIN`, `SINPE_MOVIL`). Internal codes such as `PM_PIN` are never exposed.
          enum:
            - PIN
            - SINPE_MOVIL
          example: PIN
    WebhookProvider:
      $ref: "#/components/schemas/PublicPaymentProvider"
    WebhookRejection:
      type: object
      description: |
        Rail-agnostic provider rejection. Shared by `POST /accounts/validate`
        (`data.rejection`) and the `payment.failed` webhook (`rejection`).
        Object only when the provider rejected the operation; omitted/`null` otherwise.
      required:
        - code
        - reason_code
        - message
      properties:
        code:
          type: string
          description: |
            Normalized platform semantic derived from `reason_code`. Only a subset of
            `reason_code` values (see the catalog in the description of `POST /accounts/validate`
            and of the `payment.failed` webhook contract endpoint) has a distinct entry here —
            for any other numeric `reason_code`, `code` is `SINPE_REJECTED` even when `message`
            is specific (e.g. `reason_code = 21` "fondos insuficientes" still returns
            `code = SINPE_REJECTED`, it has no dedicated semantic). `PHONE_NOT_REGISTERED` is
            the fallback when `reason_code` is non-numeric (SINPE_MOVIL wallet flow).
          enum:
            - ACCOUNT_CLOSED
            - ACCOUNT_NOT_FOUND
            - ACCOUNT_BLOCKED
            - INVALID_ACCOUNT
            - IDENT_MISMATCH
            - IDENT_TYPE_INVALID
            - INVALID_ID_FORMAT
            - VALIDATION_ERROR
            - CURRENCY_MISMATCH
            - NOT_AUTHORIZED_BY_RECIPIENT
            - PROFILE_NOT_ALLOWED
            - CHANNEL_NOT_RECOGNIZED
            - COMMUNICATION_ERROR
            - RETRY_LATER
            - WALLET_PHONE_ORIGIN_INVALID
            - WALLET_PHONE_ORIGIN_NOT_ENABLED
            - WALLET_PHONE_DEST_INVALID
            - WALLET_PHONE_NOT_REGISTERED_BCCR
            - WALLET_NOT_FOUND
            - WALLET_PHONE_ALREADY_ACTIVE
            - PHONE_NOT_REGISTERED
            - SINPE_REJECTED
          example: ACCOUNT_BLOCKED
        reason_code:
          type: string
          description: |
            Raw Motivo/code returned by SINPE. See the endpoint description of
            `POST /accounts/validate` for the full code catalog (shared by this object
            wherever it appears, including the `payment.failed` webhook). A code not
            listed there still produces a response — `message` falls back to a generic
            text and `code` falls back to `SINPE_REJECTED`.
          example: "31"
        message:
          type: string
          description: Descriptive Motivo text; prefers provider `Detalle` when present.
          example: Cuenta bloqueada
    WebhookPaymentPayinPosted:
      type: object
      required:
        - payment_id
        - public_id
        - status
        - amount
        - posted_at
        - account
        - reference
      properties:
        payment_id:
          type: string
          format: uuid
        public_id:
          type: integer
          format: int64
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
        amount:
          $ref: "#/components/schemas/PaymentAmount"
        posted_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
        account:
          type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              example: PHONE
            value:
              type: string
              example: "88887777"
        reference:
          type: object
          required:
            - client_reference
            - external_reference
          properties:
            client_reference:
              type: string
              description: Partner reference sent at payment creation (`client_reference`), not `detail_reference`.
            external_reference:
              type: string
        destination_phone_number:
          type: string
        local_payment:
          type: boolean
          description: JSON boolean (`true`/`false`), not the strings `"true"`/`"false"`.
          example: true
        origin_client_name:
          type: string
    WebhookPaymentSucceededBase:
      type: object
      required:
        - payment_id
        - public_id
        - status
        - amount
        - client_reference
        - external_reference
        - fee_total
        - tax_total
        - net_amount
      properties:
        payment_id:
          type: string
          format: uuid
        public_id:
          type: integer
          format: int64
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
        amount:
          $ref: "#/components/schemas/PaymentAmount"
        client_reference:
          type: string
          description: Partner reference sent at payment creation (`client_reference`), not `detail_reference`.
        external_reference:
          type: string
        fee_total:
          type: string
          description: Fee total as decimal string (same currency as amount.currency)
        tax_total:
          type: string
          description: Tax total as decimal string (same currency as amount.currency)
        net_amount:
          type: string
          description: |
            Net cash impact on the merchant account.
            PAYIN: amount - fee_total - tax_total (what the merchant receives).
            PAYOUT: amount + fee_total + tax_total (total debit; fee is charged
            separately and is not deducted from the transferred amount).
    WebhookPaymentSucceeded:
      allOf:
        - $ref: "#/components/schemas/WebhookPaymentSucceededBase"
        - type: object
          required:
            - succeeded_at
          properties:
            succeeded_at:
              allOf:
                - $ref: "#/components/schemas/Rfc3339DateTime"
              description: Timestamp when the provider confirmed the payment succeeded.
    WebhookPayloadPaymentFailed:
      type: object
      description: Envelope delivered for `payment.failed` (decrypt AES_GCM `data` field first).
      required:
        - schema_version
        - event
        - context
        - payment
        - provider
      properties:
        schema_version:
          type: string
          example: 1.0.0
        event:
          type: object
          required:
            - event_id
            - event_type
            - occurred_at
            - correlation_id
          properties:
            event_id:
              type: string
              format: uuid
            event_type:
              type: string
              enum:
                - payment.failed
            occurred_at:
              $ref: "#/components/schemas/Rfc3339DateTime"
            correlation_id:
              type: string
        context:
          $ref: "#/components/schemas/WebhookContext"
        payment:
          $ref: "#/components/schemas/WebhookPaymentFailed"
        provider:
          $ref: "#/components/schemas/WebhookProvider"
        rejection:
          $ref: "#/components/schemas/WebhookRejection"
    WebhookPaymentFailed:
      type: object
      required:
        - payment_id
        - public_id
        - status
        - amount
        - error
      properties:
        payment_id:
          type: string
          format: uuid
        public_id:
          type: integer
          format: int64
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
        amount:
          $ref: "#/components/schemas/PaymentAmount"
        client_reference:
          type: string
          description: Partner reference sent at payment creation (`client_reference`), not `detail_reference`.
        external_reference:
          type: string
        error:
          $ref: "#/components/schemas/WebhookPaymentFailedError"
    WebhookPaymentFailedError:
      type: object
      required:
        - domain
        - platform
      properties:
        domain:
          type: string
          enum:
            - provider_rejection
            - platform_validation
            - platform_posting
            - platform_infra
            - platform_reversal
            - sinpe_rejection
        platform:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - PAYMENT_SINPE_REJECTED
                - PAYMENT_FEE_INVALID
                - PAYMENT_TAX_INVALID
                - PAYMENT_VALIDATION_FAILED
                - PAYMENT_ASSET_MISMATCH
                - PAYMENT_LEDGER_NOT_FOUND
                - PAYMENT_POSTING_FAILED
                - PAYMENT_FORMANCE_POSTING_FAILED
                - PAYMENT_INFRASTRUCTURE_FAILED
                - PAYMENT_REVERSED
            message:
              type: string
              description: |
                Actionable failure message. For provider rejections this is the
                provider `Detalle` when present (e.g. "Cuenta bloqueada").
    WebhookPayloadPaymentReversed:
      type: object
      description: |
        Envelope delivered for `payment.reversed`. Subsequent reversal of a payment
        that already progressed. Processing `payment.status` stays `posted` or `confirmed`.
        Not a processing failure (`payment.failed`).
      required:
        - schema_version
        - event
        - context
        - payment
        - provider
      properties:
        schema_version:
          type: string
          example: 1.0.0
        event:
          type: object
          required:
            - event_id
            - event_type
            - occurred_at
            - correlation_id
          properties:
            event_id:
              type: string
              format: uuid
            event_type:
              type: string
              enum:
                - payment.reversed
            occurred_at:
              $ref: "#/components/schemas/Rfc3339DateTime"
            correlation_id:
              type: string
        context:
          $ref: "#/components/schemas/WebhookContext"
        payment:
          $ref: "#/components/schemas/WebhookPaymentReversed"
        provider:
          $ref: "#/components/schemas/WebhookProvider"
    WebhookPaymentReversed:
      type: object
      required:
        - payment_id
        - public_id
        - status
        - result
        - has_reversal
        - amount
        - reversed_at
      properties:
        payment_id:
          type: string
          format: uuid
        public_id:
          type: integer
          format: int64
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
          description: Processing catalog. Remains `posted` or `confirmed`; not `failed`.
        result:
          type: string
          enum:
            - reversed
        has_reversal:
          type: boolean
          enum:
            - true
        amount:
          $ref: "#/components/schemas/PaymentAmount"
        client_reference:
          type: string
        external_reference:
          type: string
        reversed_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
        reason:
          type: object
          properties:
            code:
              type: string
              example: PAYMENT_REVERSED
            message:
              type: string
    AddWebhookDestinationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        feature_id:
          type: string
          format: uuid
        is_enabled:
          type: boolean
        destination_kind:
          type: string
        destination_ref:
          type: string
        webhook_url:
          type: string
        secret_ref:
          type: string
        signature_algo:
          type: string
        replay_window_sec:
          type: integer
        timeout_ms:
          type: integer
        max_attempts:
          type: integer
        scope_kind:
          type: string
        scope_account_id:
          type: string
          format: uuid
        scope_owner_type:
          type: string
        scope_owner_id:
          type: string
          format: uuid
        created_at:
          type: string
        updated_at:
          type: string
    CustomerIdentificationType:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          enum:
            - individual
            - business
            - both
          example: individual
    ListCustomerIdentificationTypesResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    $ref: "#/components/schemas/CustomerIdentificationType"
    CustomerLoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
    CustomerLoginAssignment:
      type: object
      description: Assignment context available for selection before token exchange.
      required:
        - assignment_id
        - owner_type
        - owner_id
        - tenant_id
        - tenant_code
        - country_code
        - role
        - roles
        - status
      properties:
        assignment_id:
          type: string
          format: uuid
          description: Identifier used in POST /api/public/v1/auth/token/exchange
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        owner_type:
          type: string
          example: customer
        owner_id:
          type: string
          format: uuid
          description: Customer identifier for this assignment context
          example: 2a1b3c4d-5e6f-7081-92a3-b4c5d6e7f809
        tenant_id:
          type: string
          format: uuid
          example: 11111111-2222-3333-4444-555555555555
        tenant_code:
          type: string
          example: "0001"
        country_code:
          type: string
          example: CR
        role:
          type: string
          description: Primary role code for this assignment
          example: owner
        roles:
          type: array
          items:
            type: string
          description: Role codes for this assignment
          example:
            - owner
        status:
          type: string
          example: active
    CustomerLoginResponseData:
      type: object
      required:
        - gidp_id_token
        - assignments
      properties:
        gidp_id_token:
          type: string
          description: GIDP ID token required for POST /api/public/v1/auth/token/exchange
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/CustomerLoginAssignment"
    CustomerExchangeRequest:
      type: object
      required:
        - gidp_id_token
        - assignment_id
      properties:
        gidp_id_token:
          type: string
        assignment_id:
          type: string
    CustomerExchangeClaims:
      type: object
      description: Decoded claims embedded in the returned access token.
      properties:
        owner_type:
          type: string
          example: customer
        owner_id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        roles:
          type: array
          items:
            type: string
        scopes:
          type: array
          items:
            type: string
        channel:
          type: string
        country_code:
          type: string
        locale:
          type: string
        idp:
          type: string
        idp_sub:
          type: string
        sub:
          type: string
        subject_kind:
          type: string
        user_type:
          type: string
        idempotency_key:
          type: string
    CustomerExchangeResponseData:
      type: object
      required:
        - token
        - expires_in
        - claims
      properties:
        token:
          type: string
          description: "Access token (JWT). Send as `Authorization: Bearer <token>` on all other endpoints."
        expires_in:
          type: integer
          description: Token lifetime in seconds.
          example: 3600
        claims:
          $ref: "#/components/schemas/CustomerExchangeClaims"
    CustomerPasswordResetRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
    PaymentAmount:
      type: object
      properties:
        amount:
          type: string
        currency:
          type: string
    PaymentIdentification:
      type: object
      description: |
        Counterparty identification for payment create.
        `type` uses platform identification-catalog keys (e.g. `cedula`, `juridica`, `dimex`).
        Same vocabulary as `holder.id_type` from `POST /accounts/validate`.
        `number` is the public identification (digits, no SINPE hyphens). The platform
        may reformat it internally for GX/SINPE; that internal form is not echoed on
        public payment reads for payments created after public identification persistence.
        For SINPE_MOVIL, account validate may return `unknown` because the wallet
        operation does not expose identification type; do not assume a confirmed type.
      properties:
        type:
          type: string
          description: |
            Identification catalog key (lowercase), e.g. `cedula`, `juridica`.
            May be copied from `holder.id_type` after account validate.
            For SINPE_MOVIL that value may be `unknown` (expected limitation, not an error).
          example: cedula
        number:
          type: string
          description: |
            Public identification number as submitted by the partner.
            Digits only; do not send SINPE hyphenation (e.g. `01-1234-3005`)
            or treat this field as the internal GX/SINPE display form.
            Supported types include `cedula`, `juridica`, `dimex`, `gobierno`,
            `institucion_autonoma`, `didi`, and `pasaporte`.
          example: "0101010101"
    PaymentAccount:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          description: |
            Account **identifier scheme** (e.g. `IBAN`, `PHONE`).
            Not the internal account classification (e.g. operational).
          enum:
            - IBAN
            - PHONE
          example: IBAN
        value:
          type: string
        currency:
          type: string
          description: Optional account currency in response payloads.
    DestinationAccount:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          description: |
            Counterparty account **identifier scheme** (`IBAN` for PIN, `PHONE` for SINPE_MOVIL).
            Not the internal account classification.
          enum:
            - IBAN
            - PHONE
          example: IBAN
        value:
          type: string
    IBANAccount:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          description: |
            Account **identifier scheme**. Only `IBAN` is supported here.
            This is not the internal account classification
            (e.g. operational).
          enum:
            - IBAN
          example: IBAN
        value:
          type: string
          description: IBAN (spaces allowed; normalized server-side)
    DestinationPaymentSide:
      type: object
      required:
        - account
        - name
        - identification
      properties:
        account:
          $ref: "#/components/schemas/DestinationAccount"
        name:
          type: string
          description: Counterparty name
        identification:
          $ref: "#/components/schemas/PaymentIdentification"
          description: Counterparty identification (e.g. cedula)
    SourcePaymentSide:
      type: object
      required:
        - account
        - name
        - identification
      properties:
        account:
          $ref: "#/components/schemas/IBANAccount"
          description: Internal account identified by IBAN
        name:
          type: string
          description: Account holder name
        identification:
          $ref: "#/components/schemas/PaymentIdentification"
          description: Account holder identification (e.g. cedula)
    PaymentRequest:
      type: object
      required:
        - payment_method_code
        - direction
        - amount
        - source
        - destination
        - detail_reference
      properties:
        payment_method_code:
          type: string
          description: Public payment method catalog (`PIN`, `SINPE_MOVIL`).
          enum:
            - PIN
            - SINPE_MOVIL
          example: PIN
        direction:
          type: string
          enum:
            - OUT
            - IN
          description: Operation direction (OUT = payout from internal source)
          example: OUT
        country_code:
          type: string
          description: Operational country when multi-country applies
          example: CR
        amount:
          $ref: "#/components/schemas/PaymentAmount"
        source:
          $ref: "#/components/schemas/SourcePaymentSide"
        destination:
          $ref: "#/components/schemas/DestinationPaymentSide"
        detail_reference:
          type: string
          description: Operational / transactional description stored on the payment
          example: Pago factura 1001
        client_reference:
          type: string
          description: Partner functional reference. Unique per tenant among in-flight and completed payments; a failed attempt can be retried with the same value.
          example: INV-1001
        channel_reference:
          type: string
          example: MOBILE_APP
        originator:
          $ref: "#/components/schemas/PaymentOriginator"
      example:
        payment_method_code: PIN
        direction: OUT
        country_code: CR
        amount:
          amount: "1000.00"
          currency: CRC
        source:
          account:
            type: IBAN
            value: CR26036900101010588061
          name: María González
          identification:
            type: cedula
            number: "0205620043"
        destination:
          account:
            type: IBAN
            value: CR16010400000000000031
          name: Juan Perez
          identification:
            type: cedula
            number: "0101010101"
        detail_reference: Pago factura 1001
        client_reference: INV-1001
        channel_reference: MOBILE_APP
    PaymentOriginator:
      type: object
      nullable: true
      description: |
        Optional Ultimate Debtor / Travel Rule originator information.
        Informational only in this release; no validation is applied.
        Stored under payment metadata when provided.
      properties:
        company:
          $ref: "#/components/schemas/PaymentOriginatorCompany"
        customer:
          $ref: "#/components/schemas/PaymentOriginatorCustomer"
    PaymentOriginatorCompany:
      type: object
      nullable: true
      properties:
        legal_name:
          type: string
          example: Acme Holdings S.A.
        id_type:
          type: string
          example: juridica
        id_number:
          type: string
          example: "3101123456"
    PaymentOriginatorCustomer:
      type: object
      nullable: true
      properties:
        name:
          type: string
          example: Juan Perez
        id_type:
          type: string
          example: cedula
        id_number:
          type: string
          example: "0101010101"
    GetAccountBalanceRequest:
      type: object
      required:
        - account
      properties:
        account:
          $ref: "#/components/schemas/IBANAccount"
      example:
        account:
          type: IBAN
          value: CR12036900101019858991
    PublicPaymentStatus:
      type: string
      description: |
        Public payment status catalog. Always lowercase. Same values on REST
        (create, list, get) and webhooks (`payment.status`).

        Internal lifecycle states are collapsed:
        - `pending`: initiated, validated, accepted
        - `processing`: processing, pending_processing, posting
        - `confirmed`: confirmed by the rail, not yet ledger-posted
        - `posted`: ledger posted (stays `posted` after a later reversal)
        - `failed`: failed, rejected, posting_failed, cancelled, expired

        A reversal is **not** a status. Use REST `result=reversed` / `has_reversal=true`
        and webhook `payment.reversed`.

        Operational detail remains in `status_detail` (uppercase internal name)
        on REST create/list/get. Webhook `payment.failed` uses `error.platform.code`
        to distinguish posting failures from provider rejections.
      enum:
        - pending
        - processing
        - confirmed
        - posted
        - failed
      example: posted
    PublicPaymentAmount:
      type: object
      required:
        - amount
        - currency
      description: Same monetary shape as payment create (`PaymentAmount`).
      properties:
        amount:
          type: string
          example: "1000.00"
        currency:
          type: string
          example: CRC
    PublicPaymentSide:
      type: object
      required:
        - account
        - name
        - identification
      description: |
        Payment party on read APIs. Nested fields are always present:
        `null` when the value is unknown. `account` is a public identifier
        (`IBAN` or `PHONE`); ledger/account UUIDs are never returned.
      properties:
        account:
          allOf:
            - $ref: "#/components/schemas/PaymentAccount"
          nullable: true
          description: |
            Public account identifier (`type` + `value`). `null` when the IBAN or
            phone cannot be resolved. Never a ledger UUID or `ACCOUNT_ID`.
        name:
          type: string
          nullable: true
          description: Party name from processing metadata when available; otherwise `null`.
        identification:
          allOf:
            - $ref: "#/components/schemas/PublicPaymentIdentification"
          nullable: true
          description: |
            Party identification (`type` catalog key + `number`). Object only when
            at least one field is known; otherwise `null`. Does not expose internal
            SINPE type codes (`0`–`9`); unmapped types are omitted (`type: null`).
            `number` is the partner-submitted public value for payments created after
            public identification persistence (digits, no SINPE hyphens). Historical
            payments may still return the hyphenated SINPE display form.
    PublicPaymentProvider:
      type: object
      description: |
        Shared provider snapshot on REST payment reads and webhook envelopes.
        Rail reference is only on `payment.external_reference`, not duplicated here.
        `provider_status_*` match webhook `rejection.reason_code` / `message` / `code`
        when the provider rejected the operation. `null` when there is no rejection.
      required:
        - correlation_id
        - occurred_at
        - provider_status_code
        - provider_status_desc
        - provider_status_semantic
      properties:
        correlation_id:
          type: string
          nullable: true
          description: |
            Transaction correlation UUID (`execution.correlation_id` /
            `metadata.tx.correlationId`). Sent to GX/SINPE as `correlationId`.
            Not `channel_reference` (e.g. `MOBILE_APP`). Distinct from webhook
            `event.correlation_id` (HTTP request id for this delivery). `null` when unknown.
        occurred_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
          nullable: true
          description: |
            When this provider-facing event was recorded (RFC 3339 UTC, second precision,
            `Z`). Webhooks use `event.occurred_at`; REST uses `succeeded_at` when present,
            otherwise `updated_at`. `null` when unknown.
        provider_status_code:
          type: string
          nullable: true
          description: |
            Raw provider Motivo/code (e.g. `31`). Same meaning as webhook
            `rejection.reason_code`. `null` when there is no provider rejection.
          example: "31"
        provider_status_desc:
          type: string
          nullable: true
          description: |
            Provider Motivo text (prefers Detalle). Same meaning as webhook
            `rejection.message`. `null` when there is no provider rejection.
          example: Cuenta bloqueada
        provider_status_semantic:
          type: string
          nullable: true
          description: |
            Normalized platform semantic (e.g. `ACCOUNT_BLOCKED`). Same meaning as
            webhook `rejection.code`. `null` when there is no provider rejection.
          example: ACCOUNT_BLOCKED
    PublicPaymentIdentification:
      type: object
      description: |
        Party identification on payment read APIs. Present only when `type` and/or
        `number` is known. Catalog keys match create (`cedula`, `juridica`, `dimex`, …).
        Raw SINPE numeric type codes are not exposed.

        For payments created after public identification persistence, `number` is the
        same public value submitted on `POST /transactions/payments` (digits, no SINPE
        hyphens such as `01-1234-3005`). It is not taken from the GX resend snapshot.

        Payments created before that change have no public snapshot. Reads then keep
        the previous behavior: `number` may be the hyphenated SINPE form stored for
        GX/SINPE communication. Those historical values are not rewritten.
        See `docs/PAYMENT-IDENTIFICATION.md`.
      properties:
        type:
          type: string
          nullable: true
          description: Identification catalog key (e.g. `cedula`, `juridica`). `null` when unknown.
          example: cedula
        number:
          type: string
          nullable: true
          description: |
            Public identification number. New PIN payments return the partner-submitted
            value (digits, no SINPE hyphens). Historical payments may still return
            the SINPE display form (hyphenated, possibly padded).
          example: "0101010101"
    PublicPaymentError:
      type: object
      description: |
        Same shape as webhook `payment.failed` `payment.error` (`domain` / `platform`).
        Present only when `result` is `failed` or `reversed` and taxonomy is known.
        Empty objects are not used; the parent `error` field is `null` instead.
      required:
        - domain
        - platform
      properties:
        domain:
          type: string
          description: Same catalog as webhook `payment.error.domain`.
          enum:
            - provider_rejection
            - platform_validation
            - platform_posting
            - platform_infra
            - platform_reversal
          example: provider_rejection
        platform:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable platform public code (same as webhook `payment.error.platform.code`).
              example: PAYMENT_SINPE_REJECTED
            message:
              type: string
              description: Actionable message (prefers provider Detalle). Same as webhook `payment.error.platform.message`.
              example: Cuenta bloqueada
    PublicPayment:
      type: object
      required:
        - schema_version
        - payment_id
        - type
        - payment_method_code
        - status
        - result
        - has_reversal
        - error
      properties:
        schema_version:
          type: string
          description: |
            Payment-read contract version. Same value as webhook envelope
            `schema_version` (`1.0.0`) for `payment.succeeded` / `payment.failed`.
          example: 1.0.0
        payment_id:
          type: string
          format: uuid
          description: |
            Payment UUID returned by create. Partner-facing payment key for
            `GET /transactions/payments/{payment_id}` and search. Not a ledger
            or internal account id.
        public_id:
          type: string
          nullable: true
          description: |
            Numeric public payment identifier returned by create. `null` if not
            yet assigned. Not a ledger/account UUID.
        type:
          type: string
          description: Payment type derived from direction (`PAYIN` / `PAYOUT`).
        payment_method_code:
          type: string
          description: Public payment method catalog (`PIN`, `SINPE_MOVIL`). Same values as webhooks.
          enum:
            - PIN
            - SINPE_MOVIL
          example: PIN
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
        status_detail:
          type: string
          description: |
            Operational (internal) status in uppercase, e.g. `VALIDATED`,
            `POSTED`, `POSTING_FAILED`. Companion to the public `status` catalog.
            Independent of `result` (`posted` is the debit/posting milestone, not provider success).
        result:
          type: string
          enum:
            - succeeded
            - failed
            - reversed
            - pending
          description: |
            Consolidated business outcome for reconciliation (backup to webhooks).
            Independent of processing `status`. Derived as: `reversed` when
            `has_reversal` is true (highest priority); `succeeded` when `succeeded_at`
            is set and there is no reversal; `failed` when processing status is
            `failed` or `posting_failed`; otherwise `pending`.
            A posted payment that was later reversed has `status=posted` and `result=reversed`.
        succeeded_at:
          allOf:
            - $ref: "#/components/schemas/Rfc3339DateTime"
          nullable: true
          description: |
            Provider success confirmation timestamp (RFC 3339 UTC, second precision, `Z`).
            Null while the payment may already be `posted` internally but the provider has not confirmed success.
        has_reversal:
          type: boolean
          description: True when a reversal was applied. Independent of `status`. Correlates with webhook `payment.reversed`.
        reversed_at:
          allOf:
            - $ref: "#/components/schemas/Rfc3339DateTime"
          nullable: true
          description: When the reversal was applied. Null when `has_reversal` is false.
        created_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
        updated_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
        amount:
          $ref: "#/components/schemas/PublicPaymentAmount"
        source:
          $ref: "#/components/schemas/PublicPaymentSide"
        destination:
          $ref: "#/components/schemas/PublicPaymentSide"
        client_reference:
          type: string
          description: Partner reference sent at payment creation (stable after processing). Same field as webhook `payment.client_reference`.
        external_reference:
          type: string
          nullable: true
          description: |
            Rail/SINPE transaction id. Same field, location, and meaning as webhook
            `payment.external_reference` on `payment.succeeded` / `payment.failed`
            (`metadata.sinpe_reference`, else `external_provider_tx_id`). Sibling of
            `client_reference`. `null` if none.
        provider:
          $ref: "#/components/schemas/PublicPaymentProvider"
        error:
          allOf:
            - $ref: "#/components/schemas/PublicPaymentError"
          nullable: true
          description: |
            Always present. `null` when there is no failure information
            (`succeeded`, `pending`, or failed/reversed without taxonomy).
            Object uses the same `domain` / `platform` shape as webhook `payment.failed`.
    GetPaymentByIDResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/PublicPayment"
    SearchPaymentRequest:
      type: object
      description: |
        The customer account and exactly one of `payment_id`, `public_id`, or `client_reference` must be provided.
      properties:
        account:
          $ref: "#/components/schemas/PaymentAccount"
        payment_id:
          type: string
          format: uuid
          description: Internal payment UUID.
        public_id:
          type: string
          description: Numeric public payment identifier.
          example: "134729"
        client_reference:
          type: string
          description: Partner reference sent at payment creation.
          example: INV-01082
      required:
        - account
    CreatePaymentResponseData:
      type: object
      properties:
        payment_id:
          type: string
          format: uuid
          description: Internal payment UUID
        public_id:
          type: string
          description: Public numeric payment identifier
        status:
          $ref: "#/components/schemas/PublicPaymentStatus"
        status_detail:
          type: string
          description: Operational status detail (e.g. PROCESSING)
        payment_method_code:
          type: string
          description: Public payment method catalog (`PIN`, `SINPE_MOVIL`).
          enum:
            - PIN
            - SINPE_MOVIL
          example: PIN
        created_at:
          $ref: "#/components/schemas/Rfc3339DateTime"
    CreatePaymentResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            http_status_code:
              type: integer
              example: 201
            response_code:
              allOf:
                - $ref: "#/components/schemas/ResponseCode"
              example: CREATED
            message:
              type: string
              example: The resource was created successfully.
            data:
              $ref: "#/components/schemas/CreatePaymentResponseData"
    ListPaymentsResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              type: object
              required:
                - schema_version
                - items
              properties:
                schema_version:
                  type: string
                  description: Same value as webhook envelope `schema_version` (`1.0.0`).
                  example: 1.0.0
                items:
                  type: array
                  items:
                    $ref: "#/components/schemas/PublicPayment"
                pagination:
                  $ref: "#/components/schemas/ListPaymentsPagination"
    ListPaymentsPagination:
      type: object
      description: Cursor pagination. Pass next_cursor as cursor on the next request.
      properties:
        next_cursor:
          type: string
          description: Opaque cursor for the next page; omitted or empty when there is no next page
        limit:
          type: integer
          description: Page size applied to this response
    AccountValidateRequest:
      type: object
      required:
        - payment_method_code
        - account
      properties:
        payment_method_code:
          type: string
          description: Payment method used to route validation (PIN for external IBAN, SINPE_MOVIL for phone wallet).
          enum:
            - PIN
            - SINPE_MOVIL
          example: PIN
        account:
          type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - IBAN
                - PHONE
              example: IBAN
            value:
              type: string
      example:
        payment_method_code: PIN
        account:
          type: IBAN
          value: CR16010400000000000031
    AccountValidateResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              type: object
              properties:
                is_valid:
                  type: boolean
                account:
                  type: object
                  properties:
                    type:
                      type: string
                    value:
                      type: string
                    currency:
                      type: string
                    product_name:
                      type: string
                holder:
                  type: object
                  nullable: true
                  description: |
                    Account holder when validation succeeds.
                    `id_type` matches `PaymentIdentification.type` (same catalog as POST /payments).
                    For SINPE_MOVIL, `id_type` may be `unknown` because the wallet
                    operation does not return an identification type. That is expected
                    and stable; do not treat it as a bug.
                  properties:
                    name:
                      type: string
                    id_type:
                      type: string
                      description: |
                        Identification catalog key (lowercase), e.g. `cedula`, `juridica`, `dimex`.
                        Same vocabulary as `identification.type` on payment create.

                        PIN: mapped from the provider's `CodTipoIdDestino` (confirmed by the provider).
                        SINPE_MOVIL: `ObtenerInfoMonedero` does not return an identification
                        type, so this field **may be `unknown`**. That is expected, stable
                        behavior due to available provider data — not a mapping bug or a
                        transient error. Do not assume a confirmed type is always present.
                      enum:
                        - cedula
                        - dimex
                        - gobierno
                        - juridica
                        - institucion_autonoma
                        - didi
                        - pasaporte
                        - unknown
                      example: cedula
                    id_number:
                      type: string
                financial_institution:
                  type: object
                  nullable: true
                  description: |
                    Counterparty institution when validation succeeds.

                    PIN fills `entity_name` from `InformacionCuenta.Entidad`.
                    SINPE_MOVIL only receives an entity **code** from `ObtenerInfoMonedero`;
                    the operation does not return the institution name, so `entity_name`
                    **may be `""`**. That is expected, stable behavior — not a transient
                    error. Do not assume `entity_name` is always populated.
                  properties:
                    country_code:
                      type: string
                    entity_code:
                      type: string
                    entity_name:
                      type: string
                      description: |
                        Human-readable institution name.
                        PIN: populated from the provider account-info operation.
                        SINPE_MOVIL: may be `""` because `ObtenerInfoMonedero` does not
                        expose the name. Expected limitation, not an error.
                      example: Banco Davivienda (Costa Rica) S.A.
                rejection:
                  allOf:
                    - $ref: "#/components/schemas/WebhookRejection"
                  nullable: true
                  description: Present when `is_valid` is `false` and the provider rejected the account. `null` when `is_valid` is `true`.
                provider:
                  type: object
                  properties:
                    operation:
                      type: string
                    correlation_id:
                      type: string
                      nullable: true
                    occurred_at:
                      type: string
                      format: date-time
                      nullable: true
    BalanceAmounts:
      type: object
      description: |
        Ledger balances as decimal strings with 2 fraction digits
        (same display scale as public payment amounts). Prefer string over JSON number
        for financial amounts.
      properties:
        available:
          type: string
          example: "991900.00"
        posted:
          type: string
          example: "991900.00"
        inbound_in_transit:
          type: string
          example: "0.00"
        outbound_in_transit:
          type: string
          example: "0.00"
    AccountBalance:
      type: object
      required:
        - account
        - amounts
        - as_of
      description: |
        Balance snapshot. `amounts` and `as_of` are only returned on
        `GET /accounts/balances` and `POST /accounts/balance`.
      properties:
        account:
          $ref: "#/components/schemas/PaymentAccount"
          description: Same shape as balance request (type + value); IBAN when available
        amounts:
          $ref: "#/components/schemas/BalanceAmounts"
        as_of:
          allOf:
            - $ref: "#/components/schemas/Rfc3339DateTime"
          nullable: true
          description: Ledger timestamp when known (RFC 3339 UTC, second precision, `Z`); `null` when not available.
    PublicAccount:
      type: object
      required:
        - account
      description: |
        Account attributes only. Used by `GET /accounts`. Does not include
        `amounts` or `as_of`.
      properties:
        account:
          $ref: "#/components/schemas/PaymentAccount"
    AccountsPagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    GetAccountBalanceResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/AccountBalance"
    CreateAccountStatementRequest:
      type: object
      required:
        - account
        - date_from
        - date_to
      properties:
        account:
          $ref: "#/components/schemas/IBANAccount"
          description: |
            Account identified by identifier scheme + value (`type` + `value`).
            Same public standard as balance and payments. Not the internal
            account classification.
        date_from:
          $ref: "#/components/schemas/Rfc3339DateTimeInput"
        date_to:
          allOf:
            - $ref: "#/components/schemas/Rfc3339DateTimeInput"
          description: RFC 3339 (max 60 days after date_from)
        notify_email:
          type: boolean
          default: false
      example:
        account:
          type: IBAN
          value: CR12036900101019858991
        date_from: 2026-01-01T00:00:00Z
        date_to: 2026-01-31T23:59:59Z
        notify_email: false
    AccountStatementCreated:
      type: object
      required:
        - request_id
        - status
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - DONE
            - ERROR
    CreateAccountStatementResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            payload:
              $ref: "#/components/schemas/CreateAccountStatementRequest"
            data:
              $ref: "#/components/schemas/AccountStatementCreated"
    AccountStatementStatus:
      type: object
      required:
        - request_id
        - status
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - DONE
            - ERROR
        download_url:
          type: string
          format: uri
          description: Signed GCS download URL (present when status is DONE and the link has not expired)
        expires_at:
          allOf:
            - $ref: "#/components/schemas/Rfc3339DateTime"
          description: Expiration of download_url (48h from generation)
        message:
          type: string
          description: Generic error message when status is ERROR
    GetAccountStatementStatusResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/AccountStatementStatus"
    ListAccountsResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: "#/components/schemas/PublicAccount"
                pagination:
                  $ref: "#/components/schemas/AccountsPagination"
    ListAccountBalancesResponse:
      allOf:
        - $ref: "#/components/schemas/GenericSuccessResponse"
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: "#/components/schemas/AccountBalance"
                pagination:
                  $ref: "#/components/schemas/AccountsPagination"
    AddWebhookDestinationRequest:
      type: object
      description: |
        Single object shape; **which fields are required or forbidden** is determined by `destination_kind` and `scope_kind` (see operation description). Values are case-insensitive where the server normalizes to uppercase for kinds.
      required:
        - feature_id
        - destination_kind
        - scope_kind
      properties:
        feature_id:
          type: string
          format: uuid
          description: Feature to subscribe (from `GET /api/public/v1/webhook/features`). Must exist or create fails.
        is_enabled:
          type: boolean
          description: Defaults to true if omitted.
        destination_kind:
          type: string
          description: |
            Public API accepts only `EXTERNAL_WEBHOOK` (HTTPS callback with shared secret). `INTERNAL` destinations are managed administratively.
          enum:
            - EXTERNAL_WEBHOOK
        destination_ref:
          type: string
          nullable: true
          description: Not used on the public API. Reserved for internal destinations.
        webhook_url:
          type: string
          format: uri
          nullable: true
          description: Required (must use `https://`).
        secret_ref:
          type: string
          nullable: true
          description: |
            Required shared secret used to decrypt AES_GCM payloads (`key = SHA256(secret_ref)`).
            See "Webhook encryption" in this operation's description.
        signature_algo:
          type: string
          nullable: true
          enum:
            - AES_GCM
          description: |
            Fixed to `AES_GCM` for `EXTERNAL_WEBHOOK`. Omitted on create; stored as `AES_GCM`.
            `HMAC_SHA256` is no longer supported.
        replay_window_sec:
          type: integer
          nullable: true
          description: |
            Reserved for legacy destinations. Not used for `EXTERNAL_WEBHOOK` AES_GCM deliveries.
        timeout_ms:
          type: integer
          nullable: true
          description: HTTP timeout for delivery attempts (`EXTERNAL_WEBHOOK`).
        max_attempts:
          type: integer
          nullable: true
          description: Max delivery attempts (`EXTERNAL_WEBHOOK`).
        backoff_policy:
          type: object
          nullable: true
          additionalProperties: true
          description: |
            Optional free-form JSON retry/backoff override, stored as-is and not
            currently validated or documented by the platform. Omit to use the
            platform's default backoff policy.
        scope_kind:
          type: string
          description: |
            - `TENANT`: no scope id fields.
            - `ACCOUNT`: set `scope_account_id` only.
            - `OWNER`: set `scope_owner_type` and `scope_owner_id` only.
          enum:
            - TENANT
            - ACCOUNT
            - OWNER
        scope_account_id:
          type: string
          format: uuid
          nullable: true
          description: Required when `scope_kind` is `ACCOUNT`. Must be omitted for `TENANT` and `OWNER`.
        scope_owner_type:
          type: string
          nullable: true
          description: Required when `scope_kind` is `OWNER`. Allowed values (lowercase) `tenant`, `partner`, `user`, `platform`, `customer`. Omit for `TENANT` and `ACCOUNT`.
        scope_owner_id:
          type: string
          format: uuid
          nullable: true
          description: Required when `scope_kind` is `OWNER`. Omit for `TENANT` and `ACCOUNT`.
  examples:
    Error_UNAUTHORIZED:
      summary: "UNAUTHORIZED: Unauthorized. Verify your session or credentials."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: UNAUTHORIZED
          message: Unauthorized. Verify your session or credentials.
        http_status_code: 401
        message: Unauthorized. Verify your session or credentials.
        payload: null
        response_code: UNAUTHORIZED
        success: false
    Error_FORBIDDEN:
      summary: "FORBIDDEN: You do not have permission to perform this action."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: FORBIDDEN
          message: You do not have permission to perform this action.
        http_status_code: 403
        message: You do not have permission to perform this action.
        payload: null
        response_code: FORBIDDEN
        success: false
    Error_INVALID_REQUEST:
      summary: "INVALID_REQUEST: Invalid request. Check the required fields and try again."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INVALID_REQUEST
          message: Invalid request. Check the required fields and try again.
        http_status_code: 400
        message: Invalid request. Check the required fields and try again.
        payload: null
        response_code: INVALID_REQUEST
        success: false
    Error_INVALID_CREDENTIALS:
      summary: "INVALID_CREDENTIALS: Invalid email or password."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INVALID_CREDENTIALS
          message: Invalid email or password.
        http_status_code: 401
        message: Invalid email or password.
        payload: null
        response_code: INVALID_CREDENTIALS
        success: false
    Error_NOT_FOUND:
      summary: "NOT_FOUND: The requested resource was not found."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: NOT_FOUND
          message: The requested resource was not found.
        http_status_code: 404
        message: The requested resource was not found.
        payload: null
        response_code: NOT_FOUND
        success: false
    Error_CONFLICT:
      summary: "CONFLICT: The request conflicts with the current state."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: CONFLICT
          message: The request conflicts with the current state.
        http_status_code: 409
        message: The request conflicts with the current state.
        payload: null
        response_code: CONFLICT
        success: false
    Error_UNPROCESSABLE_ENTITY:
      summary: "UNPROCESSABLE_ENTITY: The request is well-formed but cannot be processed due to business rules."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: UNPROCESSABLE_ENTITY
          message: The request is well-formed but cannot be processed due to business rules.
        http_status_code: 422
        message: The request is well-formed but cannot be processed due to business rules.
        payload: null
        response_code: UNPROCESSABLE_ENTITY
        success: false
    Error_TOO_MANY_REQUESTS:
      summary: "TOO_MANY_REQUESTS: Too many requests. Please retry after a short delay."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: TOO_MANY_REQUESTS
          message: Too many requests. Please retry after a short delay.
        http_status_code: 429
        message: Too many requests. Please retry after a short delay.
        payload: null
        response_code: TOO_MANY_REQUESTS
        success: false
    Error_ACCOUNT_ACCESS_DENIED:
      summary: "ACCOUNT_ACCESS_DENIED: The actor does not have access to the requested account."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: ACCOUNT_ACCESS_DENIED
          message: The actor does not have access to the requested account.
        http_status_code: 403
        message: The actor does not have access to the requested account.
        payload: null
        response_code: ACCOUNT_ACCESS_DENIED
        success: false
    Error_ACCOUNT_INVALID:
      summary: "ACCOUNT_INVALID: The account is invalid or not enabled for the service."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: ACCOUNT_INVALID
          message: The account is invalid or not enabled for the service.
        http_status_code: 400
        message: The account is invalid or not enabled for the service.
        payload: null
        response_code: ACCOUNT_INVALID
        success: false
    Error_ACCOUNT_HOLDER_MISMATCH:
      summary: "ACCOUNT_HOLDER_MISMATCH: Account holder does not match the provided identification or name."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: ACCOUNT_HOLDER_MISMATCH
          message: Account holder does not match the provided identification or name.
        http_status_code: 400
        message: Account holder does not match the provided identification or name.
        payload: null
        response_code: ACCOUNT_HOLDER_MISMATCH
        success: false
    Error_ACCOUNT_NOT_FOUND:
      summary: "ACCOUNT_NOT_FOUND: Account not found."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: ACCOUNT_NOT_FOUND
          message: Account not found.
        http_status_code: 404
        message: Account not found.
        payload: null
        response_code: ACCOUNT_NOT_FOUND
        success: false
    Error_ACCOUNT_NOT_CONFIGURED:
      summary: "ACCOUNT_NOT_CONFIGURED: This account is not mapped in the system. Please contact support to configure it correctly."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: ACCOUNT_NOT_CONFIGURED
          message: This account is not mapped in the system. Please contact support to configure it correctly.
        http_status_code: 422
        message: This account is not mapped in the system. Please contact support to configure it correctly.
        payload: null
        response_code: ACCOUNT_NOT_CONFIGURED
        success: false
    Error_PAYMENT_NOT_FOUND:
      summary: "PAYMENT_NOT_FOUND: Payment not found."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: PAYMENT_NOT_FOUND
          message: Payment not found.
        http_status_code: 404
        message: Payment not found.
        payload: null
        response_code: PAYMENT_NOT_FOUND
        success: false
    Error_PAYMENT_INVALID_PAYLOAD:
      summary: "PAYMENT_INVALID_PAYLOAD: Invalid payment request payload."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: PAYMENT_INVALID_PAYLOAD
          message: Invalid payment request payload.
        http_status_code: 400
        message: Invalid payment request payload.
        payload: null
        response_code: PAYMENT_INVALID_PAYLOAD
        success: false
    Error_INVALID_ACCOUNT_FORMAT:
      summary: "INVALID_ACCOUNT_FORMAT: Invalid account format."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INVALID_ACCOUNT_FORMAT
          message: Invalid account format.
        http_status_code: 400
        message: Invalid account format.
        payload: null
        response_code: INVALID_ACCOUNT_FORMAT
        success: false
    Error_INVALID_ACCOUNT_TYPE:
      summary: "INVALID_ACCOUNT_TYPE: Unsupported or invalid account type."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INVALID_ACCOUNT_TYPE
          message: Unsupported or invalid account type.
        http_status_code: 400
        message: Unsupported or invalid account type.
        payload: null
        response_code: INVALID_ACCOUNT_TYPE
        success: false
    Error_INVALID_PAYMENT_METHOD:
      summary: "INVALID_PAYMENT_METHOD: Invalid or unsupported payment method."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INVALID_PAYMENT_METHOD
          message: Invalid or unsupported payment method.
        http_status_code: 400
        message: Invalid or unsupported payment method.
        payload: null
        response_code: INVALID_PAYMENT_METHOD
        success: false
    Error_IDEMPOTENCY_CONFLICT:
      summary: "IDEMPOTENCY_CONFLICT: Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: IDEMPOTENCY_CONFLICT
          message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
        http_status_code: 409
        message: "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress."
        payload: null
        response_code: IDEMPOTENCY_CONFLICT
        success: false
    Error_PAYMENT_DUPLICATE:
      summary: "PAYMENT_DUPLICATE: An in-flight or completed payment with this client_reference already exists."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: PAYMENT_DUPLICATE
          message: An in-flight or completed payment with this client_reference already exists.
        http_status_code: 409
        message: An in-flight or completed payment with this client_reference already exists.
        payload: null
        response_code: PAYMENT_DUPLICATE
        success: false
    Error_INSUFFICIENT_FUNDS:
      summary: "INSUFFICIENT_FUNDS: Insufficient funds to complete the payment."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INSUFFICIENT_FUNDS
          message: Insufficient funds to complete the payment.
        http_status_code: 422
        message: Insufficient funds to complete the payment.
        payload: null
        response_code: INSUFFICIENT_FUNDS
        success: false
    Error_LIMIT_EXCEEDED:
      summary: "LIMIT_EXCEEDED: A transaction or accumulation limit was exceeded."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: LIMIT_EXCEEDED
          message: A transaction or accumulation limit was exceeded.
        http_status_code: 422
        message: A transaction or accumulation limit was exceeded.
        payload: null
        response_code: LIMIT_EXCEEDED
        success: false
    Error_PROVIDER_ERROR:
      summary: "PROVIDER_ERROR: Unable to complete the request with the payment provider. Please try again later."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: PROVIDER_ERROR
          message: Unable to complete the request with the payment provider. Please try again later.
        http_status_code: 502
        message: Unable to complete the request with the payment provider. Please try again later.
        payload: null
        response_code: PROVIDER_ERROR
        success: false
    Error_SERVICE_UNAVAILABLE:
      summary: "SERVICE_UNAVAILABLE: A required service is temporarily unavailable. Please try again later."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: SERVICE_UNAVAILABLE
          message: A required service is temporarily unavailable. Please try again later.
        http_status_code: 503
        message: A required service is temporarily unavailable. Please try again later.
        payload: null
        response_code: SERVICE_UNAVAILABLE
        success: false
    Error_INTERNAL_ERROR:
      summary: "INTERNAL_ERROR: An unexpected error occurred. Please try again later."
      value:
        correlation_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        errors:
          code: INTERNAL_ERROR
          message: An unexpected error occurred. Please try again later.
        http_status_code: 500
        message: An unexpected error occurred. Please try again later.
        payload: null
        response_code: INTERNAL_ERROR
        success: false
x-public-api-error-codes-source: redis:public_api_openapi_cache+in-code:EndpointMatrix
x-public-api-error-codes-generated-at: 2026-09-03T01:37:01Z
