openapi: 3.0.4
info:
  title: Tranzmit Payers API
  description: |
    Payers API permite procesar transacciones de transferencia de dinero.

    **Flujo típico (OFFICE-PICKUP):**
    `GET referenceNumber` → `POST payout-assignment` → (opcional, repetible) `POST payout-updates`
    → `POST payout-confirmation` (PAID) **o** `POST payout-rejection` (REJECTED).

    **Flujo por lotes (no OFFICE-PICKUP):**
    `GET query-available` → por cada transacción: `POST acknowledgement` → `POST payout-assignment`
    → (opcional) `POST payout-updates` → `POST payout-confirmation` o `POST payout-rejection`.

    **Estados:** `PENDING`, `READY-FOR-PAYOUT`, `PAID`, `REJECTED`, `CANCELLED`.

    **Versionado:** header `api-version`, o `Content-Type: application/vnd.tranzmit.payers-api+json; api-version=1.0`.
    Dentro de la versión mayor solo habrá cambios aditivos (nuevos endpoints, parámetros opcionales,
    campos en respuestas, códigos de error y de rechazo), por lo que el cliente debe tolerarlos.
  version: "1.0"
  license:
    name: Uso propietario — Red Chapina S.A.
    url: https://www.redchapina.com
servers:
  - url: https://payers-api.stg.tranzmit.net
    description: Staging
tags:
  - name: Transactions
    description: Consulta y procesamiento de transacciones de transferencia de dinero.
security:
  - oauth-client-credentials: []
paths:
  /api/transactions/{id}:
    get:
      tags: [Transactions]
      operationId: findTransaction
      summary: Find transaction
      description: |
        Finds transaction by its primary id

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindTransactionByIdResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/transactions/referenceNumber={refNum}:
    get:
      tags: [Transactions]
      operationId: findTransactionByReferenceNumber
      summary: Find transaction by reference number
      description: |
        Finds transaction by reference number provided by the recipient.

        Usually the endpoint is used for transactions with `OFFICE-PICKUP` delivery method.

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
      parameters:
        - name: refNum
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/ApiVersion"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindTransactionByRefNumResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/transactions/query-available:
    get:
      tags: [Transactions]
      operationId: queryAvailableTransactions
      summary: Query available transactions
      description: |
        Finds a batch of available transactions according to provided parameters. Transaction is
        available when it is in `PENDING` status and has not been acknowledged before.

        Usually the endpoint is used for transactions where batch processing is possible
        (`BANK-DEPOSIT`, `HOME-DELIVERY`, `MOBILE-WALLET`) together with `/{id}/acknowledgement` API.

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
      parameters:
        - name: delivery_method
          in: query
          description: >-
            Delivery method the batch is filtered by. OFFICE-PICKUP does not apply:
            that flow enters by reference number.
          example: BANK-DEPOSIT
          schema:
            type: string
            enum: [BANK-DEPOSIT, HOME-DELIVERY, MOBILE-WALLET, null]
            nullable: true
        - name: limit
          in: query
          description: limit, not more than 100, default 10
          schema:
            type: integer
            format: int32
            minimum: 0
            exclusiveMinimum: true
            maximum: 100
            exclusiveMaximum: false
        - $ref: "#/components/parameters/ApiVersion"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryAvailableTransactionsResponse"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/transactions/{id}/acknowledgement:
    post:
      tags: [Transactions]
      operationId: acknowledgeTransaction
      summary: Acknowledge transaction
      description: |
        Acknowledges the transaction. Acknowledgement removes transactions from the list of
        "available" transactions. Acknowledgement does not change transaction status, leaving it
        in `PENDING` status.

        Usually the endpoint is used for transactions with non `OFFICE-PICKUP` delivery method
        (where batch processing is possible) together with `/query-available` API.

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction is already acknowledged.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcknowledgeTransactionResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/transactions/{id}/payout-assignment:
    post:
      tags: [Transactions]
      operationId: assignTransactionPayout
      summary: Assign transaction to payout
      description: |
        Assigns transaction in `PENDING` status to payout. Transaction transitions from `PENDING`
        to `READY-FOR-PAYOUT` status.

        Assignment operation generates transaction PayoutToken. The client is supposed to record
        PayoutToken which is returned in response, that value is mandatory for further transaction
        processing toward end status.

        Transactions assigned to payout cannot be changed by anyone except the client holding PayoutToken.

        Assignment is time-limited (depends on delivery method), transaction object contains info
        about its expiry. Assignment expiration transitions transaction back to `PENDING` status.

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction is already assigned to payout or transaction
        version in request does not match actual transaction version.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignTransactionPayoutRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/AssignTransactionPayoutRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignTransactionPayoutResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
    delete:
      tags: [Transactions]
      operationId: unassignTransactionPayout
      summary: Unassign transaction from payout
      description: |
        Unassigns transaction in `READY-FOR-PAYOUT` status from payout. Transaction returns to
        `PENDING` state.

        Unassigning transaction from payout requires PayoutToken generated before to be passed
        (see `POST {id}/payout-assignment`).

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.PAYOUT-TOKEN-MISMATCH` - specified in request PayoutToken is invalid.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction status is not `READY-FOR-PAYOUT`.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnassignTransactionPayoutRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/UnassignTransactionPayoutRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnassignTransactionPayoutResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/transactions/{id}/payout-updates:
    post:
      tags: [Transactions]
      operationId: createTransactionPayoutUpdate
      summary: Create transaction payout update
      description: |
        Creates additional updates about transaction processing of two types:

        `COMPLIANCE` - about compliance check that takes place for current transaction

        `COMMENT` - free form comment that the client considers reasonable to share

        Creating additional updates does not cause transaction status changes.

        Creating additional updates requires PayoutToken generated before to be passed
        (see `POST {id}/payout-assignment`).

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.PAYOUT-TOKEN-MISMATCH` - specified in request PayoutToken is invalid.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction is not assigned to payout.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransactionPayoutUpdateRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/CreateTransactionPayoutUpdateRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateTransactionPayoutUpdateResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/transactions/{id}/payout-confirmation:
    post:
      tags: [Transactions]
      operationId: confirmTransactionPayout
      summary: Confirm transaction payout
      description: |
        Confirms payout of transaction in `READY-FOR-PAYOUT` status. Transaction transitions to
        `PAID` status.

        Confirming transaction payout requires PayoutToken generated before to be passed
        (see `POST {id}/payout-assignment`).

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.PAYOUT-TOKEN-MISMATCH` - specified in request PayoutToken is invalid.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction is not assigned to payout or its status is
        not `READY-FOR-PAYOUT`.
        HTTP 400 `PAYERS-API.RECIPIENT-KYC-REQUIRED` / `PAYERS-API.RECIPIENT-KYC-BUSINESS-RULE-VIOLATION`
        - RecipientKyc is missing, invalid or does not satisfy business rules.
        HTTP 500 `PAYERS-API.INTERNAL-ERROR` - unexpected error, e.g. RecipientKyc could not be
        tokenized. Nothing was confirmed.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmTransactionPayoutRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/ConfirmTransactionPayoutRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmTransactionPayoutResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags: [Transactions]
      operationId: reverseTransactionPayout
      summary: Reverse transaction payout confirmation
      description: |
        Reverses payout confirmation submitted before. Transaction transitions from `PAID` back to
        `PENDING` status (transaction processing has to be started from scratch).

        Payout confirmation can be reversed within 24h since payout has been confirmed.

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction payout confirmation cannot be reversed.
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReverseTransactionPayoutRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/ReverseTransactionPayoutRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReverseTransactionPayoutResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/transactions/{id}/payout-rejection:
    post:
      tags: [Transactions]
      operationId: rejectTransactionPayout
      summary: Reject transaction payout
      description: |
        Rejects transaction in `READY-FOR-PAYOUT`. Transitions transaction from `READY-FOR-PAYOUT`
        to `REJECTED` status.

        Rejecting the transaction requires PayoutToken generated before to be passed
        (see `POST {id}/payout-assignment`).

        Errors:
        HTTP 403 `PAYERS-API.FORBIDDEN` - client is not allowed to use that service.
        HTTP 404 `PAYERS-API.NOT-FOUND` - transaction not found.
        HTTP 409 `PAYERS-API.PAYOUT-TOKEN-MISMATCH` - specified in request PayoutToken is invalid.
        HTTP 409 `PAYERS-API.CONFLICT` - transaction is not assigned to payout or its status is
        not `READY-FOR-PAYOUT`.

        Rejection requires ReasonCode to be specified (see `RejectReasonCode`).
      parameters:
        - $ref: "#/components/parameters/TransactionId"
        - $ref: "#/components/parameters/ApiVersion"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RejectTransactionPayoutRequest"
          application/vnd.tranzmit.payers-api+json:
            schema:
              $ref: "#/components/schemas/RejectTransactionPayoutRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectTransactionPayoutResponse"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

components:
  parameters:
    TransactionId:
      name: id
      in: path
      required: true
      schema:
        type: string
    ApiVersion:
      name: api-version
      in: header
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    InternalServerError:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
  securitySchemes:
    oauth-client-credentials:
      type: oauth2
      description: Client credentials flow
      flows:
        clientCredentials:
          tokenUrl: https://sso.stg.tranzmit.net/oauth2/token
          scopes: {}
  schemas:
    AdditionalInfoRequest:
      type: object
      additionalProperties:
        type: string
        nullable: true
      description: |-
        additional info (optional), up to 5 key-value pairs
        key max length 60 characters
        value max length 500 characters
      nullable: true
    AcknowledgeTransactionResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    AssignTransactionPayoutRequest:
      required: [version]
      type: object
      properties:
        clientToken:
          type: string
          description: |-
            client token (optional), free text, max length 64 characters

            token allowing request to be retried multiple times to overcome transient communication errors,
            calling current endpoint multiple times with the same `clientToken` results in identical response
          nullable: true
        version:
          minimum: 0
          type: integer
          format: int32
          description: >-
            transaction version client is aware of. Provided version should match with current
            transaction version for successful assignment
        agent:
          type: string
          description: payer agent (optional), free text, max length 60 characters
          nullable: true
        additionalInfo:
          $ref: "#/components/schemas/AdditionalInfoRequest"
      additionalProperties: false
    AssignTransactionPayoutResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
        payoutToken:
          type: string
          description: |-
            payout token. Token is mandatory to perform all subsequent transaction update operations.

            payout token authorizes caller for exclusive access to transaction, thus is exposed only once
            here in response. Therefore in case of transient error (due to network glitch) `payoutToken`
            value might get lost with no possibility to retrieve it.

            In order to gracefully handle transient errors with retry use `clientToken` request parameter,
            calling current endpoint multiple times with the same `clientToken` results in identical
            response, containing `payoutToken`
          nullable: true
      additionalProperties: false
    UnassignTransactionPayoutRequest:
      required: [payoutToken]
      type: object
      properties:
        payoutToken:
          minLength: 1
          type: string
          description: payout token
        reason:
          type: string
          description: unassignment reason (optional), free text, max length 500 characters
          nullable: true
      additionalProperties: false
    UnassignTransactionPayoutResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    CreateTransactionPayoutUpdateRequest:
      required: [note, payoutToken, type]
      type: object
      properties:
        payoutToken:
          minLength: 1
          type: string
          description: payout token
        type:
          minLength: 1
          type: string
          description: >-
            Update type. COMPLIANCE for the result of the compliance check you run on
            the transaction; COMMENT for free text.
          enum: [COMPLIANCE, COMMENT]
          example: COMPLIANCE
        note:
          maxLength: 500
          minLength: 1
          type: string
          description: note, free text, max length 500 characters
        additionalInfo:
          $ref: "#/components/schemas/AdditionalInfoRequest"
      additionalProperties: false
    CreateTransactionPayoutUpdateResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    ConfirmTransactionPayoutRequest:
      required: [clientTimestampUtc, payoutToken]
      type: object
      properties:
        payoutToken:
          minLength: 1
          type: string
          description: payout token
        clientTimestampUtc:
          type: string
          format: date-time
          description: utc timestamp of payout event in payer/client system
        additionalInfo:
          $ref: "#/components/schemas/AdditionalInfoRequest"
        recipientKyc:
          $ref: "#/components/schemas/RecipientKycRequest"
      additionalProperties: false
    ConfirmTransactionPayoutResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    ReverseTransactionPayoutRequest:
      type: object
      properties:
        reason:
          type: string
          description: payout reversal reason (optional), free text, max length 500 characters
          nullable: true
      additionalProperties: false
    ReverseTransactionPayoutResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    RejectReasonCode:
      type: string
      description: rejection reason code
      enum:
        - PAYERS-API.REJECT.PAYOUT-ATTEMPT-FAILED
        - PAYERS-API.REJECT.INVALID-OR-EXPIRED-DATA
        - PAYERS-API.REJECT.INVALID-FX-OR-AMOUNT-CONVERSION
        - PAYERS-API.REJECT.INVALID-SENDER-ADDRESS
        - PAYERS-API.REJECT.INVALID-SENDER-DATE-OF-BIRTH
        - PAYERS-API.REJECT.INVALID-RECIPIENT-ADDRESS
        - PAYERS-API.REJECT.INVALID-RECIPIENT-ACCOUNT
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-BLOCKED-OR-CANCELLED
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-UNAVAILABLE
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-NOT-REGISTERED
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-NAME-MISMATCH
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-CURRENCY-MISMATCH
        - PAYERS-API.REJECT.RECIPIENT-ACCOUNT-TYPE-INVALID
        - PAYERS-API.REJECT.MAX-SEND-AMOUNT-EXCEEDED
        - PAYERS-API.REJECT.INSUFFICIENT-ACCOUNT-BALANCE
        - PAYERS-API.REJECT.INVALID-AMOUNT-TO-PAYER
        - PAYERS-API.REJECT.PAYER-LIMIT-EXCEEDED
        - PAYERS-API.REJECT.PAYER-COMPLIANCE-REJECTION
        - PAYERS-API.REJECT.UNKNOWN
    RejectTransactionPayoutRequest:
      required: [clientTimestampUtc, payoutToken, reasonCode]
      type: object
      properties:
        payoutToken:
          minLength: 1
          type: string
          description: payout token
        reasonCode:
          $ref: "#/components/schemas/RejectReasonCode"
        reason:
          type: string
          description: rejection reason (optional), free text, max length 500 characters
          nullable: true
        clientTimestampUtc:
          type: string
          format: date-time
          description: utc timestamp of rejection event in payer/client system
        additionalInfo:
          $ref: "#/components/schemas/AdditionalInfoRequest"
      additionalProperties: false
    RejectTransactionPayoutResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    FindTransactionByIdResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    FindTransactionByRefNumResponse:
      type: object
      properties:
        transaction:
          $ref: "#/components/schemas/Transaction"
      additionalProperties: false
    QueryAvailableTransactionsResponse:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: "#/components/schemas/Transaction"
          description: transactions
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      description: >-
        Problem Details. `title` carries the error code (PAYERS-API.FORBIDDEN, PAYERS-API.REQUEST-CANCELLED,
        PAYERS-API.INTERNAL-ERROR, PAYERS-API.NOT-FOUND, PAYERS-API.CONFLICT, PAYERS-API.PAYOUT-TOKEN-MISMATCH,
        PAYERS-API.RECIPIENT-KYC-REQUIRED, PAYERS-API.RECIPIENT-KYC-BUSINESS-RULE-VIOLATION; new codes may be added).
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    Transaction:
      type: object
      description: >-
        A money transfer transaction. Amounts come duplicated: the integer field is in
        the smallest currency unit (cents) and the Decimal field is the same figure
        with decimals.
      example:
        id: 9f2c4a1e-77b3-4d20-a6e1-3c8f0b5d9a44
        referenceNumber: "8451207733"
        network: TRANZMIT
        payerCode: GT-BANCO-EJEMPLO
        sendingAmount: 20000
        sendingCurrency: USD
        sendingAmountDecimal: 200.00
        receivingAmount: 153400
        receivingCurrency: GTQ
        receivingAmountDecimal: 1534.00
        settlementAmount: 20000
        settlementCurrency: USD
        settlementAmountDecimal: 200.00
        sellRate: 7.67
        status: PENDING
        deliveryMethod: BANK-DEPOSIT
        sender:
          firstName: Carlos
          middleName: Alberto
          lastName: Morales
          mothersMaidenName: Lopez
          phone: "+15551234567"
          homeAddress:
            line1: 742 Evergreen Terrace
            line2: Apt 3B
            city: Los Angeles
            state: CA
            country: US
        recipient:
          firstName: Maria
          middleName: Jose
          lastName: Ramirez
          mothersMaidenName: Chavez
          phone: "+50255551234"
          homeAddress:
            line1: 5a Avenida 10-20 Zona 1
            line2: Edificio Centro, oficina 4
            city: Guatemala
            state: Guatemala
            country: GT
        bankDepositDetails:
          account: "1234567890"
          accountType: SAVINGS
          branch: "001"
        created: "2026-10-15T14:32:08Z"
        updated: "2026-10-15T14:32:08Z"
        version: 1
      properties:
        id:
          type: string
          description: transaction id
          nullable: true
          readOnly: true
        referenceNumber:
          type: string
          description: |-
            transaction reference number
            Primary reconciliation ID
          nullable: true
          readOnly: true
        network:
          type: string
          description: transaction network
          nullable: true
          readOnly: true
        payerCode:
          type: string
          description: payer code
          nullable: true
          readOnly: true
        sendingAmount:
          type: integer
          format: int32
          description: sending amount, positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency)
          readOnly: true
        sendingCurrency:
          type: string
          description: sending currency, three-letter ISO 4217 currency code in lowercase
          nullable: true
          readOnly: true
        sendingAmountDecimal:
          type: number
          format: double
          description: decimal sending amount, positive decimal representation of `SendingAmount`
          readOnly: true
        receivingAmount:
          type: integer
          format: int32
          description: receiving amount, positive integer in the smallest currency unit
          readOnly: true
        receivingCurrency:
          type: string
          description: receiving currency, three-letter ISO 4217 currency code in lowercase
          nullable: true
          readOnly: true
        receivingAmountDecimal:
          type: number
          format: double
          description: decimal receiving amount, positive decimal representation of `ReceivingAmount`
          readOnly: true
        settlementAmount:
          type: integer
          format: int32
          description: settlement amount, positive integer in the smallest currency unit
          readOnly: true
        settlementCurrency:
          type: string
          description: settlement currency, three-letter ISO 4217 currency code in lowercase
          nullable: true
          readOnly: true
        settlementAmountDecimal:
          type: number
          format: double
          description: decimal settlement amount, positive decimal representation of `SettlementAmount`
          readOnly: true
        sellRate:
          type: number
          format: double
          description: exchange sell rate
          readOnly: true
        status:
          type: string
          description: Transaction status.
          enum: [PENDING, READY-FOR-PAYOUT, PAID, REJECTED, CANCELLED, null]
          example: PENDING
          nullable: true
          readOnly: true
        sender:
          $ref: "#/components/schemas/Sender"
        recipient:
          $ref: "#/components/schemas/Recipient"
        deliveryMethod:
          type: string
          description: How the funds are delivered to the recipient.
          enum: [BANK-DEPOSIT, OFFICE-PICKUP, HOME-DELIVERY, ATM-PICKUP, MOBILE-WALLET, null]
          example: BANK-DEPOSIT
          nullable: true
          readOnly: true
        bankDepositDetails:
          $ref: "#/components/schemas/BankDepositDetails"
        officePickupDetails:
          $ref: "#/components/schemas/OfficePickupDetails"
        acknowledgement:
          $ref: "#/components/schemas/TransactionAcknowledgement"
        payout:
          $ref: "#/components/schemas/Payout"
        created:
          type: string
          format: date-time
          description: creation date-time in ISO-8601 format, utc
          readOnly: true
        updated:
          type: string
          format: date-time
          description: update date-time in ISO-8601 format, utc
          readOnly: true
        version:
          type: integer
          format: int32
          description: version
          readOnly: true
      additionalProperties: false
    TransactionAcknowledgement:
      type: object
      properties:
        payerId:
          type: string
          description: payer id
          nullable: true
          readOnly: true
        created:
          type: string
          format: date-time
          description: acknowledgement creation date-time in ISO-8601 format, utc
          readOnly: true
        transactionVersion:
          type: integer
          format: int32
          description: acknowledged transaction version
          readOnly: true
      additionalProperties: false
    Sender:
      type: object
      properties:
        firstName: {type: string, description: first name, nullable: true, readOnly: true}
        lastName: {type: string, description: last name, nullable: true, readOnly: true}
        middleName: {type: string, description: middle name, nullable: true, readOnly: true}
        mothersMaidenName: {type: string, description: "mother's maiden name", nullable: true, readOnly: true}
        phone: {type: string, description: phone number, nullable: true, readOnly: true}
        homeAddress:
          $ref: "#/components/schemas/SenderAddress"
      additionalProperties: false
    SenderAddress:
      type: object
      properties:
        country: {type: string, description: "country, alpha-2 ISO 3166 country code in upper case", nullable: true, readOnly: true}
        state: {type: string, description: state/province, nullable: true, readOnly: true}
        city: {type: string, description: city, nullable: true, readOnly: true}
        line1: {type: string, description: street address line 1, nullable: true, readOnly: true}
        line2: {type: string, description: street address line 2, nullable: true, readOnly: true}
      additionalProperties: false
    Recipient:
      type: object
      properties:
        firstName: {type: string, description: first name, nullable: true, readOnly: true}
        lastName: {type: string, description: last name, nullable: true, readOnly: true}
        middleName: {type: string, description: middle name, nullable: true, readOnly: true}
        mothersMaidenName: {type: string, description: "mother's maiden name", nullable: true, readOnly: true}
        phone: {type: string, description: phone number, nullable: true, readOnly: true}
        homeAddress:
          $ref: "#/components/schemas/RecipientAddress"
      additionalProperties: false
    RecipientAddress:
      type: object
      properties:
        country: {type: string, description: "country, alpha-2 ISO 3166 country code in upper case", nullable: true, readOnly: true}
        state: {type: string, description: state/province, nullable: true, readOnly: true}
        city: {type: string, description: city, nullable: true, readOnly: true}
        line1: {type: string, description: street address line 1, nullable: true, readOnly: true}
        line2: {type: string, description: street address line 2, nullable: true, readOnly: true}
      additionalProperties: false
    BankDepositDetails:
      type: object
      properties:
        account: {type: string, description: account number, nullable: true, readOnly: true}
        accountType:
          type: string
          description: Recipient account type.
          enum: [CHECKING, SAVINGS, null]
          example: SAVINGS
          nullable: true
          readOnly: true
        branch: {type: string, description: branch, nullable: true, readOnly: true}
      additionalProperties: false
    OfficePickupDetails:
      type: object
      properties:
        locationId: {type: string, description: location id, nullable: true, readOnly: true}
      additionalProperties: false
    Payout:
      type: object
      properties:
        payerId:
          type: string
          description: payer id
          nullable: true
          readOnly: true
        assignment:
          $ref: "#/components/schemas/PayoutAssignment"
        confirmation:
          $ref: "#/components/schemas/PayoutConfirmation"
        rejection:
          $ref: "#/components/schemas/PayoutRejection"
        expiresAfter:
          type: string
          format: date-time
          description: payout expires after date-time in ISO-8601 format, utc
          nullable: true
          readOnly: true
      additionalProperties: false
    PayoutAssignment:
      type: object
      properties:
        agent: {type: string, description: agent, nullable: true, readOnly: true}
        additionalInfo:
          type: object
          additionalProperties: {type: string, nullable: true}
          description: additional info
          nullable: true
          readOnly: true
        created: {type: string, format: date-time, description: "create date-time in ISO-8601 format, utc", readOnly: true}
      additionalProperties: false
    PayoutConfirmation:
      type: object
      properties:
        additionalInfo:
          type: object
          additionalProperties: {type: string, nullable: true}
          description: additional info
          nullable: true
          readOnly: true
        clientTimestamp: {type: string, format: date-time, description: "client timestamp in ISO-8601 format, utc", readOnly: true}
        created: {type: string, format: date-time, description: "create date-time in ISO-8601 format, utc", readOnly: true}
      additionalProperties: false
    PayoutRejection:
      type: object
      properties:
        reasonCode:
          allOf:
            - $ref: "#/components/schemas/RejectReasonCode"
          type: string
          nullable: true
          readOnly: true
        reason: {type: string, description: reason, nullable: true, readOnly: true}
        additionalInfo:
          type: object
          additionalProperties: {type: string, nullable: true}
          description: additional info
          nullable: true
          readOnly: true
        clientTimestamp: {type: string, format: date-time, description: "client timestamp in ISO-8601 format, utc", readOnly: true}
        created: {type: string, format: date-time, description: "create date-time in ISO-8601 format, utc", readOnly: true}
      additionalProperties: false
    RecipientKycRequest:
      required:
        - address
        - countryOfBirth
        - dateOfBirth
        - document
        - firstName
        - gender
        - guatemala
        - lastName
        - maritalStatus
        - nationality
        - phoneNumber
        - professionOrTrade
      type: object
      properties:
        lastName: {type: string, minLength: 1}
        secondLastName: {type: string, nullable: true}
        firstName: {type: string, minLength: 1}
        middleName: {type: string, nullable: true}
        dateOfBirth: {type: string, format: date}
        countryOfBirth: {type: string, minLength: 1}
        stateOfBirth: {type: string, nullable: true}
        cityOfBirth: {type: string, nullable: true}
        immigrationStatus: {type: string, nullable: true}
        gender: {type: string, minLength: 1}
        maritalStatus: {type: string, minLength: 1}
        professionOrTrade: {type: string, minLength: 1}
        document:
          $ref: "#/components/schemas/RecipientKycDocumentRequest"
        taxIdentificationNumber: {type: string, nullable: true}
        emailAddress: {type: string, nullable: true}
        address:
          $ref: "#/components/schemas/RecipientKycAddressRequest"
        nationality: {type: string, minLength: 1}
        phoneNumber: {type: string, minLength: 1}
        guatemala:
          $ref: "#/components/schemas/GuatemalaKycRequest"
      additionalProperties: false
    RecipientKycDocumentRequest:
      type: object
      properties:
        identificationType: {type: string, nullable: true}
        identificationNumber: {type: string, nullable: true}
        identificationIssuerCountry: {type: string, nullable: true}
        identificationIssueDate: {type: string, format: date, nullable: true}
        identificationExpiryDate: {type: string, format: date, nullable: true}
      additionalProperties: false
    RecipientKycAddressRequest:
      type: object
      properties:
        residentialAddress: {type: string, nullable: true}
        countryOfResidence: {type: string, nullable: true}
        stateOfResidence: {type: string, nullable: true}
        cityOfResidence: {type: string, nullable: true}
      additionalProperties: false
    GuatemalaKycRequest:
      type: object
      properties:
        pep:
          $ref: "#/components/schemas/PoliticallyExposedPersonRequest"
        apep:
          $ref: "#/components/schemas/AssociatedPoliticallyExposedPersonRequest"
        cpe: {type: boolean, nullable: true}
        monthlyIncome: {type: number, format: double, nullable: true}
        monthlyExpenses: {type: number, format: double, nullable: true}
        relationshipWithSender: {type: string, nullable: true}
        businessTradeName: {type: string, nullable: true}
        employerName: {type: string, nullable: true}
        otherIncome: {type: string, nullable: true}
        incomeDescription: {type: string, nullable: true}
        paymentState: {type: string, nullable: true}
        paymentCity: {type: string, nullable: true}
      additionalProperties: false
    PoliticallyExposedPersonRequest:
      type: object
      properties:
        publicEntityOfEmployment: {type: string, nullable: true}
        positionHeld: {type: string, nullable: true}
        countryOfEntity: {type: string, nullable: true}
        originOrSourceOfWealth: {type: string, nullable: true}
      additionalProperties: false
    AssociatedPoliticallyExposedPersonRequest:
      type: object
      properties:
        relationship: {type: string, nullable: true}
        associationMotive: {type: string, nullable: true}
        gender: {type: string, nullable: true}
        immigrationStatus: {type: string, nullable: true}
        firstName: {type: string, nullable: true}
        middleName: {type: string, nullable: true}
        lastName: {type: string, nullable: true}
        secondLastName: {type: string, nullable: true}
        publicEntityOfEmployment: {type: string, nullable: true}
        positionHeld: {type: string, nullable: true}
        countryOfEntity: {type: string, nullable: true}
        originOrSourceOfWealth: {type: string, nullable: true}
      additionalProperties: false
