openapi: 3.0.0
info:
  title: Gateway
  version: '1.0'
  license:
    name: Privative
  description: |-
    Este servicio web y su arquitectura permite a cualquier aplicación conectarse a Placetopay para procesar transacciones, independiente del lenguaje de desarrollo.
    Para usar el servicio web, deberás tener un lenguaje de programación que pueda comunicarse con un servicio REST.
    El método de integración contempla las operaciones básicas para el procesamiento de tarjetas no presenciales, esto es tipos de crédito, intereses, generación de OTP, autorización, reembolso.
    A continuación se describirán cada uno de los usos y los datos requeridos en la trama para cada uno de los casos.  La respuesta para cada operación está unificada en un solo tipo de trama resultante.
    Por defecto el lenguaje de las respuestas es en español, si se desea cambiar es necesario enviar el parámetro `locale` en las peticiones.
    ### Servicios
    Todos los consumos se realizan a la URL base, que será proporcionada por el área de operaciones y se le adiciona a dicha URL el endpoint del servicio a consumir.
    Por ejemplo si la URL base fuese https://placetopay.com para consumir el servicio se solicitud de información se realiza un POST con los datos del ejemplo a la URL https://placetopay.com/gateway/information
  contact:
    name: Evertec Placetopay
    email: servicioposventa@placetopay.com
servers:
  - url: https://api-co-dev.placetopay.ws
    description: Pruebas Colombia
  - url: https://api-ec-dev.placetopay.ws
    description: Pruebas Ecuador
tags:
  - name: Obtener información
    description: Una vez se tengan los datos de la tarjeta permite determinar el flujo a seguir
  - name: Procesamiento de transacción
    description: Diferentes formas de procesar una petición
  - name: Consulta de una transacción
    description: Busqueda de información sobre una o más transacciones realizadas
  - name: Acciones sobre transacciones
    description: Permite realizar operaciones como anulación, checkout, procesar una transacción manual
  - name: Tokenización de tarjetas
    description: Permite almacenar de forma segura una tarjeta para realizar procesos de cobro automáticos posteriormente
  - name: Proceso 3DS
    description: Validar la transacción mediante 3DS
  - name: Proceso OTP
    description: Permite generar y posteriormente validar un One Time Password cuando se requiera
  - name: Operaciones con Pinpad
    description: Permite realizar validación de PIN con un Pinpad seguro
  - name: Reporte de operaciones realizadas
    description: Permite obtener un reporte de todas las transacciones realizadas en un periodo de tiempo para el sitio usado
  - name: Account validator
    description: Permite consumir los endpoints de account validator de forma mas segura
paths:
  /gateway/information:
    post:
      summary: Solicitud de Información
      operationId: post-rest-gateway-information
      description: Este servicio proporciona información sobre la tarjeta del usuario que se va a procesar, tal como qué servicios son los que se usarán para ella y los tipos de crédito, si aplica, que hay para esta, si no hay tipos de crédito se retorna un arreglo vacío y si los hay, se debe iterar cada tipo de crédito con los installments que se encuentran en el arreglo.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - title: Tarjeta
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determina el idioma de la respuesta
                      example: es-CO
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    instrument:
                      $ref: '#/components/schemas/Instrument'
                    payment:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                    subscription:
                      $ref: '#/components/schemas/Subscription'
                    metadata:
                      type: object
                      description: Objeto dinámico que contiene información adicional de interés.
                      properties:
                        preferredPaymentMethodIndex:
                          type: integer
                          description: Índice de medio de pago a seleccionar dentro de una lista de medios de pago disponibles. Este campo es requerido solo cuando se desee emplear el flujo de orquestador de pagos.
                          example: 2
                - title: Paystudio TS
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determina el idioma de la respuesta
                      example: es-CO
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    instrument:
                      $ref: '#/components/schemas/Instrument'
                    payment:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: PSE
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    locale:
                      type: string
                    payer:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payer'
                    payment:
                      type: object
                      description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                    instrument:
                      type: object
                      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
                      properties:
                        redirection:
                          type: object
                          description: Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso.
                          properties:
                            paymentMethod:
                              type: string
                              enum:
                                - _PSE_
                            returnURL:
                              type: string
                              format: uri
                              example: http://your-site.com/your-return-route
                              maxLength: 250
                              description: URL para que una vez se termine el proceso de pago se retorne el control.
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: Botón Bancolombia
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    locale:
                      type: string
                    payer:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payer'
                    payment:
                      type: object
                      description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                    instrument:
                      type: object
                      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
                      properties:
                        redirection:
                          type: object
                          description: Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso.
                          properties:
                            paymentMethod:
                              type: string
                              enum:
                                - BTNBC
                            returnURL:
                              type: string
                              format: uri
                              example: http://your-site.com/your-return-route
                              maxLength: 250
                              description: URL para que una vez se termine el proceso de pago se retorne el control.
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: Botón Aval
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    payment:
                      type: object
                      description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                    instrument:
                      type: object
                      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
                      properties:
                        redirection:
                          type: object
                          description: Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso.
                          properties:
                            paymentMethod:
                              type: string
                              enum:
                                - BTNAV
                            returnURL:
                              type: string
                              format: uri
                              example: http://your-site.com/your-return-route
                              maxLength: 250
                              description: URL para que una vez se termine el proceso de pago se retorne el control.
                    locale:
                      type: string
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: CeroPay
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determina el idioma de la respuesta
                      example: es-CO
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    payment:
                      type: object
                      description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          title: Amount
                          type: object
                          description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                          required:
                            - currency
                            - total
                          properties:
                            currency:
                              type: string
                              enum:
                                - COP
                              example: COP
                              minLength: 3
                              maxLength: 3
                            total:
                              type: number
                            taxes:
                              type: array
                              items:
                                title: TaxDetail
                                type: object
                                description: Estructura para almacenar información sobre un impuesto.
                                properties:
                                  kind:
                                    type: string
                                    example: valueAddedTax
                                    description: Tipo de impuesto reportado
                                    enum:
                                      - valueAddedTax
                                      - exciseDuty
                                      - ice
                                      - airportTax
                                      - stateTax
                                      - reducedStateTax
                                      - municipalTax
                                  amount:
                                    type: number
                                    description: |
                                      Monto total del impuesto
                                  base:
                                    description: |
                                      Monto base sobre el cual se calcula el impuesto
                                    type: number
                            details:
                              type: array
                              items:
                                title: AmountDetail
                                type: object
                                description: Estructura para almacenar información sobre un valor adicional.
                                properties:
                                  kind:
                                    type: string
                                    description: |
                                      Identificador del tipo de detalle.
                                  amount:
                                    type: number
                                    description: |
                                      Monto total del detalle
                    instrument:
                      type: object
                      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
                      properties:
                        redirection:
                          type: object
                          description: Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso.
                          properties:
                            paymentMethod:
                              type: string
                              enum:
                                - BB_CP
                            returnURL:
                              type: string
                              format: uri
                              example: http://your-site.com/your-return-route
                              maxLength: 250
                              description: URL para que una vez se termine el proceso de pago se retorne el control.
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1234567890'
                    description: Testing Payment
                    amount:
                      currency: COP
                      total: '3000'
                  instrument:
                    card:
                      number: '4110760000000008'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      tags:
        - Obtener información
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - title: Tarjeta
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: EBUS
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: EB_VS
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor
                        items:
                          $ref: '#/components/schemas/Credit'
                      requirePockets:
                        type: boolean
                        description: Indica si es requerido bolsillo para el procesamiento de la transacción
                      pockets:
                        type: array
                        description: Estructura que contiene los bolsillos de la tarjeta
                        items:
                          $ref: '#/components/schemas/Pocket'
                      requireAvs:
                        type: boolean
                        description: Indica si es requerida la información de código postal
                      zipCodeFormat:
                        type: string
                        description: Formato a ser utilizado para la validación del código postal
                        nullable: 'true'
                      accountVerification:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de verificación de cuentas
                      requirePin:
                        type: boolean
                        description: Indica si es necesario pin para procesar la transacción
                      requireRedirection:
                        type: boolean
                        description: Indica si el medio de pago es del tipo redirección
                      bankList:
                        type: array
                        description: Lista de bancos disponibles para procesar un pago
                        items:
                          $ref: '#/components/schemas/BankItem'
                      requireBalance:
                        type: boolean
                        description: Indica si es requerido el consumo del servicio de balance
                      hasForwarding:
                        type: boolean
                        description: Indica si el medio de pago tiene configurado enrutamiento transaccional
                      availablePaymentMethods:
                        type: integer
                        description: Indica el total de medios de pago disponibles para procesar. Se indicará en la respuesta solo si se trata de selección de servicio por medio de índice.
                      requireCardExpiration:
                        type: boolean
                        description: Indica si se requiere la fecha de vencimiento de la tarjeta para procesar la transacción.
                      allowedDocumentTypes:
                        type: array
                        description: Indica los tipos de documentos permitidos para la transacción.
                        items:
                          type: string
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Paystudio TS
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: PAYSTUDIO
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: PS_VS
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indica si es requerido mostrar los intereses de la transacción
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor. Estructura bajo el modelo **estructura por cuota**. Ver más en [Crédito](/gateway/additional-data#additional-data-credit)
                        items:
                          $ref: '#/components/schemas/CreditPerInstallment'
                      hasForwarding:
                        type: boolean
                        description: Indica si el medio de pago tiene configurado enrutamiento transaccional
                      requireCardExpiration:
                        type: boolean
                        description: Indica si se requiere la fecha de vencimiento de la tarjeta para procesar la transacción.
                      allowedDocumentTypes:
                        type: array
                        description: Indica los tipos de documentos permitidos para la transacción.
                        items:
                          type: string
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: PSE
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: ACH
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: _PSE_
                      requireRedirection:
                        type: boolean
                        description: Indica si el medio de pago es del tipo redirección
                      bankList:
                        type: array
                        description: Lista de bancos disponibles para procesar un pago
                        items:
                          $ref: '#/components/schemas/BankItem'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indica si es requerido mostrar los intereses de la transacción
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor
                        items:
                          $ref: '#/components/schemas/Credit'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Botón Bancolombia
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: BANCOLOMBIA
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: BTNBC
                      requireRedirection:
                        type: boolean
                        description: Indica si el medio de pago es del tipo redirección
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indica si es requerido mostrar los intereses de la transacción
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor
                        items:
                          $ref: '#/components/schemas/Credit'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Botón Aval
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: AVAL
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: BTNAV
                      requireRedirection:
                        type: boolean
                        description: Indica si el medio de pago es del tipo redirección
                      bankList:
                        type: array
                        description: Lista de bancos disponibles para procesar un pago
                        items:
                          $ref: '#/components/schemas/BankItem'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indica si es requerido mostrar los intereses de la transacción
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor
                        items:
                          $ref: '#/components/schemas/Credit'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: CeroPay
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: BANCO_BOGOTA
                        description: Indica cual proveedor será utilizado en la transacción
                      serviceCode:
                        type: string
                        description: Indica el código del servicio que procesará la transacción
                        example: BB_CP
                      requireRedirection:
                        type: boolean
                        description: Indica si el medio de pago es del tipo redirección
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indica los tipos de tarjeta soportados por el proveedor
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indica si es requerido mostrar los intereses de la transacción
                      requiereOtp:
                        type: boolean
                        description: Indica si es necesario realizar el flujo de OTP
                      requiereCvv2:
                        type: boolean
                        description: Indica si es requerido enviar CVV para el procesamiento de la transacción
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indica si es necesario 3DS
                      credits:
                        type: array
                        description: Indica los créditos disponibles por proveedor
                        items:
                          $ref: '#/components/schemas/Credit'
                    required:
                      - status
                      - provider
                      - serviceCode
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-09-21T09:26:11-05:00'
                    provider: CREDIBANCO
                    serviceCode: CR_VS
                    cardType: C
                    cardTypes:
                      - C
                      - R
                      - A
                    displayInterest: 'false'
                    requireOtp: 'false'
                    requireCvv2: 'true'
                    threeDS: optional
                    requireCardExpiration: true
                    allowedDocumentTypes:
                      - CLRUT
                    credits:
                      - description: Cuotas
                        code: '0'
                        groupCode: C
                        type: '00'
                        installments:
                          - '1'
                          - '2'
                          - '3'
                          - '4'
                          - '5'
                          - '6'
                          - '7'
                          - '8'
                          - '9'
                          - '10'
                          - '11'
                          - '12'
                          - '13'
                          - '14'
                          - '15'
                          - '16'
                          - '17'
                          - '18'
                          - '19'
                          - '20'
                          - '21'
                          - '22'
                          - '23'
                          - '24'
                          - '25'
                          - '26'
                          - '27'
                          - '28'
                          - '29'
                          - '30'
                          - '31'
                          - '32'
                          - '33'
                          - '34'
                          - '35'
                          - '36'
  /gateway/process:
    post:
      summary: Procesamiento de transacción
      operationId: post-gateway-process
      description: Este servicio permite que se realice el cobro a la tarjeta del usuario, los parámetros del instrument son variables, si no se pide tipo de crédito ni otp no es necesario enviar esas variables, payer es siempre requerido, buyer es opcional pero recomendado.
      tags:
        - Procesamiento de transacción
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: Este campo debe ser enviado únicamente cuando se realice un proceso de checkin, de lo contrario, no debe ser enviado en la solicitud
                  enum:
                    - checkin
                locale:
                  type: string
                  example: es_CO
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payer:
                  title: Person
                  type: object
                  description: Estructura que refleja la información de una persona involucrada en una transacción.
                  properties:
                    documentType:
                      type: string
                      description: '[Tipo de documento de identificación](/gateway/document-types)'
                      example: CC
                      maxLength: '6'
                    document:
                      type: string
                      description: Número de documento de identificación. Debe ser un número válido de acuerdo al tipo de documento. Ver más en [Tipos de documento de identificación](/gateway/document-types)
                      maxLength: '25'
                    name:
                      type: string
                      description: Nombre
                      maxLength: '60'
                    surname:
                      type: string
                      description: Apellidos
                      maxLength: '60'
                    company:
                      type: string
                      description: Compañia
                      maxLength: '60'
                    email:
                      type: string
                      description: Correo electrónico.
                      maxLength: '80'
                    address:
                      $ref: '#/components/schemas/Payer/properties/address'
                      description: Objeto que contiene información de la dirección de una persona.
                    mobile:
                      type: string
                      description: Teléfono movil
                buyer:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payer'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  title: Payment
                  type: object
                  description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                  properties:
                    reference:
                      type: string
                      minLength: 1
                      maxLength: 32
                    description:
                      type: string
                      maxLength: 250
                    amount:
                      $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                    dispersion:
                      type: array
                      items:
                        title: Dispersion
                        type: object
                        description: Estructura que contiene la información requerida para un pago de dispersión
                        properties:
                          agreement:
                            type: number
                            description: Identificador de destinatario de la transacción. Para el sitio principal de la transacción, el valor debe ser null.
                            nullable: true
                          agreementType:
                            type: string
                            enum:
                              - AIRLINE
                              - MERCHANT
                          amount:
                            $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                    modifiers:
                      type: array
                      description: Estructura que contiene modificadores de pago
                      items:
                        title: PaymentModifier
                        type: object
                        description: |-
                          Estructura para almacenar información sobre un modificador de pago.
                          NOTA: Si se envia un modificador que aplica descuento, no se tomará los descuentos configurados por promociones en el sítio.
                        x-examples:
                          law-discount:
                            type: FEDERAL_GOVERNMENT
                            code: '17934'
                            additional:
                              invoice: '123456'
                        properties:
                          type:
                            type: string
                            enum:
                              - FEDERAL_GOVERNMENT
                            description: Tipo de modificador
                          code:
                            type: string
                            example: '17934'
                            description: Código del modificador. Cuando el tipo es FEDERAL_GOVERMENT, representa el número de ley para descuento.
                          additional:
                            type: object
                            description: Informaciones adicionales del modificador
                            properties:
                              invoice:
                                type: string
                                description: Número de factura. Requerido cuando tipo es FEDERAL_GOVERMENT.
                    shipping:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payer'
                      description: Estructura para relacionar información de envío.
                    items:
                      type: array
                      items:
                        description: Posee una colección de estructuras de elementos.
                        title: Item
                        type: object
                        properties:
                          sku:
                            type: string
                            minLength: 1
                            maxLength: 30
                            description: |
                              Identificador SKU del artículo.   
                              EJ: `SKU-12345`
                            example: SKU-12345
                          id:
                            type: string
                            minLength: 1
                            maxLength: 30
                            description: Id del item
                            example: '12345'
                          description:
                            type: enum
                            description: Descripción del artículo.
                            example: Descripción del artículo
                          name:
                            type: enum
                            description: |
                              Nombre del artículo.   
                              EJ: `Manta de lana`
                            example: product_1
                          category:
                            type: string
                            minLength: 1
                            maxLength: 30
                            description: |
                              Categoría del artículo. Uno de: `digital` `physical`
                            enum:
                              - digital
                              - physical
                            example: physical
                          qty:
                            type: number
                            description: |
                              Cantidad de artículos de este tipo.   
                              EJ: `23`
                            example: '1'
                          price:
                            type: number
                            description: |
                              Costo total del artículo.   
                              EJ: `1400`
                            example: 1400
                          tax:
                            type: number
                            description: |
                              Monto en impuestos del artículo.   
                              EJ: `100`
                          additional:
                            type: object
                            description: Es un objeto que permite enviar datos adicionales en formato JSON.
                            nullable: true
                      description: |
                        Estructura para relacionar productos o artículos en el proceso.
                additional:
                  type: object
                  description: |
                    Objeto dinámico clave valor de información que se desee guardar con la transacción. Las siguientes claves **NO** son permitidas: `_accountNumber`, `userAgent`, `fingerprint`, `sourcePlatform`, `tokenizationID`, `trazabilyCode`, `transactionCycle`, `RequestId`, `PartnerAuthCode`, `onTest`, `threeDSEnrolled`, `threeDSAuthenticated`.
                    Ver más en [Datos adicionales](/gateway/additional-data)
                metadata:
                  type: object
                  description: |
                    Objeto dinámico clave valor de información adicional que solicitan los servicios externos para ser ejecutados.
                  properties:
                    EBTDeliveryIndicator:
                      type: string
                      enum:
                        - DIRECT_DELIVERY
                        - CUSTOMER_PICKUP
                        - COMMERCIAL_SHIPPING
                        - OTHER
                        - NOT_AVAILABLE
                    openingDate:
                      type: string
                      description: Fecha de apertura del producto. Requerido en transacciones PSE para comercios en la categoría de servicios financieros.
                      example: '2025-04-16'
                    beneficiaryId:
                      type: string
                      description: ID del beneficiario. Requerido en transacciones PSE para comercios en la categoría de servicios financieros.
                      example: '12345'
                    preferredPaymentMethodIndex:
                      type: integer
                      description: Índice de medio de pago a seleccionar dentro de una lista de medios de pago disponibles. Este campo es requerido solo cuando se desee emplear el flujo de orquestador de pagos.
                      example: 2
                    kount:
                      type: object
                      description: Información adicional sobre la transacción que puede ser utilizada para análisis de riesgo y prevención de fraude.
                      properties:
                        account:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                            creationDateTime:
                              type: string
                              format: date-time
                            username:
                              type: string
                            accountIsActive:
                              type: boolean
                        loyalty:
                          type: object
                          properties:
                            id:
                              type: string
                            description:
                              type: string
                            credit:
                              type: object
                              properties:
                                creditType:
                                  type: string
                                amount:
                                  type: integer
                                currency:
                                  type: string
                                  description: Currency code (ISO 4217)
                        promotions:
                          type: object
                          properties:
                            id:
                              type: string
                            description:
                              type: string
                            status:
                              type: string
                            statusReason:
                              type: string
                            discount:
                              type: object
                              properties:
                                percentage:
                                  type: number
                                amount:
                                  type: integer
                                currency:
                                  type: string
                                  description: Currency code (ISO 4217)
                            credit:
                              type: object
                              properties:
                                creditType:
                                  type: string
                                percentage:
                                  type: number
                                currency:
                                  type: string
                                  description: Currency code (ISO 4217)
                                amount:
                                  type: integer
                        links:
                          type: object
                          properties:
                            viewOrderUrl:
                              type: string
                              format: uri
                            requestRefundUrl:
                              type: string
                              format: uri
                            buyAgainUrl:
                              type: string
                              format: uri
                            writeReviewUrl:
                              type: string
                              format: uri
                        advertising:
                          type: object
                          properties:
                            channel:
                              type: string
                            affiliate:
                              type: string
                            subAffiliate:
                              type: string
                            writeReviewUrl:
                              type: string
                              format: uri
                            events:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: string
                                  value:
                                    type: string
                            campaign:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                        shipping:
                          type: object
                          properties:
                            type:
                              type: string
                              description: Tipo de envío ("SHIPPED", "DIGITAL", "STORE_PICK_UP", "LOCAL_DELIVERY", "STORE_DRIVE_UP", "IN_PERSON").
                            provider:
                              type: string
                              description: Nombre del proveedor de envío o plataforma de entrega digital.
                            trackingNumber:
                              type: string
                              description: Numero de seguimiento del envío físico.
                            shippingMethod:
                              type: string
                              description: Método de envío ("STANDARD", "EXPRESS", "SAME_DAY", "NEXT_DAY", "SECOND_DAY").
                            store:
                              type: object
                              properties:
                                address:
                                  type: object
                                  properties:
                                    street:
                                      type: string
                                      description: Dirección de la tienda para recogida.
                                    city:
                                      type: string
                                    state:
                                      type: string
                                    postalCode:
                                      type: string
                                    country:
                                      type: string
                                    phone:
                                      type: string
                                      description: Número de teléfono de la tienda para recogida.
                            accessUrl:
                              type: string
                              format: uri
                              description: URL de acceso para productos digitales o información de seguimiento para envíos físicos.
                            digitalDownloaded:
                              type: boolean
                              description: Indica si el producto digital ha sido descargado.
                            downloadDeviceIp:
                              type: string
                              format: ipv4
                              description: IP desde la cual se descargó el producto digital.
                        store:
                          type: object
                          description: Información de la tienda física asociada a la transacción.
                          properties:
                            id:
                              type: string
                              description: Identificador de la tienda.
                              example: STORE001
                            name:
                              type: string
                              description: Nombre de la tienda.
                              example: Sucursal centro
                            address:
                              type: object
                              description: Dirección de la tienda.
                              properties:
                                line1:
                                  type: string
                                  description: Primera línea de la dirección.
                                  example: calle 80
                                line2:
                                  type: string
                                  description: Segunda línea de la dirección.
                                  example: casa 3
                                city:
                                  type: string
                                  description: Ciudad de la tienda.
                                  example: Medellin
                                region:
                                  type: string
                                  description: Región o departamento de la tienda.
                                  example: ANTIOQUIA
                                countryCode:
                                  type: string
                                  description: Código del país (ISO 3166-1 alpha-2).
                                  example: CO
                                postalCode:
                                  type: string
                                  description: Código postal de la tienda.
                                  example: '10001'
                    requiresConfirmation:
                      type: boolean
                      description: Indica si la transacción requiere confirmación previo a su procesamiento.
                      example: true
                    interestQueryCode:
                      type: string
                      description: Indica si la cuota cuenta con información disponible para ser aplicada durante el procesamiento de la transacción. Este campo es válido para el servicio **PAYSTUDIO**, *flavour* **TS**, y la información debe estar disponible a través del [servicio de consulta de intereses](/gateway/interests).Si se envía este valor, pero el código proporcionado no es válido o no es retornado por dicho servicio, la transacción será rechazada.
                      example: true
                idempotenceKey:
                  type: string
                  description: Clave única para identificar la transacción. Ver más en [Control de Idempotencia](/gateway/idempotency)
                  example: ABCD1234
                  maxLength: 32
                notificationURL:
                  type: string
                  description: URL a la que se enviará una notificación HTTP con la información de la transacción una vez que esta haya sido procesada. Ver más en [Notificación](/gateway/notification)
                  example: https://your-site.com/your-notification-path
                ipAddress:
                  type: string
                userAgent:
                  type: string
                  example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
                sourcePlatform:
                  type: string
              required:
                - auth
                - payer
                - instrument
                - payment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    example: '2021-09-20T21:51:59-05:00'
                  transactionDate:
                    type: string
                    example: '2021-09-20T21:51:59-05:00'
                  internalReference:
                    type: integer
                    nullable: true
                  reference:
                    type: string
                    minLength: 1
                  paymentMethod:
                    type: string
                    nullable: true
                    minLength: 1
                  franchise:
                    type: string
                    nullable: true
                    minLength: 1
                  franchiseName:
                    type: string
                    nullable: true
                    minLength: 1
                    example: Botón Aval
                  issuerName:
                    type: string
                    minLength: 1
                    nullable: true
                    description: Nombre del banco procesador
                    example: Banco Bogotá
                  amount:
                    $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                  conversion:
                    title: AmountConversion
                    type: object
                    description: Estructura para definir el factor de conversión y los valores.
                    properties:
                      from:
                        $ref: '#/paths/~1cash~1orders/post/requestBody/content/application~1json/schema/properties/payment/properties/amount'
                      to:
                        $ref: '#/paths/~1cash~1orders/post/requestBody/content/application~1json/schema/properties/payment/properties/amount'
                      factor:
                        type: number
                        example: 1
                        description: Factor de conversión
                  authorization:
                    type: string
                    minLength: 1
                    nullable: true
                  receipt:
                    type: string
                    maxLength: 16
                    nullable: true
                  type:
                    type: string
                    minLength: 1
                    enum:
                      - AUTH_ONLY
                      - CHECKIN
                  refunded:
                    type: boolean
                    nullable: true
                  lastDigits:
                    type: string
                    minLength: 1
                    nullable: true
                  provider:
                    type: string
                    nullable: true
                    enum:
                      - ACH
                      - ATH-AVALNET
                      - ATH-MOVIL
                      - AUSTRO
                      - AVAL
                      - BANCOLOMBIA
                      - BRASPAG
                      - COMFANDI
                      - CREDIBANCO
                      - DATAFAST
                      - EBUS
                      - EVERTEC
                      - FLAMINGO
                      - INTERDIN
                      - MEDIANET
                      - PAYSTUDIO
                      - REDEBAN
                      - SABRE
                      - SUPERGIROS
                      - TECNICARD
                      - TRANSERVER
                      - TUYA-DIRECT
                  discount:
                    type: object
                    nullable: true
                    properties:
                      code:
                        type: string
                      type:
                        type: string
                      amount:
                        type: number
                      base:
                        type: number
                      percentage:
                        type: number
                  processorFields:
                    type: object
                    properties:
                      id:
                        type: string
                        nullable: true
                        example: e67122e3b9af1f7f72eacd430996d94b
                      b24:
                        type: string
                        example: '?-'
                      paymentURL:
                        type: string
                        nullable: true
                        example: https://avalpaycenter.labdigbdbstgpb.com/?trazabilityCode=000000437981
                  additional:
                    type: object
                    description: |
                      Ver más en [Datos adicionales](/gateway/additional-data)
                    properties:
                      merchantCode:
                        type: string
                        nullable: true
                        description: Código de entidad
                      terminalNumber:
                        type: string
                        nullable: true
                        description: Número de terminal del medio de pago
                      trazabilyCode:
                        type: string
                      _wcTransactionId_:
                        type: string
                        description: Identificador de transacción en comercio
                  preAuthorization:
                    type: object
                    items:
                      type: object
                      properties:
                        condition:
                          enum:
                            - ACTIVE
                            - PENDING
                            - COMPLETED
                        internalReference:
                          type: integer
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                        salt:
                          type: string
                  dispersion:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                        type:
                          type: string
                          minLength: 1
                          enum:
                            - AUTH_ONLY
                        agreement:
                          type: integer
                          nullable: true
                        agreementType:
                          type: string
                          enum:
                            - AIRLINE
                            - MERCHANT
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                        conversion:
                          $ref: '#/paths/~1gateway~1process/post/responses/200/content/application~1json/schema/properties/conversion'
                        refunded:
                          type: boolean
                        paymentMethod:
                          type: string
                  redirection:
                    $ref: '#/components/schemas/Redirection'
                  notificationURL:
                    type: string
                    description: URL a la que se enviará una notificación HTTP con la información de la transacción una vez que esta haya sido procesada. Ver más en [Notificación](/gateway/notification)
                    example: https://your-site.com/your-notification-path
  /gateway/tokenize:
    post:
      summary: Tokenización (tokenize)
      operationId: post-gateway-tokenize
      description: |-
        Este servicio permite almacenar un instrumento de pago como: tarjetas de crédito o cuenta bancaria de manera segura, a través de una petición que contenga la información de la misma, se generará un token que puede ser usado en el servicio de procesamiento y para todos los efectos, en Placetopay equivale a una tarjeta de crédito o cuenta bancaria, la diferencia es que se envía la estructura token en vez de card o account.
        Previamente al consumo de este servicio se debe consultar el de información para saber si es necesario o no generar un OTP al cliente y en caso de ser necesario, solicitar el token a la persona y enviarlo en el consumo.
      tags:
        - Tokenización de tarjetas
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - instrument
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payer:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payer'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
                ipAddress:
                  type: string
                userAgent:
                  type: string
            examples:
              Tarjeta de crédito:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    card:
                      number: '5180300000000005'
                      expiration: 12/18
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
              Cuenta bancaria:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    account:
                      bankName: Test Bank
                      bankCode: '0001234'
                      accountType: SAV
                      accountNumber: '4111111111111111'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
              Con cobro:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    card:
                      number: '5180300000000005'
                      expiration: 12/18
                      cvv: '123'
                  payment:
                    reference: TEST_PAYMENT_12345
                    amount:
                      currency: COP
                      total: '100'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  instrument:
                    $ref: '#/components/schemas/Instrument'
                  additional:
                    type: object
                    description: Objeto que almacena información adicional de la respuesta de tokenización.
                    properties:
                      bin:
                        type: string
                        description: Primeros 6 dígitos del número de la tarjeta
              examples:
                Ok:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-06-17T11:29:37-05:00'
                    provider: CREDIBANCO
                    instrument:
                      token:
                        token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                        subtoken: fakesubtoken00005
                        franchise: master
                        franchiseName: Mastercard
                        lastDigits: '0005'
                        validUntil: '2018-12-31'
  /invalidate:
    post:
      summary: Tokenización (invalidate)
      operationId: post-gateway-tokenize
      description: Este servicio permite invalidar y eliminar un token asociado a una tarjeta de crédito.
      tags:
        - Tokenización de tarjetas
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  required:
                    - token
                  type: object
                  properties:
                    token:
                      type: object
                      required:
                        - token
                      properties:
                        token:
                          type: string
              required:
                - auth
                - instrument
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: /svw0VZ1UML5qEmaPbefQO7OXt098zOdfWsc/vHclGM=
                    nonce: NjQ0MWFlNGY0MWE1OQ==
                    seed: '2023-04-20T16:27:43-05:00'
                  instrument:
                    token:
                      token: 239bd2573205e974c4bed7c99cc1125c464f6350a905565333fff041d8f5ef79
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    title: Status
                    type: object
                    description: Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
                    properties:
                      status:
                        type: string
                        enum:
                          - OK
                          - FAILED
                          - APPROVED
                          - APPROVED_PARTIAL
                          - PARTIAL_EXPIRED
                          - REJECTED
                          - PENDING
                          - PENDING_VALIDATION
                          - PENDING_PROCESS
                          - PENDING_CONFIRMATION
                          - REFUNDED
                          - REVERSED
                          - ERROR
                          - UNKNOWN
                          - MANUAL
                          - DISPUTE
                      reason:
                        type: string
                        minLength: '1'
                        maxLength: '4'
                      message:
                        type: string
                      date:
                        type: string
                        example: '2021-09-21T09:34:48-05:00'
              examples:
                Ok:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-06-17T11:29:37-05:00'
  /gateway/transaction:
    post:
      summary: Operaciones sobre una transacción
      operationId: post-gateway-transaction
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema'
              examples:
                Ejemplo:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-20T21:56:29-05:00'
                    date: '2021-09-20T21:56:29-05:00'
                    transactionDate: '2021-09-20T21:56:29-05:00'
                    internalReference: 455
                    description: |
                      Usuario dueño de la cuenta a validar
                    reference: '1945768'
                    paymentMethod: CR_VS
                    franchise: visa
                    franchiseName: Visa
                    issuerName: Testing Bank
                    amount:
                      taxes:
                        - kind: valueAddedTax
                          amount: 705.66
                          base: '0'
                      currency: USD
                      total: 3714
                    conversion:
                      from:
                        currency: USD
                        total: 3714
                      to:
                        currency: USD
                        total: 3714
                      factor: 1
                    authorization: '000000'
                    receipt: '455'
                    type: CREDIT
                    refunded: 'false'
                    lastDigits: '0008'
                    provider: CREDIBANCO
                    discount: null
                    processorFields:
                      id: f4ec45ea4c83039384b189df2c1a6891
                      b24: '000'
                    additional:
                      merchantCode: null
                      terminalNumber: null
                      bin: '411076'
                      expiration: '1228'
                      installments: 1
        200 Confirm:
          description: Respuesta Aprobada de una confirmación
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    description: Fecha de la solicitud de operación
                    example: '2021-09-20T21:56:29-05:00'
                  transactionDate:
                    type: string
                    description: Fecha de ejecución de la operación.
                    example: '2021-09-20T21:56:29-05:00'
                  internalReference:
                    type: integer
                    description: Referencia interna de la operación.
                    nullable: true
                  type:
                    type: string
                    description: Tipo de transacción
                    enum:
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                  transactionProcessed:
                    type: object
                    description: Objeto que contiene la información de la transacción original procesada.
                    $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema'
      description: Permite realizar un reembolso, re-autorización, checkout, confirmación o cancelación sobre una transacción existente
      tags:
        - Acciones sobre transacciones
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  description: Contiene el código de localización
                  example: es-CO
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                action:
                  type: string
                  description: |
                    Tipo de operación a realizar sobre la transacción

                    `reverse` para revesar una transacción.

                    `reauthorization` para modificar una transacción de checkin.

                    `checkout` para cerrar y cobrar una transacción de checkin.

                    `refund` para rembolsar una transacción.

                    `process`, para aprobar de manera manual una transacción.

                    `void` para cancelar el procesamiento de una transacción pendiente de aprobación manual.

                    `confirm` para procesar una transacción pendiente de confirmación.

                    `cancel` para cancelar una transacción pendiente de confirmación.
                  enum:
                    - reverse
                    - refund
                    - process
                    - void
                    - dispersion
                    - checkout
                    - reauthorization
                    - confirm
                    - cancel
                  example: reverse
                internalReference:
                  type: number
                  description: |
                    Referencia interna única de la transacción

                    EJ: `543423`
                authorization:
                  type: string
                  description: |
                    Autorización de la transacción

                    EJ: `9999999`
                payment:
                  type: object
                  description: |
                    Estructura que contiene la información acerca del pago de la transacción
                  items:
                    type: object
                    properties:
                      amount:
                        type: object
                        properties:
                          currency:
                            type: number
                            description: |
                              Código alfabético de la moneda a usar (ISO 4217 alpha code)

                              EJ: `USD`
                          total:
                            type: number
                            description: |
                              Valor total en la moneda base indicada

                              EJ: `1000` Valor total en la moneda base indicada
                instrument:
                  type: object
                  description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
                  items:
                    type: object
                    properties:
                      credit:
                        description: Credito seleccionado para procesar. Disponible para action `confirm`
                        $ref: '#/components/schemas/CreditPerInstallment'
                metadata:
                  type: object
                  description: |
                    Objeto dinámico clave valor de información adicional que solicitan los servicios externos para ser ejecutados.
                  properties:
                    interestQueryCode:
                      type: string
                      description: Indica si la cuota cuenta con información disponible para ser aplicada durante el procesamiento de la transacción. Este campo es válido para el servicio **PAYSTUDIO**, *flavour* **TS**, y la información debe estar disponible a través del [servicio de consulta de intereses](/gateway/interests).Si se envía este valor, pero el código proporcionado no es válido o no es retornado por dicho servicio, la transacción será rechazada.
                      example: true
                ipAddress:
                  type: string
                  description: Dirección IP del cliente
                  example: 127.0.0.1
                userAgent:
                  type: string
                  description: Agente de usuario del cliente
                  example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
              required:
                - auth
                - action
                - internalReference
              x-conditional: credit
            examples:
              Reembolsos:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: MzgwYWYwMjc2ZWUzODA5YmI1MDQ1YmNjYzdlNzY1MTY=
                    seed: '2021-03-02T17:03:50+01:00'
                  internalReference: '1505723583'
                  authorization: '999999'
                  action: reverse
              Checkout:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0ZTNiZGEzZTNlNA==
                    seed: '2021-09-24T15:58:02-05:00'
                  internalReference: '62342'
                  authorization: '580883'
                  action: checkout
                  payment:
                    amount:
                      total: '2000'
  /gateway/query:
    post:
      summary: Consulta de transacción por referencia interna
      operationId: post-rest-gateway-query
      description: Permite consultar una transacción en particular usando su referencia interna
      tags:
        - Consulta de una transacción
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                internalReference:
                  type: number
              required:
                - auth
                - internalReference
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: MzgwYWYwMjc2ZWUzODA5YmI1MDQ1YmNjYzdlNzY1MTY=
                    seed: '2021-03-02T17:03:50+01:00'
                  internalReference: '230364'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: Datos de la transacción
                type: object
                title: ''
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    format: date-time
                    description: 'Fecha de creación (ISO 8601 con zona). Ej: `2021-09-20T21:51:59-05:00`.'
                  transactionDate:
                    type: string
                    format: date-time
                    description: Fecha de procesamiento en el proveedor (puede diferir de date).
                  internalReference:
                    type: number
                    description: Referencia interna.
                    minimum: 1
                  reference:
                    type: string
                    description: Referencia del comercio.
                    minLength: 1
                    maxLength: 64
                  paymentMethod:
                    type: string
                    description: 'Formato convencional: procesador_franquicia (ej: `ID_VS` para Interdin Visa, `DF_MS` para Datafast Mastercard), pueden existir excepciones.'
                    minLength: 5
                    maxLength: 5
                  franchise:
                    type: string
                    description: Franquicia / marca.
                    enum:
                      - visa
                      - visa_electron
                      - amex
                      - master
                      - codensa
                      - diners
                      - jbc
                      - discover
                      - ris
                      - credencial
                      - comfama
                      - colsubsidio
                      - falabella
                      - elo
                      - somos
                      - tuya
                      - exito
                      - alkosto
                      - maestro
                      - mefia
                      - ath_card
                      - ath
                      - athmv
                      - bancolombia
                      - cooperativa
                      - debito
                      - pagoefectivo
                      - cafam
                      - efecty
                      - gana
                      - masterpass
                      - ppd
                      - pse
                      - safetypay
                      - supergiros
                      - visa_checkout
                      - procesa
                      - comfandi
                      - ach
                      - telered
                      - aval
                      - dilo
                      - banco_bogota
                      - ebt
                      - alia
                      - deuna
                  franchiseName:
                    type: string
                    description: Nombre mostrado de la franquicia.
                    minLength: 1
                  issuerName:
                    type: string
                    description: Nombre del emisor.
                    minLength: 1
                    nullable: true
                  amount:
                    $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                  conversion:
                    $ref: '#/paths/~1gateway~1process/post/responses/200/content/application~1json/schema/properties/conversion'
                  authorization:
                    type: string
                    description: Código de autorización.
                    minLength: 1
                    nullable: true
                  receipt:
                    type: string
                    description: Recibo / comprobante.
                    maxLength: 16
                    nullable: true
                  type:
                    type: string
                    description: Tipo de operación.
                    minLength: 1
                    enum:
                      - AUTH_ONLY
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                      - AUTH_CAPTURE
                      - CAPTURE_ONLY
                      - CREDIT
                      - SETTLE
                      - VOID
                      - CHARGEBACK
                      - DISPUTE
                      - DISPUTE_LOSS
                      - DISPUTE_WIN
                      - DISPERSION
                      - REFUND
                      - PRE_AUTH
                      - CHECKIN
                      - CHECKOUT
                      - RE_AUTH
                      - DISPERSION_CAPTURE
                      - DISPERSION_SETTLE
                      - DISPERSION_CREDIT
                  refunded:
                    type: boolean
                    description: Indicador reembolsada.
                    example: false
                  lastDigits:
                    type: string
                    description: Últimos dígitos de cuenta.
                    minLength: 2
                    nullable: true
                  provider:
                    type: string
                    description: Código del procesador/proveedor.
                    enum:
                      - CREDIBANCO
                      - REDEBAN
                      - INTERDIN
                      - DATAFAST
                      - TUYA-DIRECT
                      - BRASPAG
                      - TRANSERVER
                      - SABRE
                      - EVERTEC
                      - ACH
                      - ATH-AVALNET
                      - SUPERGIROS
                      - TECNICARD
                      - MEDIANET
                      - AUSTRO
                      - COMFANDI
                      - PAYSTUDIO
                      - FLAMINGO
                      - ATH-MOVIL
                      - EBUS
                      - BANCOLOMBIA
                      - PAGOEFECTIVO
                      - PROCESA
                      - TELERED
                      - AVAL
                      - DILO
                      - BANCO_BOGOTA
                      - BANET
                      - DEUNA
                  discount:
                    type: string
                    description: Información de descuento aplicada (si existe).
                  processorFields:
                    type: object
                    description: Campos crudos del procesador.
                    properties:
                      id:
                        type: string
                        description: Id procesador.
                        maxLength: 64
                      b24:
                        type: string
                        description: Campo extra.
                        maxLength: 64
                  additional:
                    type: object
                    description: |
                      Ver más en [Datos adicionales](/gateway/additional-data)
                  preAuthorization:
                    type: object
                    description: Segmentos de preautorización.
                    items:
                      type: object
                      properties:
                        condition:
                          type: string
                          description: Condición.
                        internalReference:
                          type: number
                          description: Ref. segmento.
                        authorization:
                          type: string
                          description: Auth segmento.
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          description: Recibo segmento.
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                        salt:
                          type: string
                          description: Salt segmento.
                  dispersion:
                    type: array
                    description: Lista de dispersiones.
                    items:
                      type: object
                      properties:
                        status:
                          $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                        agreement:
                          type: integer
                          description: Id acuerdo.
                          nullable: true
                        agreementType:
                          type: string
                          description: Tipo acuerdo.
                          enum:
                            - AIRLINE
                            - MERCHANT
                        authorization:
                          type: string
                          description: Auth. dispersión.
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          description: Recibo dispersión.
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                        refunded:
                          type: boolean
                          description: Dispersión reembolsada.
                          example: false
                        paymentMethod:
                          type: string
                          description: Código del método de pago.
                required:
                  - status
                  - provider
                  - internalReference
                  - reference
                  - paymentMethod
                  - franchise
                  - franchiseName
                  - amount
                  - authorization
                  - receipt
                  - type
                  - refunded
                  - processorFields
              examples:
                Ejemplo:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-24T14:04:23-05:00'
                    date: '2021-09-24T10:02:17-05:00'
                    transactionDate: '2021-09-24T10:02:18-05:00'
                    internalReference: '230364'
                    reference: '800166551'
                    paymentMethod: ID_DN
                    franchise: diners
                    franchiseName: Diners
                    issuerName: Diners
                    amount:
                      taxes:
                        - kind: valueAddedTax
                          amount: 0
                          base: 0
                      currency: USD
                      total: 120
                    conversion:
                      from:
                        currency: USD
                        total: 120
                      to:
                        currency: USD
                        total: 120
                      factor: 1
                    authorization: '999999'
                    receipt: '230364'
                    type: AUTH_ONLY
                    refunded: 'false'
                    lastDigits: '0008'
                    provider: INTERDIN
                    discount: null
                    processorFields:
                      id: cf3e77878a07d6e3ee667c60081dc39d
                      b24: '00'
                    additional:
                      merchantCode: '1065152'
                      terminalNumber: '00990099'
                      credit:
                        code: '1'
                        type: '03'
                        groupCode: X
                        installments: 3
                      totalAmount: 120
                      interestAmount: 0
                      installmentAmount: 40
                      iceAmount: 0
                      batch: null
                      line: null
                      bin: '365454'
                      expiration: '1122'
                    notificationURL: https://test.placetopay.ec/redirection/api/notify
        200 Confirm:
          description: Respuesta de una Transacción de Confirmación
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    description: Fecha de la solicitud de operación
                    example: '2021-09-20T21:56:29-05:00'
                  transactionDate:
                    type: string
                    description: Fecha de ejecución de la operación.
                    example: '2021-09-20T21:56:29-05:00'
                  internalReference:
                    type: integer
                    description: Referencia interna de la operación.
                    nullable: true
                  type:
                    type: string
                    description: Tipo de transacción
                    enum:
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                  transactionProcessed:
                    type: object
                    description: Objeto que contiene la información de la transacción original procesada.
                    $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema'
  /gateway/search:
    post:
      summary: Búsqueda de transacciones
      operationId: post-gateway-search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  transactions:
                    type: array
                    uniqueItems: 'true'
                    minItems: '1'
                    items:
                      $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema'
                required:
                  - status
                  - transactions
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-09-20T21:51:59-05:00'
                    transactions:
                      - status:
                          status: PENDING
                          reason: '?-'
                          message: Transacción pendiente
                          date: '2021-09-20T21:51:59-05:00'
                        date: '2021-09-20T21:51:59-05:00'
                        transactionDate: '2021-09-20T21:51:59-05:00'
                        internalReference: 453
                        reference: TEST_3
                        paymentMethod: ID_VS
                        franchise: visa
                        franchiseName: Visa
                        issuerName: Testing Bank
                        amount:
                          taxes:
                            - kind: valueAddedTax
                              amount: 3.27
                              base: 0
                          currency: USD
                          total: 17.2
                        conversion:
                          from:
                            currency: USD
                            total: 17.2
                          to:
                            currency: USD
                            total: 17.2
                          factor: 1
                        authorization: null
                        receipt: null
                        type: AUTH_ONLY
                        refunded: 'false'
                        lastDigits: '0008'
                        provider: INTERDIN
                        discount: null
                        processorFields:
                          id: a9cb4b7a7aa03f681a0545ba6807e1fc
                          b24: '?-'
                        additional:
                          merchantCode: '000468232'
                          terminalNumber: '00990101'
                          credit: null
                          totalAmount: 17.2
                          interestAmount: 0
                          installmentAmount: 0
                          iceAmount: 0
                          batch: null
                          line: null
                          bin: '411076'
                          expiration: '1228'
                      - status:
                          status: PENDING
                          reason: '?-'
                          message: Transacción pendiente
                          date: '2021-09-20T21:51:59-05:00'
                        date: '2021-09-20T21:51:59-05:00'
                        transactionDate: '2021-09-20T21:51:59-05:00'
                        internalReference: 452
                        reference: TEST_3
                        paymentMethod: ID_VS
                        franchise: visa
                        franchiseName: Visa
                        issuerName: Testing Bank
                        amount:
                          taxes:
                            - kind: valueAddedTax
                              amount: 3.27
                              base: 0
                          details:
                            - kind: shipping
                              amount: 100
                          currency: USD
                          total: 17.2
                        conversion:
                          from:
                            currency: USD
                            total: 17.2
                          to:
                            currency: USD
                            total: 17.2
                          factor: 1
                        authorization: null
                        receipt: null
                        type: AUTH_ONLY
                        refunded: 'false'
                        lastDigits: '0008'
                        provider: INTERDIN
                        discount: null
                        processorFields:
                          id: cbc65da9667ca078dc774cad2fd510e4
                          b24: '?-'
                        additional:
                          merchantCode: '000468232'
                          terminalNumber: '00990101'
                          credit: null
                          totalAmount: 17.2
                          interestAmount: 0
                          installmentAmount: 0
                          iceAmount: 0
                          batch: null
                          line: null
                          bin: '411076'
                          expiration: '1228'
      tags:
        - Consulta de una transacción
      description: Este servicio permite la búsqueda de transacciones por referencia y monto, suele utilizarse en caso de pérdida de comunicación al crear una transacción para obtener la referencia interna nuevamente.
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                reference:
                  type: string
                  minLength: 1
                amount:
                  title: Amount
                  type: object
                  description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                  required:
                    - currency
                    - total
                  properties:
                    currency:
                      type: string
                      description: |
                        Código alfabético de la moneda a usar (ISO 4217 alpha code)
                      enum:
                        - USD
                        - COP
                        - CRC
                        - EUR
                        - CAD
                        - AUD
                        - GBP
                        - MXN
                        - CLP
                      example: COP
                      minLength: 3
                      maxLength: 3
                    total:
                      type: number
                      example: 2000
                      description: |
                        Valor total en la moneda base indicada
                    taxes:
                      type: array
                      description: |
                        Estructura para definir impuestos en el proceso de pago.
                      items:
                        $ref: '#/paths/~1gateway~1information/post/requestBody/content/application~1json/schema/oneOf/5/properties/payment/properties/amount/properties/taxes/items'
                    details:
                      type: array
                      description: |
                        Estructura para definir detalles adicionales del monto en el proceso de pago.
                      items:
                        $ref: '#/paths/~1gateway~1information/post/requestBody/content/application~1json/schema/oneOf/5/properties/payment/properties/amount/properties/details/items'
              required:
                - auth
                - reference
                - amount
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: +FSGHsW3e6WrrHcIdBmqI+j6FFeUN4bidfPL7LeZgvE=
                    nonce: N2YzMGM1M2QxOTU3YzZmMzVlYmIzZTAyOGMwNjNkMmU=
                    seed: '2021-03-03T19:40:37+01:00'
                  reference: TEST_20171108_144400
                  amount:
                    currency: COP
                    total: 1000
  /gateway/interests:
    post:
      summary: Cálculo de Intereses
      operationId: post-rest-gateway-interests
      description: Este servicio se debe consumir si la tarjeta requiere que se muestren los intereses (`displayInterest` en `true`) o sus condiciones de crédito lo permiten (Ver condición en [Créditos por proveedor](/gateway/additional-data/#additional-data-credit-providers)). Está disponible para los flujos que exponen cálculo de intereses, incluidos Ecuador y Chile con PAYSTUDIO flavour `TS`.
      tags:
        - Obtener información
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  values:
                    $ref: '#/components/schemas/InterestValues'
                  conversion:
                    $ref: '#/paths/~1gateway~1process/post/responses/200/content/application~1json/schema/properties/conversion'
                  additional:
                    type: object
                    description: Información adicional del interest
                    properties:
                      interestQueryCode:
                        type: string
                        description: Indica si la cuota contiene información adicional que debe considerarse durante el procesamiento de la transacción. Aplica únicamente para **Paystudio TS**. Cuando este campo sea retornado, el valor de `metadata.interestQueryCode` también deberá enviarse explícitamente en la solicitud de procesamiento para que se aplique la información obtenida en la consulta de cuotas.
                        nullable: true
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-09-22T16:08:19-05:00'
                    provider: PAYSTUDIO
                    values:
                      original: 50000
                      installment: 25000
                      interest: 0
                      total: 50000
                    conversion: null
    parameters: null
  /gateway/otp/generate:
    post:
      summary: Generación de OTP (solo Ecuador)
      operationId: post-rest-otp-generate
      description: Este servicio se consume si es necesario el otp para la tarjeta provista por el cliente (requireOtp en true) y debe permitirsele al usuario ingresar el OTP para enviarlo posteriormente en el servicio de procesamiento, a manera de ejemplo de esta manera se captura en la interfaz de redirección
      tags:
        - Proceso OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: q/7k0WUshvLEpQ5gqNWqne+ZfWXSXUP/b7T80TuAUSY=
                    nonce: NjE0YTM3OGIwNjA2NA==
                    seed: '2021-09-21T14:50:35-05:00'
                  payer:
                    name: John
                    email: user_email@example.com
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: USD
                      total: 3
                  instrument:
                    card:
                      number: '36545400000008'
                      expiration: 12/20
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-09-21T14:52:28-05:00'
                    provider: INTERDIN
                No Requerido:
                  value:
                    status:
                      status: REJECTED
                      reason: NR
                      message: OTP is not required with this card
                      date: '2021-09-21T14:53:21-05:00'
                    provider: INTERDIN
  /gateway/otp/validate:
    post:
      summary: Validación de OTP (solo Ecuador)
      operationId: post-rest-otp-validate
      description: Permite validar que el OTP provisto concuerde con el enviado por el proveedor y proporcionará una firma que sirve para autenticar la transacción > Nota Importante > > Es necesario enviar el valor retornado como `signature` en la respuesta como `instrument.otp` en la petición de procesamiento para que se registre en la transacción
      tags:
        - Proceso OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: q/7k0WUshvLEpQ5gqNWqne+ZfWXSXUP/b7T80TuAUSY=
                    nonce: NjE0YTM3OGIwNjA2NA==
                    seed: '2021-09-21T14:50:35-05:00'
                  payer:
                    name: John
                    email: user_email@example.com
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: USD
                      total: 3
                  instrument:
                    card:
                      number: '36545400000008'
                      expiration: 12/20
                      cvv: '123'
                    otp: '123456'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  signature:
                    type: string
                    nullable: 'true'
                  validated:
                    type: boolean
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: OTP Validation successful
                      date: '2021-09-21T15:12:01-05:00'
                    provider: INTERDIN
                    signature: a586077cd77ec2dbcb9b7f68b896368a
                    validated: 'true'
                Errado:
                  value:
                    status:
                      status: FAILED
                      reason: OT1
                      message: El OTP ingresado no coincide con el que se te ha provisto
                      date: '2021-09-21T15:14:41-05:00'
                    provider: INTERDIN
                    signature: null
                    validated: 'false'
  /gateway/report:
    post:
      summary: Solicitar un reporte
      operationId: post-report
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  id:
                    type: number
                required:
                  - status
                  - id
              examples:
                example:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La solicitud se ha procesado exitosamente
                      date: '2020-01-18T18:00:00-05:00'
                    id: '1231'
                error:
                  value:
                    status:
                      status: FAILED
                      reason: BR
                      message: El reporte solicitado supera los 10 días
                      date: '2020-01-18T18:00:00-05:00'
                    id: '0'
      description: Permite solicitar que se genere un reporte de transacciones y retorna un identificador para el proceso, el cúal una vez sea llamado el callback puede ser obtenido en el endpoint siguiente
      tags:
        - Reporte de operaciones realizadas
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                filters:
                  type: object
                  required:
                    - startDate
                    - endDate
                    - processStartDate
                    - processEndDate
                  properties:
                    startDate:
                      type: string
                      format: date-time
                      example: '2021-01-10T18:01:27-05:00'
                      description: Este campo es obligatorio cuando no se envía processStartDate
                    endDate:
                      type: string
                      format: date-time
                      example: '2021-01-12T18:01:27-05:00'
                    processStartDate:
                      type: string
                      format: date-time
                      example: '2021-01-10T18:01:27-05:00'
                      description: |-
                        Este campo es obligatorio cuando no se envía startDate.

                        Permite filtrar por la fecha de procesamiento de la transacción
                    processEndDate:
                      type: string
                      format: date-time
                      example: '2021-01-12T18:01:27-05:00'
                    state:
                      type: array
                      description: 'Permite definir el estado de las transacciones, es un arreglo: APPROVED, REJECTED, FAILED y PENDING'
                      items:
                        type: string
                        example: '[''APPROVED'', ''REJECTED'']'
                        enum:
                          - APPROVED
                          - REJECTED
                          - PENDING
                          - FAILED
                    type:
                      type: array
                      description: 'Permite definir el tipo de las transacciones, es un arreglo: AUTH_ONLY, CAPTURE_ONLY, CREDIT, REFUND, SETTLE, AUTH_CAPTURE, VOID, DISPUTE, CHARGEBACK, DISPUTE_LOSS, DISPUTE_WIN, PRE_AUTH, CHECKIN, CHECKOUT, RE_AUTH'
                      items:
                        type: string
                        example: '[''AUTH_ONLY'', ''CHARGEBACK'']'
                        enum:
                          - AUTH_ONLY
                          - CAPTURE_ONLY
                          - CREDIT
                          - REFUND
                          - SETTLE
                          - AUTH_CAPTURE
                          - VOID
                          - DISPUTE
                          - CHARGEBACK
                          - DISPUTE_LOSS
                          - DISPUTE_WIN
                          - PRE_AUTH
                          - CHECKIN
                          - CHECKOUT
                          - RE_AUTH
                callbackUrl:
                  type: string
                  format: uri
              required:
                - auth
                - filters
            examples:
              Básico:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: cV5MJlkUgPq/BLG40M1Cp2mSkJcZg7FPL4FBxKo+t5A=
                    nonce: NjQ4MjMzMjY0MDIyYw==
                    seed: '2023-06-08T14:59:34-05:00'
                  filters:
                    startDate: '2023-06-07 14:59:34'
                    endDate: '2023-06-08 14:59:34'
                  callbackUrl: https://dnetix.co/ping/report
              Con estado:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: cV5MJlkUgPq/BLG40M1Cp2mSkJcZg7FPL4FBxKo+t5A=
                    nonce: NjQ4MjMzMjY0MDIyYw==
                    seed: '2023-06-08T14:59:34-05:00'
                  filters:
                    startDate: '2023-06-07 14:59:34'
                    endDate: '2023-06-08 14:59:34'
                    state:
                      - APPROVED
                      - REJECTED
                  callbackUrl: https://dnetix.co/ping/report
  /gateway/report/obtain:
    post:
      summary: Obtener un reporte previamente solicitado
      operationId: post-report-obtain
      responses:
        '200':
          description: |-
            OK
            Una vez se tiene el reporte retorna la información, el cúal es un archivo separado por tabs con los siguientes encabezados
            La columna de type es agragada cuando el reporte usa el filtro de type

            ``` id date transaction_date reference currency_code amount tax payment_method internal_reference status reason merchant terminal authorization refunded installments last_digits bank_currency bank_factor bank_amount issuer_name payer_document payer_first_name payer_last_name payer_email ip_address batch_number line_number type ```
          content:
            text/plain:
              schema:
                type: string
              examples:
                example:
                  value: "id\tdate transaction_date\t\treference\tcurrency_code\t\tamount tax payment_method\tinternal_reference\t status\t\treason merchant\t\tterminal\t authorization refunded\t\tinstallments\t last_digits\t bank_currency bank_factor bank_amount issuer_name payer_document\tpayer_first_name payer_last_name payer_email ip_address\tbatch_number line_number\t type c42977b5d4ff9d9613320c7ee98e9eb0\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t4113943\t\tUSD\t\t2327\t 442.13\t\tID_VS\t221\t\t\t APPROVED\t 000468232\t00990101\t\t\t\t1 0008\t\tUSD\t\t1\t2327 Testing Bank\t\t32694548\t Miss Joanne Fadel MD\tPrice\t\tuser@example.com 237.234.250.30\tAUTH_ONLY 315c9ca9e64bed46f24a2e18bdd76468\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t8122\t USD\t 4457\t846.83\t ID_VS 222 \t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 4457\t\tTesting Bank\t 44056172\tCharlotte Maggio Steuber user@example.com\t 164.233.22.247\tAUTH_ONLY fd239e99125c326e92137197fd5d1959\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t753446151\tUSD\t3798 721.62\tID_VS\t\t223\t\t\t\t APPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t3798\t Testing Bank\t51751981 Mr. Abdiel Schroeder DDS\t\tMcKenzie\t leonard.beier@runte.com\t 250.136.231.200\t\tAUTH_ONLY be945b27ff13291409b929cc9cb15274\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t482657 USD 1401\t\t266.19 ID_VS\t 224\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 1401\tTesting Bank 98958097\t\tDr. Mia Abshire\t\tDouglas\t\tantonia.blanda@wyman.com\t 32.1.213.30 \tAUTH_ONLY 3aaa74df49cf3634276675c95e49f2af\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t77616851\t USD\t 1921\t364.99\t ID_VS 225 \t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 1921\t\tTesting Bank\t 6211299\t Dr. Marcelina Huel I\tConsidine\t\tvlangworth@emard.biz\t 249.218.136.4\tAUTH_ONLY 6e89e692975bb117db78360c8ebf0a00\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t74141\tUSD\t773\t146.87\t ID_VS 226 \t\t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 773 Testing Bank\t\t22736252\t Melody Goodwin DDS\t\tGerlach\t\tiblock@ohara.com\t 168.87.8.132\tAUTH_ONLY b50e4e8cca851a578fa40917030397a3\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t828\t\tUSD\t\t473\t\t89.87\tID_VS\t\t227\t\t\t\t\tAPPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t473\t\tTesting Bank\t 9397147\t Freeman Kirlin\t\tAufderhar\tdrobel@kshlerin.com\t21.185.38.170\t\tAUTH_ONLY b66ffe1bff91a15986cba677bbaeaa7f\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t581122 USD 1767\t\t335.73 ID_VS\t 228\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 1767\tTesting Bank 62818359\t\tMrs. Rosina Mann\t Schaefer\tuser@example.com\t15.8.188.238 \tAUTH_ONLY 135afcb2f872cf55168461e7e874242a\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t3896507\t\tUSD\t\t7\t1.33 ID_VS\t 229\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 7 Testing Bank\t\t10597030\t Kristy Purdy IV\t Mills user@example.com 148.232.85.97 \tAUTH_ONLY 19868ea1110eca766186806ef0e38f71\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t68490\tUSD\t4987 947.53\tID_VS\t\t230\t\t\t\t APPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t4987\t Testing Bank\t32385057 Mr. Harley Howe Rogahn\tuser@example.com 87.121.113.190\t\tAUTH_ONLY\t "
        '425':
          description: Cuando la petición se realiza antes de que se termine de generar el reporte
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                id:
                  type: number
              required:
                - auth
                - id
        description: ''
      description: Permite obtener un reporte previamente generado
      tags:
        - Reporte de operaciones realizadas
      parameters:
        - schema:
            type: string
            enum:
              - gzip
          in: header
          name: accept-encoding
          description: Permite proporcionar gzip como formato de compresión.
  /gateway/mpi/lookup:
    post:
      summary: 3DS Lookup
      operationId: post-mpi-lookup
      description: Realiza el proceso inicial de validación de 3DS retornando los datos para que el usuario pueda continuar con el proceso
      tags:
        - Proceso 3DS
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                userAgent:
                  type: string
                  description: Información del agente de usuario
                  example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36
                buyer:
                  $ref: '#/components/schemas/Buyer'
                payer:
                  $ref: '#/components/schemas/Payer'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
                version:
                  type: string
                  nullable: true
                  description: Versión de 3DS en la que se procesara la petición.
                  enum:
                    - v2
                    - v2x
                returnUrl:
                  type: string
                  format: uri
                  maxLength: 250
                  description: Url de retorno para retomar el control del usuario
                additional:
                  type: object
                  properties:
                    initiatorIndicator:
                      type: string
                      description: Actor que genera la transacción. Puede ser AGENT cuando es diferente al tarjeta habiente
                      nullable: true
                      enum:
                        - AGENT
                metadata:
                  type: object
                  properties:
                    merchantRiskIndicator:
                      type: object
                      description: Objeto que contiene información relacionada con la evaluación del comerciante respecto al nivel de riesgo de fraude en una autenticación específica. La inclusión de estos datos adicionales en la solicitud permite realizar una evaluación más precisa, lo que puede mejorar considerablemente la tasa de autenticaciones exitosas.
                      properties:
                        deliveryEmailAddress:
                          type: string
                          maxLength: 254
                          description: Para entrega electrónica, la dirección de correo electrónico a la que se entregó la mercancía.
                          nullable: true
                        deliveryTimeframe:
                          type: string
                          enum:
                            - ELECTRONIC_DELIVERY
                            - SAME_DAY_SHIPPING
                            - OVERNIGHT_SHIPPING
                            - TWO_DAYS_OR_MORE_SHIPPING
                          description: Indica el plazo de entrega de la mercancía.
                          nullable: true
                          example: ELECTRONIC_DELIVERY
                        giftCardAmount:
                          type: string
                          maxLength: 15
                          description: Para compras con tarjeta de regalo o prepago, es el monto total de la compra de tarjetas de regalo o prepago en unidades principales (por ejemplo, 123,45 USD es 123).
                          nullable: true
                          example: '123'
                        giftCardCount:
                          type: string
                          maxLength: 2
                          description: Para compras con tarjeta de regalo o prepago, recuento total de tarjetas, códigos de regalo o prepago individuales comprados.
                          nullable: true
                          example: '10'
                        giftCardCurrency:
                          type: string
                          maxLength: 3
                          description: Para compras con tarjeta de regalo o prepago, código de moneda de tres dígitos ISO 4217 de la tarjeta de regalo.
                          nullable: true
                          example: '021'
                        preOrderDate:
                          type: string
                          format: YYYY-MM-DD
                          description: Para una compra pre-ordenada, la fecha esperada en que la mercancía estará disponible.
                          nullable: true
                          example: '2025-10-08'
                        preOrderPurchaseIndicator:
                          type: string
                          enum:
                            - MERCHANDISE_AVAILABLE
                            - FUTURE_AVAILABILITY
                          description: Indica si el Titular de la tarjeta está realizando un pedido de mercancía con una disponibilidad futura o una fecha de lanzamiento.
                          nullable: true
                          example: FUTURE_AVAILABILITY
                        reOrderItemsIndicator:
                          type: string
                          enum:
                            - REORDERED
                            - FIRST_TIME_ORDERED
                          description: Indica si el Titular de la tarjeta está reordenando mercancía comprada anteriormente.
                          nullable: true
                          example: REORDERED
                        shipIndicator:
                          type: string
                          enum:
                            - SHIP_TO_CARDHOLDER_BILLING_ADDR
                            - SHIP_TO_ANOTHER_VERIFIED_ADDR_ON_FILE
                            - SHIP_TO_ADDR_DIFF_CARDHOLDER_BILLING_ADDR
                            - SHIP_TO_STORE
                            - DIGITAL_GOODS
                            - TRAVEL_EVENT_TICKETS_NOT_SHIPPED
                            - OTHER
                          description: Indica el método de envío elegido para la transacción.
                          nullable: true
                          example: SHIP_TO_STORE
                    cardholderAccountInformation:
                      type: object
                      description: Objeto que contiene información adicional sobre la cuenta del titular de la tarjeta.  Estos datos adicionales permiten realizar una evaluación más precisa, lo que puede mejorar considerablemente la tasa de autenticaciones exitosas.
                      properties:
                        cardholderAccountAgeIndicator:
                          type: string
                          description: Longitud del tiempo en que la cuenta fue creada en el sitio web del comercio.
                          enum:
                            - NO_ACCOUNT
                            - CREATED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          nullable: true
                          example: LESS_30_DAYS
                        cardholderAccountChangeDate:
                          type: string
                          format: YYYY-MM-DD
                          description: Fecha del último cambio efectuado en la cuenta del tarjetahabiente en el sitio web del comercio.
                          nullable: true
                          example: '2025-12-29'
                        cardholderAccountChangeIndicator:
                          type: string
                          enum:
                            - CHANGED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Longitud del tiempo desde el último cambio efectuado en la cuenta en el sitio web del comercio.
                          nullable: true
                          example: MORE_60_DAYS
                        cardholderAccountDate:
                          type: string
                          format: YYYY-MM-DD
                          description: Fecha en la que se realizó el último cambio o recuperación de contraseña de la cuenta en el sitio web del comercio.
                          nullable: true
                          example: '2025-08-01'
                        cardholderAccountPasswordChangeIndicator:
                          type: string
                          enum:
                            - NO_CHANGE
                            - CHANGED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Longitud de tiempo desde el último cambio o recuperación de contraseña de la cuenta.
                          nullable: true
                          example: MORE_60_DAYS
                        cardholderPurchaseCount:
                          type: string
                          maxLength: 4
                          description: Número de compras durante los últimos 6 meses.
                          nullable: true
                          example: '1234'
                        addCardAttemptsDay:
                          type: string
                          description: Número de intentos de agregar tarjetas en las últimas 24 horas.
                          maxLength: 3
                          nullable: true
                          example: '05'
                        trxActivityDay:
                          description: Número de transacciones (exitosas y abandonadas) para la cuenta en las últimas 24 horas.
                          type: string
                          maxLength: 3
                          nullable: true
                          example: '05'
                        trxActivityYear:
                          description: Número de transacciones (exitosas y abandonadas) para la cuenta en el último año.
                          type: string
                          maxLength: 3
                          nullable: true
                          example: '123'
                        paymentAccountAge:
                          type: string
                          format: YYYY-MM-DD
                          description: Fecha en la que el método de pago se agregó a la cuenta del usuario en el sitio web del comercio.
                          nullable: true
                          example: '2025-04-04'
                        paymentAccountIndicator:
                          type: string
                          enum:
                            - NO_ACCOUNT
                            - CREATED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Longitud de tiempo desde que el método de pago fue enrolado en la cuenta en el sitio web del comercio.
                          nullable: true
                          example: MORE_60_DAYS
                        shipAddressUsage:
                          type: string
                          format: YYYY-MM-DD
                          description: Fecha en la que la dirección de entrega fue usada por primera vez en el sitio web del comercio.
                          nullable: true
                          example: '2025-04-04'
                        shipNameIndicator:
                          type: string
                          enum:
                            - ACCOUNT_NAME_IDENTICAL_SHIPPING_NAME
                            - ACCOUNT_NAME_DIFFERENT_SHIPPING_NAME
                          description: Indica si el nombre del titular de la tarjeta es igual al nombre de envío usado en esta transacción.
                          nullable: true
                          example: ACCOUNT_NAME_DIFFERENT_SHIPPING_NAME
                        suspiciousAccountActivity:
                          type: string
                          enum:
                            - NO_SUSPICIOUS_ACTIVITY_OBSERVED
                            - SUSPICIOUS_ACTIVITY_OBSERVED
                          description: Indica si el comercio ha experimentado actividad sospechosa (incluido fraude previo) en la cuenta del titular de la tarjeta.
                          nullable: true
                          example: NO_SUSPICIOUS_ACTIVITY_OBSERVED
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/LookupResponseDataV2X'
                      - $ref: '#/components/schemas/LookupResponseDataV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
  /gateway/mpi/query:
    post:
      summary: 3DS Query
      operationId: post-mpi-query
      tags:
        - Proceso 3DS
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                id:
                  type: string
                  description: Identificador retornado en el lookup inicial sobre el cual se va a consultar
              required:
                - auth
                - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    $ref: '#/components/schemas/Instrument/properties/threeDS'
                required:
                  - status
                  - data
  /gateway/balance:
    post:
      summary: Servicio de consulta de balance
      operationId: post-rest-gateway-balance
      description: Este servicio permite la consulta de balance, debe consumirse cuando el medio de pago lo requiera ('requireBalance' en true).
      tags:
        - Obtener información
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/BalanceInstrument'
                payment:
                  $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
            examples:
              Consumo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: E0gHh8C6fceHnbsLlgBq2n7nRNjr8MVPcz0um1ZYCfs=
                    nonce: NjE0YjUwZGNlYjJiNA==
                    seed: '2021-09-22T10:50:52-05:00'
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: CRC
                      total: '1000'
                  instrument:
                    card:
                      number: '4111111111111111'
                      expiration: 12/30
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  total:
                    type: number
                    example: '4973.19'
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-09-22T16:08:19-05:00'
                    total: 42356.32
        '400':
          description: FAILED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
              examples:
                Ejemplo:
                  value:
                    status:
                      status: FAILED
                      reason: BR
                      message: El campo instrument.card.expiration es obligatorio.
                      date: '2024-11-01T07:12:57-05:00'
  /security/pinpad/transaction:
    post:
      summary: Solicitud de Pinpad
      operationId: post-rest-security-transaction
      description: |-
        Un PINPAD es un dispositivo electrónico que se utiliza en una transacción de débito, crédito o tarjeta inteligente para aceptar y cifrar el número de identificación personal (PIN) del titular de la tarjeta.
        Esta API proporciona un servicio PinPad con generación de PinBlock cifrada según ISO 9564.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              Solicitud por tarjeta:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    card:
                      number: '4111111111111111'
              Solicitud por token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    properties:
                      pinPad:
                        $ref: '#/components/schemas/PinPad'
              examples:
                Respuesta exitosa:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-14T17:43:48-05:00'
                    data:
                      pinPad:
                        positions: '7915864032'
                        transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                        pinLength: '4'
                Error:
                  value:
                    status:
                      status: FAILED
                      reason: '0'
                      message: ''
                      date: '2021-09-22T16:53:48-05:00'
                Rechazo:
                  value:
                    status:
                      status: REJECTED
                      reason: '05'
                      message: El servicio requerido no se encuentra disponible en el sitio
                      date: '2021-09-27T09:35:03-05:00'
                Servicio no disponible:
                  value:
                    status:
                      status: REJECTED
                      reason: SU
                      message: El servicio requerido no se encuentra disponible en el sitio
                      date: '2021-09-27T09:35:03-05:00'
      tags:
        - Operaciones con Pinpad
    parameters: null
  /security/pinpad/pinblock:
    post:
      summary: Generación de PinBlock a partir de PinPad
      operationId: post-rest-security-pinblock
      description: Permite generar el pinblock con una transaccion en base a las posiciones entregadas por el usuario que se seleccionaron del PinPad
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              Solicitud de PinBlock por tarjeta:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    card:
                      number: '0215020177972730'
                    pinPad:
                      transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                      positions: '0123'
              Solicitud de Pinblock por token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                    pinPad:
                      transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                      positions: '0123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    properties:
                      pinPad:
                        $ref: '#/components/schemas/PinPad'
              examples:
                Generación exitosa:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-14T17:43:48-05:00'
                    data:
                      pinPad:
                        positions: '0123'
                        transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                        pinBlock: 106C56A4819B68EA
                        pinLength: '4'
                Error:
                  value:
                    status:
                      status: FAILED
                      reason: '0'
                      message: ''
                      date: '2021-09-22T16:53:48-05:00'
                Rechazo:
                  value:
                    status:
                      status: REJECTED
                      reason: '05'
                      message: El servicio requerido no se encuentra disponible en el sitio
                      date: '2021-09-27T09:35:03-05:00'
                Servicio no disponible:
                  value:
                    status:
                      status: REJECTED
                      reason: SU
                      message: El servicio requerido no se encuentra disponible en el sitio
                      date: '2021-09-27T09:35:03-05:00'
            application/xml:
              schema:
                required:
                  - login
                  - tranKey
                  - nonce
                  - seed
                title: Autenticación
                type: object
                properties:
                  login:
                    type: string
                    description: Identificador del sitio
                  tranKey:
                    type: string
                    description: Credencial **tranKey** generado
                  nonce:
                    type: string
                    description: Valor **aleatorio** para cada solicitud codificado en **Base64**.
                  seed:
                    type: string
                    description: Fecha **actual**, la cual se genera en formato **ISO 8601**.
                description: Estructura que contiene la información de autenticación del sitio generada de acuerdo al WSSE UsernameToken Profile 1.1
      tags:
        - Operaciones con Pinpad
  /cash/orders:
    post:
      summary: Consultar orden de pago
      operationId: post-gateway-search-cashorder
      description: Este servicio permite consultar ordenes de pago mediante los valores de referencia, total y moneda.
      tags:
        - Operaciones con ordenes de pago
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - payment
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payment:
                  title: Datos del pago
                  type: object
                  properties:
                    reference:
                      title: Referencia de pago
                      type: string
                    amount:
                      title: AmountBase
                      type: object
                      description: Estructura que representa una cantidad que define la moneda y el total.
                      properties:
                        currency:
                          type: string
                          description: |
                            Moneda acorde al ISO 4217 (alphabetic code).
                        total:
                          type: number
                          description: |
                            Valor total.
                  required:
                    - reference
                    - amount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: array
                    description: Estructura que contiene las ordenes de pago encontradas. Si no se encontraron registros que coincidan con los filtros proporcionados será un arreglo vacio.
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        status:
                          type: string
                          enum:
                            - PAYED
                            - EXPIRED
                            - ACTIVE
                        payment:
                          type: object
                          properties:
                            reference:
                              type: string
                            description:
                              type: string
                            amount:
                              $ref: '#/paths/~1gateway~1search/post/requestBody/content/application~1json/schema/properties/amount'
                            allowPartial:
                              type: boolean
                            subscribe:
                              type: boolean
                        createdAt:
                          type: string
                        expirationDate:
                          type: string
                        notificationUrl:
                          type: string
                        sessionId:
                          type: number
  /cash/delete:
    post:
      summary: Eliminar orden de pago
      operationId: post-gateway-delete-cashorder
      description: Este servicio permite eliminar una orden de pago en estado pendiente.
      tags:
        - Operaciones con ordenes de pago
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - id
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                id:
                  type: number
                  description: Id de la orden de pago a eliminar.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  id:
                    type: number
                    description: Id de la orden de pago eliminada.
  /gateway/token:
    post:
      summary: Consulta de token
      operationId: post-gateway-search-token
      description: Este servicio permite buscar un token mediante el valor del token o subtoken.
      tags:
        - Tokenización de tarjetas
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - instrument
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  title: Instrument
                  type: object
                  properties:
                    token:
                      title: Token
                      type: object
                      description: Estructura que contiene la información de la tokenización a buscar.
                      properties:
                        id:
                          type: number
                          description: Identificador del token en el sistema.
                        token:
                          type: string
                          description: Código generado para identificar la tarjeta en el sistema.
                        subtoken:
                          type: string
                          description: Código alterno generado para identificar la tarjeta.
                  required:
                    - token
            examples:
              Consulta por token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    description: Objeto con la información de la tokenización encontrada.
                    properties:
                      id:
                        type: number
                        description: Identificador de la tokenización.
                      type:
                        type: string
                        description: Tipo de tokenización.
                      token:
                        type: string
                        description: Código generado para identificar la tarjeta en el sistema
                      subtoken:
                        type: string
                        description: Código alterno generado para identificar la tarjeta
                      franchise:
                        type: string
                        description: Franquicia de la tarjeta
                      franchiseName:
                        type: string
                        description: Nombre de la franquicia de la tarjeta
                      issuerName:
                        type: string
                        description: Nombre del banco emisor de la tarjeta
                      lastDigits:
                        type: string
                        description: Últimos dígitos de la tarjeta
                      validUntil:
                        type: string
                        format: date
                        description: Fecha de expiración de la tarjeta
                      owner:
                        type: string
                        description: Nombre del propietario de la tarjeta
                      bin:
                        type: string
                        description: Primeros 6 dígitos de la tarjeta
                      accountType:
                        type: string
                        description: Tipo de cuenta ACH (SAV, DDA, CCD), aplica solo para Puerto Rico
                      isPromotedToBrandToken:
                        type: boolean
                        description: Indica si el token ha sido promovido a un token de marca. Aplica únicamente si el sitio tiene habilitada la integración de brand tokenization
              examples:
                Ok:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: La petición se ha procesado correctamente
                      date: '2021-06-17T11:29:37-05:00'
                    data:
                      id: 1
                      type: card
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                      subtoken: fakesubtoken00005
                      franchise: visa
                      franchiseName: Visa
                      issuerName: TESTING
                      lastDigits: '1111'
                      validUntil: 12/29
                      owner: John Doe
  /gateway/account-validator/session:
    post:
      summary: Crear Session
      description: Este endpoint permite crear una sesión de verificación de cuenta
      operationId: create-session
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - user
                - returnUrl
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                user:
                  type: object
                  description: |
                    Usuario dueño de la cuenta a validar
                  required:
                    - name
                    - email
                  properties:
                    name:
                      type: string
                      description: Primer nombre o nombres del usuario propietario de la cuenta
                      maxLength: 50
                      example: John
                    surname:
                      type: string
                      description: Apellidos del usuario propietario de la cuenta
                      maxLength: 50
                      example: Doe
                    email:
                      type: email
                      description: Correo Electrónico del usuario propietario de la cuenta
                      maxLength: 80
                      example: John.doe@test.com
                returnUrl:
                  type: string
                  description: Url de retorno una vez culmine el proceso de validación de cuentas
                  maxLength: 255
                  example: https://www.placetopay.com/return
                locale:
                  type: string
                  description: Determina el idioma de la respuesta
                  maxLength: 5
                  example: es_CO
                isAuthenticated:
                  type: boolean
                  description: Determina si ya se ha realizado un proceso de autenticación externa. La intención de no validar el correo electrónico del usuario dos veces. por defecto es false, quiere decir que se realizara envio de OTP para validar el usuario si este ya ha validado cuentas con microdepositos en el sistema
                  example: true
      responses:
        '200':
          description: Sesión creada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Estructura que contiene la respuesta a la solicitud en el caso de que el estado sea exitoso
                    properties:
                      requestId:
                        type: string
                        description: Identificador unico de la sesión que desea consultar.
                        format: regex
                        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                        maxLength: 36
                        example: 9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea
                      redirectUrl:
                        type: string
                        format: uri
                        description: URL de redireccionamiento
                        example: https://dev-account-validator.placetopay.ws/verification/redirect/9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea
                      expiresAt:
                        type: string
                        description: Fecha de expiración de la sesión
                        format: date-time
                        example: '2024-04-19 17:36:57'
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
        '400':
          description: Petición inválida.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
  /gateway/account-validator/query:
    post:
      summary: Consultar estado de sesión
      description: Este endpoint te permitirá consultar el estado de la sesión creada.
      operationId: check-session-status
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - requestId
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                requestId:
                  type: string
                  description: Identificador unico de la sesión que desea consultar.
                  example: 1f630ff7-9c02-4da4-82d4-d676709acb21
                  format: regex
                  pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  maxLength: 36
      responses:
        '200':
          description: Consulta exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    description: Estructura que contiene la respuesta a la solicitud en el caso de que el estado sea exitoso
                    properties:
                      requestId:
                        type: string
                        description: Identificador unico de la sesión que desea consultar.
                        example: 1f630ff7-9c02-4da4-82d4-d676709acb21
                        format: regex
                        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                        maxLength: 36
                      expiresAt:
                        type: string
                        description: Fecha de expiración de la sesión
                        example: '2022-08-30 15:19:33'
                        format: date-time
                      isAuthenticated:
                        type: boolean
                        description: Indica si el usuario ya ha realizado un proceso de autenticación externa
                        example: true
                      token:
                        $ref: '#/components/schemas/Token'
        '400':
          description: Solicitud inválida.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
  /gateway/account-validator/validate:
    post:
      summary: Validar Cuenta existente
      description: Una vez realizada de manera exitosa la creación inicial de la sesión podrá realizar validaciones a la cuenta las veces que considere necesarias, solo debe tener la información de la cuenta y el código de verificación entregado en el proceso anterior.
      operationId: validate-existing-account
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - instrument
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  type: object
                  description: |
                    Token a la que se le realizará la validación.
                  required:
                    - token
                  properties:
                    token:
                      type: object
                      description: |
                        Se requiere el token o subtoken de la cuenta a validar.
                      properties:
                        token:
                          type: string
                          examples:
                            - faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                        subtoken:
                          type: string
                          examples:
                            - fakesubtoken00005
                payment:
                  type: object
                  description: |
                    Estructura que contiene la información acerca del pago de la transacción.
                  required:
                    - name
                    - email
                  properties:
                    amount:
                      type: object
                      description: |
                        Estructura que contiene la información acerca del pago de la transacción.
                      properties:
                        currency:
                          type: string
                          example: USD
                          maxLength: 3
                          minLength: 3
                        total:
                          type: number
                          example: 1000
                locale:
                  type: string
                  example: es_CO
                  default: en
      responses:
        '200':
          description: Respuesta estado de validación
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
        '400':
          description: Solicitud inválida.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
components:
  schemas:
    Subscription:
      title: Subscription
      x-stoplight:
        id: vip3u3guypqyd
      type: object
      description: Estructura que contiene la información sobre una suscripción o transacción que no requiera un monto en específico
      properties:
        reference:
          type: string
          x-stoplight:
            id: hpkr64f4l7gwo
          maxLength: '32'
        description:
          type: string
          minLength: '1'
          x-stoplight:
            id: cc6z3gqusoy1k
          maxLength: '254'
    Document:
      title: Document
      type: object
      description: Estructura que contiene información acerca de un documento
      properties:
        type:
          type: string
          maxLength: '3'
          enum:
            - NIT
            - CC
            - CE
            - RUT
            - TI
          example: NIT
          description: Tipo de documento de identificación. [Para más información](/gateway/document-types)
        number:
          type: string
          example: '123456123'
          description: Número de documento de identificación.
        expeditionDate:
          type: string
          description: 'Fecha de expedición '
        expirationDate:
          type: string
          description: Fecha de expiración
      required:
        - type
        - number
    Account:
      title: Account
      type: object
      description: Estructura que contiene la información de la cuenta bancaria.
      required:
        - bankCode
        - accountType
        - accountNumber
      properties:
        bankName:
          type: string
          maxLength: '30'
          description: Nombre del banco de la cuenta a procesar
        bankCode:
          type: string
          maxLength: '17'
          description: Código que identifica al banco en la red
        accountType:
          type: string
          description: tipo de cuenta
          enum:
            - SAV
            - DDA
            - CCD
        accountNumber:
          type: string
          maxLength: '17'
          description: Número de cuenta
        franchise:
          type: string
          x-stoplight:
            id: bhbb4cpy3me8p
          maxLength: '20'
        verificationCode:
          type: string
          x-stoplight:
            id: jpxori5mf80z2
          example: eyJhbGciOiJSUzI1NiJ9.eyJhY2NvdW50SGFzaCI6ImM5YWM2ZjFhZDhjNDA3Y2ZjNzMyNDljNTE2MTJjNTdmMWQxZGNiNTA4YjE4ZGJlYWE1MWQ0NDI5NjBjMjUwNDUyMzY4ZTg2YmUzMWQ3MDMxMDY4ZDM2MjM2NzVjYzhkYTUzNzhhODNmMTUwZjg5OTczOTBiZTEyMGU1ZmExN2RhIiwib25UZXN0Ijp0cnVlLCJzZXJ2aWNlIjoibW9jayIsImlkIjo0MDB9.dFMY4EwCrWq9EBmERFkKCoLHExPH4vgaCgnZaqB_mf8n3Sv6Qnu6Pb79onluX1OZecmYmBuHqZ_ykKXWSD4RMZSpckYFCiO3mlcJKI4qb91COhl_c2qXxYJuLEdbLfGlzf0k8-oJgFcO9gAS1Xm0hpTP4iiXF6st1hFwlfR3fpX4rr-bTsKgMvRSReMuxa0Vs92DykfqUR_3udlc0DFCPB9ZTaSqeRNHFAPAWNniUPWURQlW5c9J9xcyKTgKGzfI1_7h2I4ALQeRifptE2nC-HZtEMwtcToNh7hn0oL9lNFXnXGK9sWKORcyWKVfpEChS8z30UfX6kOhU6fp_qUwmA
          description: El verificationCode es un JSON Web Signature (JWS). Tiene el fin de ser el instrumento verificador del estado de la cuenta.
    Instrument:
      title: Instrument
      type: object
      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
      properties:
        card:
          $ref: '#/components/schemas/Card'
        account:
          $ref: '#/components/schemas/Account'
        token:
          $ref: '#/components/schemas/Token'
        credit:
          $ref: '#/components/schemas/Credit'
        threeDS:
          type: object
          properties:
            version:
              type: string
              enum:
                - v2
                - v2x
            id:
              type: number
              description: Este valor solo aplica si la validación se hizo con el servicio de 3DS de Placetopay
            enrolled:
              type: string
              minLength: 1
              enum:
                - 'Y'
                - 'N'
                - U
              description: Informa si la tarjeta se encuentra registrada en 3DS
            authenticated:
              type: string
              minLength: 1
              enum:
                - 'Y'
                - 'N'
                - U
                - A
                - I
                - C
                - D
                - R
              maxLength: 1
            eci:
              type: string
              minLength: 1
              description: Indicador del resultado de la autenticación generado por el comercio electrónico.
              enum:
                - '02'
                - '01'
                - '00'
                - '05'
                - '06'
                - '07'
            cavv:
              type: string
              minLength: 28
              maxLength: 28
              nullable: true
              description: Valor de autenticación para la franquicia generado por el ACS. (3DS campo `authenticationValue`).
              example: AJkBABIWcQAAAAM5FwIzdGiYeHM
            xid:
              type: string
              minLength: 1
              description: ID de Transacción DS (3DS campo `dsTransID`).
            extra:
              type: object
              properties:
                transStatusReason:
                  type: string
                  description: Proporciona información sobre el estado de la transacción.
                  nullable: true
                acsTransId:
                  type: string
                  description: Identificador único de transacción generado por el ACS.
                  example: 37a7b6e0-fd58-4e38-98de-79c70c526a47
                threeDSServerTransID:
                  type: string
                  description: Identificador único de transacción generado por el 3DS Server.
                  example: eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
                deviceChannel:
                  type: string
                  description: Canal a través del cual se realiza la transacción.
                  enum:
                    - APP
                    - BRW
                    - RI
                messageCategory:
                  type: string
                  description: Indica la categoría del mensaje.
                  enum:
                    - PA
                    - NPA
                authMethod:
                  type: string
                  description: Indica si la transacción tuvo o no desafío.
                  example: FRICTIONLESS_AUTHENTICATION
                authTimestamp:
                  type: string
                  description: Indica el timestamp de la autenticación.
                  example: '2020-04-21T01:44:54.000Z'
                authInd:
                  type: string
                  description: Define el tipo de autenticación aplicada según el canal utilizado.
                  example: RECURRING_TRANSACTION
            validSignature:
              type: boolean
          required:
            - enrolled
            - authenticated
            - eci
            - cavv
            - xid
            - version
        otp:
          type: string
        pinPad:
          $ref: '#/components/schemas/PinPad'
        pin:
          type: string
          example: 0B880E2326F6409E
          minLength: '2'
          maxLength: '20'
          description: Recibe el código PIN cuando es plano o cuando se trata de un PinBlock
        redirection:
          $ref: '#/components/schemas/Redirection'
        kount:
          $ref: '#/components/schemas/Kount'
        pocket:
          type: string
          description: Bolsillo de la tarjeta utilizado para el pago
    Card:
      title: Card
      type: object
      description: Estructura que contiene la información de la tarjeta.
      properties:
        number:
          type: string
          maxLength: '20'
        expiration:
          type: string
          example: 12/22
          pattern: ^[01]\d\/\d{2}$
        cvv:
          type: string
      required:
        - number
    Token:
      title: Token
      type: object
      description: |-
        Estructura que contiene la información del token que asocia a la tarjeta
        Para la entrada solo es necesario el token o el subtoken y el cvv si se trata de una operación donde el usuario está presente
        Para la salida si se devuelven todos los datos al tokenizar 
      properties:
        id:
          type: number
          description: Identificador del token en el sistema, aplica solo si el sitio cuenta con URL de notificación para token configurada
        token:
          type: string
          maxLength: '64'
          minLength: '64'
          description: Código generado para identificar la tarjeta en el sistema
        subtoken:
          type: string
          maxLength: '16'
          minLength: '16'
          description: Código alterno generado para identificar la tarjeta
        franchise:
          type: string
          enum:
            - visa
            - visa_electron
            - amex
            - master
            - codensa
            - diners
            - jbc
            - discover
            - ris
            - credencial
            - comfama
            - colsubsidio
            - falabella
            - elo
            - somos
            - tuya
            - exito
            - alkosto
            - maestro
            - mefia
            - ath_card
          description: Codigo de la franquicia asociada al token (Solo como respuesta no es necesario enviarla)
        franchiseName:
          type: string
        issuerName:
          type: string
        lastDigits:
          type: string
        validUntil:
          type: string
        cvv:
          type: string
          minLength: 3
          maxLength: 4
          description: CVV solicitado al usuario en caso de que esté presente en la operación
      x-examples:
        Ejemplo respuesta:
          value:
            token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
            subtoken: fakesubtoken00005
            franchise: master
            franchiseName: Mastercard
            lastDigits: '0005'
            validUntil: '2018-12-31'
            installments: '3'
        Ejemplo en solicitud:
          value:
            token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
            cvv: '123'
    Credit:
      title: Credit
      type: object
      description: Estructura que contiene la información del tipo de crédito. Ver más en [Crédito](/gateway/additional-data#additional-data-credit)
      properties:
        code:
          type: string
        type:
          type: string
        groupCode:
          type: string
        installment:
          type: integer
        installments:
          type: array
          items:
            type: integer
        kind:
          type: string
          description: Clasificación de la modalidad de crédito. (Paystudio TS)
        description:
          type: string
    CreditPerInstallment:
      title: Credit
      type: object
      description: Estructura que contiene la información del tipo de crédito. Ver más en [Crédito](/gateway/additional-data#additional-data-credit-providers-paystudio-ts)
      properties:
        installment:
          type: integer
          description: Numero de cuotas
        kind:
          type: string
          description: Clasificación de la modalidad de crédito.
        description:
          type: string
          description: Descripción del crédito.
      required: installment kind
    Pocket:
      title: Pocket
      type: object
      description: Estructura que contiene la información del bolsillo de la tarjeta
      properties:
        code:
          type: string
          description: Valor del bolsillo
        description:
          type: string
          description: Descripción del bolsillo
      x-examples: null
    InterestValues:
      title: InterestValues
      type: object
      description: Estructura que contiene la información del cálculo de intereses para un tipo de crédito y monto
      properties:
        original:
          type: number
        installment:
          type: number
        interest:
          type: number
        total:
          type: number
    LookupResponseDataV2:
      title: LookupResponseDataV2
      type: object
      description: Esta estructura contiene las propiedades necesarias para continuar con una autenticación 3DS.
      properties:
        version:
          type: string
          description: Versión del api en la que se hizo la sesión de autenticación.
          enum:
            - v2
        sessionToken:
          type: string
          example: 1bbf97e3660511d0ce82c15fca343307ba2f87fe84ba421368afb041ba1f638f
        redirectUrl:
          type: string
          description: URL a la cual se debe redirigir al cliente para continuar con el proceso de autenticación.
          example: https://3dss-test.placetopay.com/threeds/v2/sessions/100950/examplea974d40500a650b6a77973985d367ad389a28b747dfdc918756a4ddc1
        identifier:
          type: number
          description: Identificador de la sesión de autenticación.
          example: 263325
      required:
        - version
        - identifier
        - sessionToken
        - redirectUrl
    LookupResponseDataV2X:
      title: LookupResponseDataV2X
      type: object
      description: Los campos aquí descritos corresponden a una respuesta del servicio [3DS](/three-d-s-server/api/transactions/values).
      properties:
        action:
          type: string
          enum:
            - continue
            - redirect
          example: continue
        version:
          type: string
          enum:
            - v2x
        sessionToken:
          type: string
          example: 1bbf97e3660511d0ce82c15fca343307ba2f87fe84ba421368afb041ba1f638f
        redirectUrl:
          type: string
          description: URL a la cual se debe redirigir al cliente para continuar con el proceso de autenticación
          example: https://3dss-test.placetopay.com/threeds/v2/sessions/100950/examplea974d40500a650b6a77973985d367ad389a28b747dfdc918756a4ddc1
        id:
          type: number
          description: Identificador de la sesión de autenticación.
          example: 263325
        enrolled:
          type: string
          enum:
            - 'Y'
            - 'N'
            - U
          description: Presente si `action` fue `continue`. Indica si la tarjeta con la cual se realizó la transacción está enrolada (está registrada en los rangos de tarjeta para el emisor específico).
        authenticated:
          type: string
          description: Presente si `action` fue `continue`. Informa el estado de la autenticación
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - I
            - C
            - D
            - R
          maxLength: 1
        validSignature:
          type: boolean
          description: Presente si `action` fue `continue`. Informa si la firma de la respuesta es válida
        eci:
          type: string
          description: Código de autenticación por franquicia. Indicador del resultado de la autenticación generado por el comercio electrónico.
          enum:
            - '02'
            - '01'
            - '00'
            - '05'
            - '06'
            - '07'
        cavv:
          type: string
          minLength: 28
          maxLength: 28
          nullable: true
          description: Presente si `action` fue `continue`. Valor de autenticación para la franquicia generado por el ACS. (3DS campo `authenticationValue`).
          example: AJkBABIWcQAAAAM5FwIzdGiYeHM
        xid:
          type: string
          minLength: 1
          description: Presente si `action` fue `continue`. ID de Transacción DS (3DS campo `dsTransID`).
        extra:
          type: object
          description: presente si `action` fue `continue`. Información adicional de la transacción.
          properties:
            transStatusReason:
              type: string
              description: Proporciona información sobre el estado de la transacción.
              nullable: true
            acsTransId:
              type: string
              description: Identificador único de transacción generado por el ACS.
              example: 37a7b6e0-fd58-4e38-98de-79c70c526a47
            threeDSServerTransID:
              type: string
              description: Identificador único de transacción generado por el 3DS Server.
              example: eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
            deviceChannel:
              type: string
              description: Canal a través del cual se realiza la transacción.
              enum:
                - APP
                - BRW
                - RI
            messageCategory:
              type: string
              description: Indica la categoría del mensaje.
              enum:
                - PA
                - NPA
            authMethod:
              type: string
              description: Indica si la transacción tuvo o no desafío.
              example: FRICTIONLESS_AUTHENTICATION
            authTimestamp:
              type: string
              description: Indica el timestamp de la autenticación.
              example: '2020-04-21T01:44:54.000Z'
            authInd:
              type: string
              description: Define el tipo de autenticación aplicada según el canal utilizado.
              example: RECURRING_TRANSACTION
            messageVersion:
              type: string
              description: Es el número de versión del protocolo 3DS que utiliza el sistema para ejecutar el flujo de autenticación.
              example: 2.2.0
              nullable: true
      required:
        - enrolled
        - authenticated
        - eci
        - cavv
        - xid
        - version
    PinPad:
      title: PinPad
      type: object
      description: Estructura que contiene la información del servicio PinPad
      properties:
        transactionId:
          type: string
          description: Identificador de la transacción en el servicio PinPad
        positions:
          type: string
          description: Posiciones del PinPad
        pinBlock:
          type: string
          description: PIN encriptado en formato PinBlock
        length:
          type: integer
          description: Longitud del PIN
        format:
          type: integer
          description: Formato de encriptación del PIN
    Redirection:
      title: Redirection
      type: object
      description: Representa un medio de pago de redirección, es decir que requiere que se envíe el usuario a otra URL para completar el proceso
      properties:
        paymentMethod:
          type: string
          enum:
            - _PSE_
            - BTNBC
            - PGEFT
            - BTNAV
            - ATHMV
        returnURL:
          type: string
          format: uri
          maxLength: 250
          description: URL para que una vez se termine el proceso de pago se retorne el control (cuando aplica)
          example: http://your-site.com/your-return-route
        processURL:
          type: string
          format: uri
          maxLength: 250
          description: URL a la cual se debe enviar al cliente para continuar el proceso, está es proporcionada por el servicio
        additional:
          type: object
          description: Estructura para relacionar datos adicionales en el proceso.
          properties:
            bankCode:
              type: string
              description: Código que identifica al banco en la red.
              example: '1007'
            userType:
              type: string
              description: Define si el pagador es una persona natural o jurídica
              enum:
                - person
                - company
            skipRegister:
              type: boolean
              description: Indica si el usuario desea omitir la afiliación a Tarjeta Clave
              default: true
            dispersion:
              type: array
              description: Lista de dispersión de pagos
              items:
                type: object
                properties:
                  serviceCode:
                    type: string
                    description: Código del servicio
                  entityCode:
                    type: string
                    description: Código de la entidad
                  amountValue:
                    type: number
                    description: Valor del monto a pagar
                  taxValue:
                    type: number
                    description: Valor del impuesto aplicado
                  description:
                    type: string
                    description: Detalle sobre la dispersión
    Kount:
      title: Kount
      x-stoplight:
        id: qevzv57mju2tp
      type: object
      description: Maneja información especifica para usar con el filtro de riesgo Kount
      properties:
        session:
          type: string
          description: Identificador de esta operación en Kount, debe ser único por transacción
        type:
          type: string
          description: Describe el tipo de operación que se está manejando en la sesión para definir los campos adicionales a enviar
          enum:
            - airline
            - soat
      required:
        - session
    CardType:
      title: CardType
      x-stoplight:
        id: x4y03rkspgz0b
      type: string
      enum:
        - C
        - R
        - A
      description: Indica el tipo de la tarjeta. C = credito, R = debito, A = ahorros
    BankItem:
      title: BankItem
      x-stoplight:
        id: 60487hsjhovs9
      type: object
      properties:
        code:
          type: string
          description: Código de la entidad bancaria
        description:
          type: string
          description: Nombre de la entidad bancaria
    BalanceInstrument:
      title: Instrument
      type: object
      description: Estructura que contiene la información acerca del medio de pago a usar en una transacción, esta estructura es variable de acuerdo a la solicitud que se genere, cada servicio requiere que se usen unos u otros datos.
      properties:
        card:
          $ref: '#/components/schemas/BalanceCard'
    BalanceCard:
      title: Card
      type: object
      description: Estructura que contiene la información de la tarjeta.
      properties:
        number:
          type: string
          maxLength: '20'
        expiration:
          type: string
          example: 12/22
          pattern: ^[01]\d\/\d{2}$
      required:
        - number
        - expiration
    Payer:
      type: object
      properties:
        name:
          type: string
          example: John
        surname:
          type: string
          example: Doe
        email:
          type: string
          example: johnDoe@email.com
        mobile:
          type: string
          description: El numero celular puede contener el indicativo del país
          example: '+573111111111'
        address:
          title: Address
          type: object
          description: Estructura que contiene la información sobre una dirección física
          properties:
            street:
              type: string
              maxLength: '128'
              description: Calle
            city:
              type: string
              maxLength: '30'
              description: Ciudad
            state:
              type: string
              maxLength: '3'
              description: Código de la subdivisión del país que representa el estado o provincia. Formato ISO 3166-2
              example: CUN
            postalCode:
              type: string
              maxLength: '10'
              description: Código postal
              example: '110111'
            country:
              type: string
              maxLength: '2'
              example: CO
              description: País. Código ISO 3166-1 alpha-2
            phone:
              type: string
              maxLength: '20'
              description: Teléfono
              example: '3003003000'
    Buyer:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Payer/properties/address'
