openapi: 3.1.0
info:
  title: Placetopay WebCheckout
  version: '1.0'
  description: |
    WebCheckout es una página web prediseñada, optimizada y alojada en Placetopay que le permite aceptar pagos en línea de forma rápida y segura desde dispositivos móviles y de escritorio. Puedes aceptar pagos únicos, pagos recurrentes, pagos mixtos y suscribir medios de pago.

    Webcheckout te permite:

    * **Diseño personalizado:** Puedes personalizar los nombres, logos y colores de tu empresa.
    * **Diferentes idiomas y monedas:** Aceptar pagos en multiples idiomas y monedas.
    * **Adaptado a diferentes resoluciones:** Diseño receptivo para diferentes dispositivos.
    * **Wallet Placetopay:** WebCheckout cuenta con su propia billetera que le permite a usuarios guardar medios de pago frecuentes brindando mayor seguridad y facilidad en el proceso de pago.
    * **Seguridad de la información:** Lineamientos PCI que garantizan seguridad en la captura y procesamiento de la información sensible de tarjetas.
    * **Pagos avanzados:** Pagos con Impuestos, pagos mixtos, suscripciones, cobros recurrentes, promociones y más...

    <!-- theme: info -->
    > #### Acerca de HTTPS
    >
    > Para hacer uso de este servicio es necesario que tu sistema soporte comunicación con la versión 1.2 del protocolo TLS.
  contact:
    url: https://www.evertecinc.com/pasarela-de-pagos-e-commerce/
    name: Placetopay by Evertec
  summary: Usa WebCheckout para aceptar pagos en línea de forma sencilla y segura
servers:
  - description: Sandbox (CO, PR, CR, PA)
    url: https://checkout-test.placetopay.com/
  - url: https://checkout-test.placetopay.ec/
    description: SandBox EC
  - url: https://checkout.placetopay.com
    description: Producción (CO, PR, CR, PA)
  - url: https://checkout.placetopay.ec
    description: Producción (EC)
paths:
  /api/session:
    post:
      summary: Crear sesión (CreateRequest)
      operationId: post-api-session
      description: Solicita la creación de la sesión, retorna el identificador y la URL de procesamiento.
      x-internal: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedirectRequest'
            examples:
              Crear Sesión simple:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              'Crear sesión de preautorización ':
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  type: checkin
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con pago mixto:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                    allowPartial: true
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con impuestos:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Reference
                    amount:
                      currency: USD
                      total: 500
                      taxes:
                        - kind: stateTax
                          amount: 16.13
                        - kind: municipalTax
                          amount: 11.21
                        - kind: reducedStateTax
                          amount: 10.21
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con dispersión:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Reference
                    amount:
                      currency: USD
                      total: 500
                    dispersion:
                      - agreement: '1299'
                        agreementType: MERCHANT
                        amount:
                          currency: USD
                          total: 200
                      - agreement: ''
                        agreementType: MERCHANT
                        amount:
                          currency: USD
                          total: 300
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión suscripción:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  subscription:
                    reference: '331122'
                    description: Una suscripción de prueba
                  expiration: '2021-12-31T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con recurrencia:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Pago con recurrencia
                    amount:
                      currency: USD
                      total: 100
                    recurring:
                      periodicity: D
                      interval: '1'
                      nextPayment: '2021-12-30'
                      maxPeriods: '12'
                  expiration: '2022-12-15T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con modificadores:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Pago con modificadores
                    amount:
                      currency: UYU
                      total: 2000
                    modifiers:
                      - type: FEDERAL_GOVERNMENT
                        code: 17934
                        additional:
                          invoice: '112233'
                  expiration: '2022-12-15T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con detalles:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Reference
                    amount:
                      currency: USD
                      total: 500
                      details:
                        - kind: tip
                          amount: 11
                        - kind: subtotal
                          amount: 11
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Crear sesión con pago y subscripción:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payer:
                    document: '1122334455'
                    documentType: CC
                    name: John
                    surname: Doe
                    company: Evertec
                    email: johndoe@app.com
                    mobile: '+5731111111111'
                  payment:
                    reference: '12345'
                    description: Prueba de pago y subscripción
                    amount:
                      currency: COP
                      total: 2000
                    subscribe: true
                  fields:
                    - keyword: _processUrl_
                      value: https://checkout.redirection.test/session/1/a592098e22acc709ec7eb30fc0973060
                      displayOn: none
                  expiration: '2019-08-24T14:15:22Z'
                  returnUrl: https://commerce.test/return
                  cancelUrl: https://commerce.test/cancel
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
                  skipResult: false
                  noBuyerFill: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  requestId:
                    type: integer
                  processUrl:
                    type: string
              examples:
                Respuesta:
                  value:
                    status:
                      status: OK
                      reason: PC
                      message: La petición se ha procesado correctamente
                      date: '2021-11-30T15:08:27-05:00'
                    requestId: 1
                    processUrl: https://checkout-co.placetopay.com/session/1/cc9b8690b1f7228c78b759ce27d7e80a
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                Respuesta:
                  value:
                    status:
                      status: FAILED
                      reason: 401
                      message: Autenticación fallida 102
                      date: '2021-11-30T15:12:25-05:00'
    parameters: []
  /api/session/{requestId}:
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    post:
      summary: Consultar sesión (getSessionInformation)
      operationId: post-api-session-requestId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedirectInformation'
              examples:
                Aprobado:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED
                      reason: '00'
                      message: La petición ha sido aprobada exitosamente
                      date: '2021-11-30T15:49:47-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: LastName
                        email: dnetix1@app.com
                        mobile: '3111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '1122334455'
                        description: Prueba
                        amount:
                          currency: USD
                          total: 1000
                        allowPartial: false
                        subscribe: false
                      fields:
                        - keyword: _processUrl_
                          value: https://test.placetopay.com/redirection/session/1/cb0f71a1f1ecdfab3ac345d3d670b097
                          displayOn: none
                      returnUrl: https://redirection.test/home
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: APPROVED
                          reason: '00'
                          message: Aprobada
                          date: '2021-11-30T15:49:36-05:00'
                        internalReference: 1
                        paymentMethod: visa
                        paymentMethodName: Visa
                        issuerName: JPMORGAN CHASE BANK, N.A.
                        amount:
                          from:
                            currency: USD
                            total: 1000
                          to:
                            currency: USD
                            total: 1000
                          factor: 1
                        authorization: '000000'
                        reference: '1122334455'
                        receipt: '241516'
                        franchise: DF_VS
                        refunded: false
                        processorFields:
                          - keyword: merchantCode
                            value: '7200076413'
                            displayOn: none
                          - keyword: terminalNumber
                            value: PT312002
                            displayOn: none
                          - keyword: credit
                            value:
                              code: '0'
                              type: '00'
                              groupCode: C
                              installments: 0
                            displayOn: none
                          - keyword: totalAmount
                            value: 1000
                            displayOn: none
                          - keyword: iceAmount
                            value: 0
                            displayOn: none
                          - keyword: bin
                            value: '411111'
                            displayOn: none
                          - keyword: expiration
                            value: '1229'
                            displayOn: none
                          - keyword: lastDigits
                            value: '1111'
                            displayOn: none
                    subscription: null
                Pendiente:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: La petición se encuentra pendiente
                      date: '2021-11-30T15:45:57-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: lastName
                        email: dnetix1@app.com
                        mobile: '3111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '1122334455'
                        description: Prueba
                        amount:
                          currency: USD
                          total: 1000
                        allowPartial: false
                        subscribe: false
                      fields:
                        - keyword: _processUrl_
                          value: https://test.placetopay.com/redirection/session/1/e0dfb6c7d6ab964b2377c825aef56a63
                          displayOn: none
                      returnUrl: https://dnetix.co/p2p/client
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment: null
                    subscription: null
                Rechazado:
                  value:
                    requestId: 1
                    status:
                      status: REJECTED
                      reason: XN
                      message: Se ha rechazado la petición
                      date: '2021-11-30T16:44:24-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: LastName
                        email: dnetix@app.com
                        mobile: '31111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '331122'
                        description: Reference
                        amount:
                          currency: USD
                          total: 500
                        allowPartial: false
                        subscribe: false
                        dispersion:
                          - reference: '331122'
                            description: Reference
                            amount:
                              currency: USD
                              total: 200
                            allowPartial: false
                            subscribe: false
                            agreement: '26'
                            agreementType: AIRLINE
                          - reference: '331122'
                            description: Reference
                            amount:
                              currency: USD
                              total: 300
                            allowPartial: false
                            subscribe: false
                            agreementType: MERCHANT
                      fields:
                        - keyword: _processUrl_
                          value: https://test.placetopay.com/redirection/session/1/1dfbaf16c76c6ee83a63a956d704a9d1
                          displayOn: none
                      returnUrl: https://redirection.test/home
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: REJECTED
                          reason: '65'
                          message: '65'
                          date: '2021-11-30T16:22:19-05:00'
                        internalReference: 1
                        paymentMethod: visa
                        paymentMethodName: Visa
                        issuerName: CAIXA D'ESTALVIS UNIO DE CAIXES DE MANLLEU, SABADE
                        amount:
                          from:
                            currency: USD
                            total: 500
                          to:
                            currency: USD
                            total: 500
                          factor: 1
                        authorization: '000000'
                        reference: '331122'
                        franchise: TS_VS
                        refunded: false
                        processorFields:
                          - keyword: totalAmount
                            value: 500
                            displayOn: none
                          - keyword: lastDigits
                            value: '6853'
                            displayOn: none
                        dispersion:
                          - status:
                              status: REJECTED
                              reason: '65'
                              message: '65'
                              date: '2021-11-30T16:34:17-05:00'
                            internalReference: 2
                            amount:
                              from:
                                currency: USD
                                total: 200
                              to:
                                currency: USD
                                total: 200
                              factor: 1
                            authorization: '000000'
                            franchise: TS_VS
                            refunded: false
                            agreement: 26
                            agreementType: AIRLINE
                          - status:
                              status: REJECTED
                              reason: '?C'
                              message: Pago abortado por el usuario
                              date: '2021-11-30T16:34:17-05:00'
                            internalReference: 3
                            amount:
                              from:
                                currency: USD
                                total: 300
                              to:
                                currency: USD
                                total: 300
                              factor: 1
                            authorization: '000000'
                            receipt: '000000'
                            franchise: ID_VS
                            refunded: false
                            agreementType: MERCHANT
                    subscription: null
                Expirado parcialmente:
                  value:
                    requestId: 1
                    status:
                      status: PARTIAL_EXPIRED
                      reason: PX
                      message: La petición esta expirada o cancelada y se han realizado pagos
                      date: '2023-03-09T17:10:34-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '111111111'
                        documentType: CC
                        name: John
                        surname: Doe
                        email: user_email@example.com
                        mobile: '+573111111111'
                      payment:
                        reference: '331122'
                        description: Reference
                        amount:
                          currency: USD
                          total: 500
                        allowPartial: false
                        subscribe: false
                        dispersion:
                          - reference: '331122'
                            description: Reference
                            amount:
                              currency: USD
                              total: 200
                            allowPartial: false
                            subscribe: false
                            agreement: '111'
                            agreementType: MERCHANT
                          - reference: '331122'
                            description: Reference
                            amount:
                              currency: USD
                              total: 300
                            allowPartial: false
                            subscribe: false
                            agreementType: MERCHANT
                      fields:
                        - keyword: _processUrl_
                          value: https://checkout.redirection.test/session/750/20e2eb0d4681a916549e95ed49a11080
                          displayOn: none
                      returnUrl: https://redirection.test/home
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2023-03-09T23:09:14.946Z'
                    payment:
                      - amount:
                          to:
                            total: 500
                            currency: USD
                          from:
                            total: 500
                            currency: USD
                          factor: 1
                        status:
                          date: '2023-03-09T17:10:14-05:00'
                          reason: '61'
                          status: APPROVED_PARTIAL
                          message: Negada, Monto excede el máximo definido por la Entidad Financiera en el archivo de Tarjetahabientes
                        receipt: '110000857921'
                        refunded: false
                        franchise: EB_VS
                        reference: '331122'
                        dispersion:
                          - amount:
                              to:
                                total: 200
                                currency: USD
                              from:
                                total: 200
                                currency: USD
                              factor: 1
                            status:
                              date: '2023-03-09T17:10:14-05:00'
                              reason: '00'
                              status: APPROVED
                              message: Aprobada
                            receipt: '110000857921'
                            refunded: false
                            franchise: EB_VS
                            agreementType: MERCHANT
                            authorization: '614761'
                            internalReference: 421692
                          - amount:
                              to:
                                total: 300
                                currency: USD
                              from:
                                total: 300
                                currency: USD
                              factor: 1
                            status:
                              date: '2023-03-09T17:10:14-05:00'
                              reason: '61'
                              status: REJECTED
                              message: Negada, Monto excede el máximo definido por la Entidad Financiera en el archivo de Tarjetahabientes
                            receipt: '421693'
                            refunded: false
                            franchise: EB_VS
                            agreementType: MERCHANT
                            authorization: '000000'
                            internalReference: 421693
                        issuerName: BANCO DE GUAYAQUIL, S.A.
                        authorization: '614761'
                        paymentMethod: visa
                        processorFields:
                          - value: '4549106521651'
                            keyword: merchantCode
                            displayOn: none
                          - value: '19371021'
                            keyword: terminalNumber
                            displayOn: none
                          - value: '411076'
                            keyword: bin
                            displayOn: none
                          - value: 200
                            keyword: totalAmount
                            displayOn: none
                          - value: '0057'
                            keyword: lastDigits
                            displayOn: none
                          - value: eeacbe4f36c8f8117fc4d7ab47fa366f
                            keyword: id
                            displayOn: none
                          - value: '61'
                            keyword: b24
                            displayOn: none
                        internalReference: 421691
                        paymentMethodName: Visa
                    subscription: null
                Aprobado Parcialmente:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED_PARTIAL
                      reason: P0
                      message: La petición está parcialmente aprobada
                      date: '2023-03-09T17:29:13-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '111111111'
                        documentType: CC
                        name: Antonino
                        surname: Pan y queso
                        email: root13@app.com
                        mobile: '+573111111111'
                      payment:
                        reference: GAD_1675183488
                        description: Pago GAD Municipal de Cuenca
                        amount:
                          currency: COP
                          total: 10000
                        allowPartial: true
                        subscribe: false
                      fields:
                        - keyword: _processUrl_
                          value: https://checkout.redirection.test/session/751/cfe5a789a27feca7fe211bd400db354d
                          displayOn: none
                      returnUrl: https://mysite.com/response/32120
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2023-03-09T23:28:43.775Z'
                    payment:
                      - amount:
                          to:
                            total: 1.05
                            currency: USD
                          from:
                            total: 5000
                            currency: COP
                          factor: 0.00021
                        status:
                          date: '2023-03-09T17:29:03-05:00'
                          reason: '00'
                          status: APPROVED
                          message: Aprobada
                        receipt: '110000288071'
                        refunded: false
                        franchise: EB_VS
                        reference: GAD_1675183488
                        issuerName: JPMORGAN CHASE BANK, N.A.
                        authorization: '614761'
                        paymentMethod: visa
                        processorFields:
                          - value: '4549106521651'
                            keyword: merchantCode
                            displayOn: none
                          - value: '19371021'
                            keyword: terminalNumber
                            displayOn: none
                          - value: '411111'
                            keyword: bin
                            displayOn: none
                          - value: '1111'
                            keyword: lastDigits
                            displayOn: none
                          - value: 74a6ef63ea0d1fcc78f4c471b0ae7f3d
                            keyword: id
                            displayOn: none
                          - value: '00'
                            keyword: b24
                            displayOn: none
                        internalReference: 421694
                        paymentMethodName: Visa
                    subscription: null
                Pendiente de Confirmación:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: La petición se encuentra pendiente
                      date: '2025-01-21T21:20:07-05:00'
                    request:
                      locale: es_CO
                      payment:
                        reference: TEST_VISA
                        description: Pago de prueba
                        amount:
                          currency: USD
                          total: 100
                      metadata:
                        requiresConfirmation: true
                      returnUrl: https://comercio.com/retorno
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2026-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: PENDING_CONFIRMATION
                          reason: PT
                          message: Transacción pendiente de confirmación
                          date: '2025-01-21T21:20:07-05:00'
                        internalReference: 84
                        paymentMethod: visa
                        paymentMethodName: Visa
                        issuerName: JPMORGAN CHASE BANK, N.A.
                        amount:
                          from:
                            currency: USD
                            total: 100
                          to:
                            currency: USD
                            total: 100
                          factor: 1
                        authorization: '000000'
                        reference: TEST_VISA
                        receipt: '426882'
                        franchise: CR_VS
                        refunded: false
                    subscription: null
      description: |
        Obtiene la información de la sesión, si en la sesión hay transacciones se muestra el detalle de las mismas.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
              properties:
                auth:
                  $ref: '#/components/schemas/Authentication'
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
          application/xml:
            schema:
              description: ''
              type: object
              properties:
                auth:
                  type: object
                  properties:
                    login:
                      type: string
                      minLength: 1
                    tranKey:
                      type: string
                      minLength: 1
                    nonce:
                      type: string
                      minLength: 1
                    seed:
                      type: string
                      minLength: 1
                  required:
                    - login
                    - tranKey
                    - nonce
                    - seed
              required:
                - auth
  /api/session/{requestId}/cancel:
    parameters:
      - in: path
        name: requestId
        required: true
        schema:
          type: integer
        description: Identificador de la sesión a cancelar
    post:
      summary: Cancelar sesion
      operationId: cancel-api-session-requestId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSessionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSessionResponse'
        4XX:
          description: No se pudo completar la operación debido a un error inesperado.
          $ref: '#/components/responses/StatusResponse'
  /api/notify:
    post:
      summary: Notificar Pago
      operationId: post-api-notify
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/components/schemas/Authentication'
                internalReference:
                  type:
                    - string
                    - number
                    - integer
                  description: |
                    Referencia interna de la transacción a reembolsar que se encuentra en el listado de transacciones del getRequestInformation (payment).
                reference:
                  type: string
                  description: Referencia del pago
                signature:
                  type: string
                  description: Firma de la transacción almacenada en core
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 1
                  reference: '12345'
                  signature: 3ccbae73d6a5bb1be7e00f9a2cfc3cc7cd95a311
      description: Permite solicitar el cambio de estado de una transacción que se encuentre en estado pendiente
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                Aprobada:
                  value:
                    status:
                      status: OK
                      reason: null
                      message: null
                      date: '2021-12-07T16:27:56-05:00'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                Firma inválida:
                  value:
                    status:
                      status: FAILED
                      reason: 0
                      message: Firma inválida
                      date: '2021-12-07T16:24:20-05:00'
      x-internal: true
    parameters: []
  /api/collect:
    post:
      summary: Cobro usando token (Collect)
      operationId: post-api-collect
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectResponse'
              examples:
                Aprobado:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED
                      reason: '00'
                      message: La petición ha sido aprobada exitosamente
                      date: '2021-11-30T15:49:47-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: LastName
                        email: dnetix1@app.com
                        mobile: '3111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '1122334455'
                        description: Prueba
                        amount:
                          currency: USD
                          total: 100
                        allowPartial: false
                        subscribe: false
                      returnUrl: https://redirection.test/home
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: APPROVED
                          reason: '00'
                          message: Aprobada
                          date: '2021-11-30T15:49:36-05:00'
                        internalReference: 1
                        paymentMethod: visa
                        paymentMethodName: Visa
                        issuerName: JPMORGAN CHASE BANK, N.A.
                        amount:
                          from:
                            currency: USD
                            total: 100
                          to:
                            currency: USD
                            total: 100
                          factor: 1
                        authorization: '000000'
                        reference: '1122334455'
                        receipt: '241516'
                        franchise: DF_VS
                        refunded: false
                        processorFields:
                          - keyword: lastDigits
                            value: '1111'
                            displayOn: none
                    subscription: null
                Pendiente:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: La petición se encuentra pendiente
                      date: '2021-11-30T15:45:57-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: lastName
                        email: dnetix1@app.com
                        mobile: '3111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '1122334455'
                        description: Prueba
                        amount:
                          currency: USD
                          total: 100
                        allowPartial: false
                        subscribe: false
                      returnUrl: https://dnetix.co/p2p/client
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment: null
                    subscription: null
                Rechazado:
                  value:
                    requestId: 1
                    status:
                      status: REJECTED
                      reason: XN
                      message: Se ha rechazado la petición
                      date: '2021-11-30T16:44:24-05:00'
                    request:
                      locale: es_CO
                      payer:
                        document: '1033332222'
                        documentType: CC
                        name: Name
                        surname: LastName
                        email: dnetix@app.com
                        mobile: '31111111111'
                        address:
                          postalCode: '12345'
                      payment:
                        reference: '331122'
                        description: Reference
                        amount:
                          currency: USD
                          total: 500
                        allowPartial: false
                        subscribe: false
                      returnUrl: https://redirection.test/home
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2021-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: REJECTED
                          reason: '65'
                          message: '65'
                          date: '2021-11-30T16:22:19-05:00'
                        internalReference: 1
                        paymentMethod: visa
                        paymentMethodName: Visa
                        issuerName: CAIXA D'ESTALVIS UNIO DE CAIXES DE MANLLEU, SABADE
                        amount:
                          from:
                            currency: USD
                            total: 100
                          to:
                            currency: USD
                            total: 100
                          factor: 1
                        authorization: '000000'
                        reference: '331122'
                        franchise: TS_VS
                        refunded: false
                        processorFields:
                          - keyword: lastDigits
                            value: '1111'
                            displayOn: none
                    subscription: null
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectRequest'
            examples:
              Cobro con token simple:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Cobro con token a una preautorización:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                  type: checkin
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Cobro con  bolsillo de tarjeta:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Prueba
                    amount:
                      currency: USD
                      total: 100
                  instrument:
                    pocket: 10
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                  expiration: '2021-12-30T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
      description: |
        Permite realizar cobros sin la intervención del usuario usando medios de pago previamente suscritos.
      x-internal: false
  /api/transaction:
    post:
      summary: Acciones de transacción (TransactionPayment)
      operationId: post-api-transaction
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
              examples:
                Checkout:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-11-30T09:36:00-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Aprobada
                        date: '2021-11-30T09:35:59-05:00'
                      internalReference: 643
                      paymentMethod: visa
                      paymentMethodName: Visa
                      issuerName: JPMORGAN CHASE BANK, N.A.
                      amount:
                        from:
                          currency: USD
                          total: 500
                        to:
                          currency: USD
                          total: 500
                        factor: 1
                      authorization: '550044'
                      reference: '1122334455'
                      receipt: '499435368733'
                      franchise: PS_VS
                      refunded: false
                Reauthorization:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-11-30T09:26:50-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Aprobada
                        date: '2021-11-30T09:26:49-05:00'
                      internalReference: 642
                      paymentMethod: visa
                      paymentMethodName: Visa
                      issuerName: JPMORGAN CHASE BANK, N.A.
                      amount:
                        from:
                          currency: USD
                          total: 500
                        to:
                          currency: USD
                          total: 500
                        factor: 1
                      authorization: '883327'
                      reference: '1122334455'
                      receipt: '657093859996'
                      franchise: PS_VS
                      refunded: false
                Reverse:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-11-30T09:37:46-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Aprobada
                        date: '2021-11-30T09:37:46-05:00'
                      internalReference: 644
                      paymentMethod: visa
                      paymentMethodName: Visa
                      issuerName: JPMORGAN CHASE BANK, N.A.
                      amount:
                        from:
                          currency: USD
                          total: 500
                        to:
                          currency: USD
                          total: 1000
                        factor: 1
                      authorization: '550044'
                      reference: '1122334455'
                      receipt: '499435368733'
                      franchise: PS_VS
                      refunded: false
                Confirmar:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2025-01-21T21:20:07-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Aprobada
                        date: '2025-01-21T21:20:07-05:00'
                      internalReference: 84
                      paymentMethod: visa
                      paymentMethodName: Visa
                      issuerName: JPMORGAN CHASE BANK, N.A.
                      amount:
                        from:
                          currency: USD
                          total: 100
                        to:
                          currency: USD
                          total: 100
                        factor: 1
                      authorization: '000000'
                      reference: TEST_VISA
                      receipt: '426882'
                      franchise: CR_VS
                      refunded: false
                Cancelar:
                  value:
                    status:
                      status: REJECTED
                      reason: '?C'
                      message: Cancelada por el comercio
                      date: '2025-01-21T21:20:07-05:00'
                    payment:
                      status:
                        status: REJECTED
                        reason: '?C'
                        message: Cancelada por el comercio
                        date: '2025-01-21T21:20:07-05:00'
                      internalReference: 84
                      paymentMethod: visa
                      paymentMethodName: Visa
                      issuerName: JPMORGAN CHASE BANK, N.A.
                      amount:
                        from:
                          currency: USD
                          total: 100
                        to:
                          currency: USD
                          total: 100
                        factor: 1
                      authorization: '000000'
                      reference: TEST_VISA
                      receipt: '426882'
                      franchise: CR_VS
                      refunded: false
        '400':
          description: Solicitud inválida
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                SesiónNoSoportada:
                  value:
                    status:
                      status: FAILED
                      reason: request_not_valid
                      message: La acción [confirm] no está soportada para esta sesión
                      date: '2025-01-21T21:20:07-05:00'
                TransacciónNoPendienteConfirmación:
                  value:
                    status:
                      status: FAILED
                      reason: request_not_valid
                      message: La acción [confirm] solo está disponible para transacciones en estado pendiente de confirmación
                      date: '2025-01-21T21:20:07-05:00'
                ServicioNoDisponible:
                  value:
                    status:
                      status: FAILED
                      reason: transaction_request_error
                      message: La transacción ya ha sido expirada
                      date: '2025-01-21T21:20:07-05:00'
      description: Permite realizar operaciones básicas de preauthorización como `checkout`, `reauthorization`, (No aplica para Puerto Rico). También permite confirmar (`confirm`) o cancelar (`cancel`) transacciones en estado PENDING_CONFIRMATION, y revertir un pago aprobado con `reverse`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionActionRequest'
            examples:
              Checkout:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 640
                  amount:
                    currency: USD
                    total: '500'
                  action: checkout
              Reauthorization:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 640
                  amount:
                    currency: USD
                    total: '500'
                  action: reauthorization
              Reverse:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 123
                  action: reverse
              Confirmar:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 84
                  action: confirm
              Cancelar:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 84
                  action: cancel
        description: ''
      x-internal: false
  /api/instrument/invalidate:
    post:
      summary: Invalidar Token (InstrumentInvalidateRequest)
      responses:
        '200':
          $ref: '#/components/responses/StatusResponse'
        '400':
          $ref: '#/components/responses/StatusResponse'
      operationId: post-api-instrument-invalidate
      description: Permite invalidar un token ya existente del sitio. Esto hará que el token o el subtoken ya no se pueda usar.
      requestBody:
        $ref: '#/components/requestBodies/InstrumentInvalidateRequest'
  /api/gateway/information:
    post:
      summary: Este servicio proporciona información sobre la tarjeta/token del usuario que se va a procesar. Se recomienda integrarse siempre a través de la API [Gateway](/gateway/api/reference/information).
      responses:
        '200':
          $ref: '#/components/responses/GatewayInformationResponse'
        '400':
          description: FAILED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
      operationId: post-api-instrument-invalidate
      description: Permite invalidar un token ya existente del sitio. Esto hará que el token o el subtoken ya no se pueda usar.
      requestBody:
        $ref: '#/components/requestBodies/GatewayInformationRequest'
  /api/gateway/token:
    post:
      summary: Este servicio permite buscar una tokenización mediante el valor del token o subtoken. Se recomienda integrarse siempre a través de la API [Gateway](/gateway/api/reference/token).
      operationId: post-api-gateway-token
      requestBody:
        $ref: '#/components/requestBodies/GatewayTokenRequest'
      responses:
        '200':
          $ref: '#/components/responses/GatewayTokenResponse'
        '400':
          description: FAILED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
  /merchant-api/notification-url:
    post:
      summary: Notificación enviada al comercio (MerchantNotificationRequest)
      operationId: merchant-api-notification-url
      requestBody:
        $ref: '#/components/requestBodies/MerchantNotificationRequest'
components:
  schemas:
    Person:
      description: Estructura que refleja la información de una persona involucrada en una transacción.
      type: object
      title: Person
      properties:
        document:
          type: string
          maxLength: 25
          description: Documento de identidad. La validación de su formato y longitud se aplica dinámicamente según el país y el tipo de documento seleccionado
          example: '1122334455'
        documentType:
          type: string
          example: CC
          maxLength: 6
          description: |
            Identificador del tipo de documento. Ver opciones en [Tipos de documento](/checkout/document-types)

            EJ: `CC` para "Cédula de Ciudadanía" en Colombia.
        name:
          type: string
          minLength: 1
          maxLength: 60
          description: Nombre de la persona o empresa
          example: Juan José
        surname:
          type: string
          minLength: 1
          maxLength: 60
          description: Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa
          example: Peréz Pinzon
        company:
          type: string
          minLength: 1
          maxLength: 60
          description: |
            Nombre de la compañia a la que pertenece la persona

            EJ: `Placetopay`
          example: Evertec
        email:
          type: string
          minLength: 1
          maxLength: 80
          example: juan.perez@example.com
          description: Correo eléctronico del usuario o empresa
        mobile:
          type: string
          minLength: 1
          maxLength: 30
          description: Número de teléfono del usuario o empresa
          example: '+573111111111'
        address:
          $ref: '#/components/schemas/Address'
    PaymentRequest:
      title: PaymentRequest
      type: object
      description: |
        Información del pago solicitado.
      required:
        - reference
        - amount
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 32
          description: |
            Referencia única del pago. compuesta por hasta 32 caracteres alfanuméricos y símbolos permitidos
            EJ: `PAYMENT_0001_ABC`, `Venta_1234-ABCD#2024/03/15$500`, `Ord: 1001/2023`
          example: PAYMENT_0001_ABC
        description:
          type: string
          minLength: 1
          maxLength: 255
          description: |
            Descripción del proceso a realizar, permitiendo hasta 250 caracteres alfanuméricos, acentuados y símbolos comunes.
          example: Cita con el Dr. Pérez a las 10:00 am. 5/12/2024, por $100.00
        amount:
          $ref: '#/components/schemas/Amount'
        allowPartial:
          type: boolean
          description: |
            Define si el monto a ser cobrado puede ser pagado en varias transacciones.
            Cuando es `true` el usuario podrá completar el pago en varias transacciones.
          default: false
        shipping:
          $ref: '#/components/schemas/Person'
          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.
        fields:
          $ref: '#/components/schemas/Fields'
        recurring:
          $ref: '#/components/schemas/Recurring'
        subscribe:
          type: boolean
          description: |
            Cuando se envía `true`, se genera una sesión de pago con suscripción.

            En el proceso de pago, el usuario puede elegir si quiere o no guardar su medio de pago para que sea usado en futuros cobros.
          default: false
        dispersion:
          type: array
          description: |
            Cuando se define, se genera una sesión de pago con dispersión.
            El pago generado puede ser dividido en diferentes destinos según las condiciones dadas.
          items:
            $ref: '#/components/schemas/DispersionDetail'
        modifiers:
          type: array
          items:
            $ref: '#/components/schemas/Modifiers'
          description: |
            Estructura para definir modificadores en el cobro.

            Aplica para leyes de impuestos en paises especificos.
        processorFields:
          type: array
          description: Estructura que  puede variar en el tiempo según la información disponible para el medio de pago.  Ver más en [Datos de procesamiento](/checkout/processor-fields)
          items:
            $ref: '#/components/schemas/NameValuePair'
      examples:
        - reference: '12345'
          description: Prueba de pago
          amount:
            currency: COP
            total: 2000
            taxes:
              - kind: valueAddedTax
                amount: 1000
                base: 0
            details:
              - kind: discount
                amount: 1000
          allowPartial: false
          shipping:
            document: '1122334455'
            documentType: CC
            name: John
            surname: Doe
            company: Evertec
            email: johndoe@app.com
            mobile: '+5731111111111'
            address:
              street: 123 Example Street, Sample City, ST 12345
              city: Medellín
              state: Poblado
              postalCode: '55555'
              country: CO
              phone: '+573111111111'
          items:
            - sku: '12345'
              name: product_1
              category: physical
              qty: '1'
              price: 1000
              tax: 0
          fields:
            - keyword: _test_field_value_
              value: _test_field_
              displayOn: approved
          recurring:
            periodicity: D
            interval: '1'
            nextPayment: '2019-08-24'
            maxPeriods: 1
            'dueDate ': '2019-09-24'
            'notificationUrl ': https://checkout.placetopay.com
          subscribe: false
          dispersion:
            - agreement: '1299'
              agreementType: MERCHANT
              amount:
                currency: USD
                total: 200
          modifiers:
            - type: FEDERAL_GOVERNMENT
              code: 17934
              additional:
                invoice: '123345'
    Amount:
      title: Amount
      type: object
      x-internal: false
      description: |
        Información del monto a cobrar
      properties:
        currency:
          type: string
          example: COP
          minLength: 3
          maxLength: 3
          description: |
            Código alfabético de la moneda a usar [ISO 4217 alpha code](https://es.wikipedia.org/wiki/ISO_4217)   
            EJ: `USD`
        total:
          type: number
          example: 2000
          description: |
            Valor total en la moneda base indicada   
            EJ: `1000` equivalen a _Mil dolares_
        taxes:
          description: |
            Estructura para definir impuestos en el proceso de pago.
          type: array
          items:
            $ref: '#/components/schemas/Taxes'
        details:
          description: |
            Estructura para definir detalles adicionales del monto en el proceso de pago.
          type: array
          items:
            $ref: '#/components/schemas/Details'
    NameValuePair:
      title: NameValuePair
      description: |
        Estructura para relacionar datos adicionales en el proceso.
      type: object
      properties:
        keyword:
          type: string
          minLength: 1
          maxLength: 50
          description: |
            Identificador o índice del dato a anexar.   
            EJ: `cmsInvoiceId`
          example: '1111'
        value:
          type:
            - string
            - object
            - array
            - number
            - boolean
          minLength: 1
          maxLength: 255
          description: |
            Valor del dato a anexar.   
            EJ: `ID_2233`
          example: lastDigits
        displayOn:
          type: enum
          description: |
            Indica en qué condiciones se muestra el dato anexo. Ver más en [Campos Adicionales](/checkout/additional-fields)

            Uno de: `none`, `payment`, `receipt`, `both`, `approved`.
          example: none
      examples:
        - value: '468232'
          keyword: merchantCode
          displayOn: none
        - value:
            code: '1'
            type: '03'
            groupCode: X
            installments: 3
          keyword: credit
          displayOn: none
        - value: 2056
          keyword: totalAmount
          displayOn: none
        - value: 685.33
          keyword: installmentAmount
          displayOn: none
    AutopayRecurring:
      title: AutopayRecurring
      type: object
      description: Requerido cuando `action` es `CREATE`, Indica las condiciones de recurrencia del autopago.
      required:
        - type
        - periodicity
        - interval
        - nextPayment
      properties:
        type:
          type: string
          description: |
            Corresponde al tipo de cobro que tendrá la recurrencia. Sólo se usa en sesiones de autopago.
            `FIXED`: El monto es fijo y fue definido desde la creación del autopago,
            `MINIMUM_BALANCE`: El monto minimo para mantener el la recurrencia activa, lo define un servicio externo,
            `TOTAL_BALANCE`: El total definido en el activo, lo define un servicio externo
          enum:
            - FIXED
            - MINIMUM_BALANCE
            - TOTAL_BALANCE
          example: TOTAL_BALANCE
        periodicity:
          $ref: '#/components/schemas/Recurring/properties/periodicity'
        interval:
          $ref: '#/components/schemas/Recurring/properties/interval'
        nextPayment:
          $ref: '#/components/schemas/Recurring/properties/nextPayment'
        dueDate:
          $ref: '#/components/schemas/Recurring/properties/dueDate'
      examples:
        - type: TOTAL_BALANCE
          periodicity: M
          interval: 1
          nextPayment: '2019-08-24'
          dueDate: '2019-09-24'
    AutopayRecurringResponse:
      title: AutopayRecurringResponse
      type: object
      description: Las condiciones del recurrencia del autopago.
      properties:
        type:
          $ref: '#/components/schemas/AutopayRecurring/properties/type'
        periodicity:
          $ref: '#/components/schemas/Recurring/properties/periodicity'
        interval:
          $ref: '#/components/schemas/Recurring/properties/interval'
        nextPayment:
          $ref: '#/components/schemas/Recurring/properties/nextPayment'
        dueDate:
          $ref: '#/components/schemas/Recurring/properties/dueDate'
        startDate:
          type: string
          format: date
          description: Fecha informativa de inicio de la recurrencia, formato AAAA-MM-DD. Sólo se usa en sesiones de autopago.
          example: '2019-08-24'
      examples:
        - type: TOTAL_BALANCE
          periodicity: M
          interval: 1
          nextPayment: '2019-08-24'
          dueDate: '2019-09-24'
          startDate: '2019-08-24'
    Recurring:
      title: Recurring
      type: object
      description: |
        Estructura para indicar la frecuencia de un cobro recurrente.
      required:
        - periodicity
        - interval
        - maxPeriods
      properties:
        periodicity:
          type: enum
          description: |
            Periodicidad del cobro. `D` día, `M` mes, `Y` año
          enum:
            - D
            - M
            - 'Y'
          example: D
        interval:
          type: integer
          min: 1
          description: |
            En combinación con `periodicity`, indica cada cuánto se realizará el cobro.
            EJ: Para 15 días, usar `interval: 15` `periodicity: "D"`.
          example: 15
        nextPayment:
          type: string
          description: Fecha del próximo pago
          format: date
          example: '2019-08-24'
        maxPeriods:
          type: number
          description: |
            Número máximo de periodos. Usar `-1` en caso de que no haya límite
          example: 12
          min: -1
        dueDate:
          type: string
          format: date
          description: |
            Fecha de vencimiento de la recurrencia   
            EJ: `2019-09-24`
          example: '2019-09-24'
        notificationUrl:
          type: string
          maxLength: 255
          format: uri
          description: URL en el que el servicio notificará cada vez que se haga un cobro
          example: https://merchant.example.com/notificationUrl
      examples:
        - periodicity: D
          interval: 1
          nextPayment: '2019-08-24'
          maxPeriods: 1
          dueDate: '2019-09-24'
          notificationUrl: https://merchant.example.com/notificationUrl
    Taxes:
      title: Taxes
      type: object
      description: |
        Estructura para definir información sobre un impuesto.
      examples:
        - kind: valueAddedTax
          amount: 1000
          base: 0
      properties:
        kind:
          type: enum
          description: |
            Identificador del tipo de impuesto

            Uno de: `valueAddedTax` `exciseDuty` `ice` `airportTax` `stateTax` `reducedStateTax` `municipalTax`.
          enum:
            - valueAddedTax
            - exciseDuty
            - ice
            - airportTax
            - stateTax
            - reducedStateTax
            - municipalTax
          example: valueAddedTax
        amount:
          type:
            - number
          description: |
            Monto total del impuesto   
            EJ: `200`
        base:
          type:
            - number
          description: |
            Monto base sobre el cual se calcula el impuesto   
            EJ: `1000`
    Details:
      title: Details
      type: object
      description: |
        Estructura para almacenar información sobre un detalle.
      x-internal: false
      examples:
        - kind: discount
          amount: 1000
      properties:
        kind:
          type: enum
          description: |
            Identificador del tipo de detalle. 
            Uno de:  `discount` `additional` `vatDevolutionBase` `shipping` `handlingFee` `insurance` `giftWrap` `subtotal` `fee` `tip` `airline` `interests`
          example: discount
          enum:
            - discount
            - additional
            - vatDevolutionBase
            - shipping
            - handlingFee
            - insurance
            - giftWrap
            - subtotal
            - fee
            - tip
            - airline
            - interests
        amount:
          type:
            - number
          description: |
            Monto total del detalle

            EJ: `200`
    SubscriptionRequest:
      title: SubscriptionRequest
      type: object
      description: |
        Cuando se envía, se genera una sesión de suscripción.

        El usuario registra un medio de pago para que luego el comercio pueda realizar cobros sobre ese medio de pago en demanada.
      properties:
        reference:
          $ref: '#/components/schemas/Reference'
        description:
          $ref: '#/components/schemas/Description'
        fields:
          $ref: '#/components/schemas/Fields'
    AutopayRequest:
      title: AutopayRequest
      type: object
      required:
        - action
        - reference
        - description
      description: |
        Detalle del autopago a generar. El usuario debe registrar un medio de pago para que se realicen cobros automáticos sobre ese medio de pago segun las condiciones pactadas. Es requerido cuando `type` es `autopay`.
      properties:
        action:
          type: enum
          description: |
            Indica la acción a realizar con el autopago.
            Uno de: `CREATE` para crear un autopago, `EDIT` para editar un autopago existente.
          enum:
            - CREATE
            - EDIT
          example: CREATE
        reference:
          $ref: '#/components/schemas/Reference'
        description:
          $ref: '#/components/schemas/Description'
        id:
          $ref: '#/components/schemas/AutopayId'
          description: Requerido cuando `action` es `EDIT`. Identificador del autopago existente.
        dueDay:
          $ref: '#/components/schemas/AutopayDueDay'
        recurring:
          $ref: '#/components/schemas/AutopayRecurring'
        amount:
          $ref: '#/components/schemas/Amount'
          description: Requerido cuando `recurring.type` es `FIXED`. Define el monto fijo a cobrar en cada recurrencia.
    AutopayId:
      type: string
      format: uuid
      description: Identificador del Autopago.
      example: f7b347d7-c922-4c68-8750-99fb43c9e5ff
    AutopayDueDay:
      type: integer
      minimum: 1
      maximum: 28
      description: |
        Para pagos recurrentes con periodicidad mensual, corresponde al día de corte del pago.
        Es un valor informativo para indicar al usuario el día máximo esperado para realizar el pago.
        Normalmente indica que los cobros despues de este día pueden tener recargos o no estar disponibles.    
        EJ: `15` para el día quince de cada mes.
      example: 15
    RedirectRequest:
      title: CreateSessionRequest
      type: object
      description: |
        Información para crear una sesión de WebCheckout.
      required:
        - auth
        - ipAddress
        - userAgent
        - returnUrl
      properties:
        auth:
          $ref: '#/components/schemas/Authentication'
        payment:
          $ref: '#/components/schemas/PaymentRequest'
        expiration:
          $ref: '#/components/schemas/Expiration'
        ipAddress:
          $ref: '#/components/schemas/IpAddress'
        userAgent:
          $ref: '#/components/schemas/UserAgent'
        returnUrl:
          $ref: '#/components/schemas/ReturnUrl'
        locale:
          $ref: '#/components/schemas/Locale'
        buyer:
          $ref: '#/components/schemas/Person'
          description: |
            Datos del usuario **comprador**, hace referencia al usuario que está comprando un producto o un servicio.

            **Cuando se crea una sesión**: Se puede enviar si conoces al usuario que está haciendo la compra, pues ayuda a completar la información de la sesión.   
            Si se envía este dato, el usuario tendrá sus datos personales pre-diligenciados y podrá cambiarlos en Checkout.
        payer:
          $ref: '#/components/schemas/Person'
          description: |
            Datos del usuario **pagador**, hace referencia al dueño del medio de pago o usuario que pagó el monto solicitado.

            **Cuando se crea una sesión**: Sólo se debe usar cuando quieres "forzar" los datos del usuario que completará el proceso.   
            Si se envía este dato, el usuario tendrá sus datos personales pre-diligenciados pero **no podrá cambiarlos**.
        subscription:
          $ref: '#/components/schemas/SubscriptionRequest'
        fields:
          $ref: '#/components/schemas/Fields'
        paymentMethod:
          type: enum
          description: |
            Se usa para restringir los métodos de pago disponibles en checkout.
            Se pueden enviar varios códigos separados por coma.
            Ver más en [Métodos de pago](/checkout/payment-methods)
          example: visa,master,pse
        cancelUrl:
          type: string
          format: uri
          maxLength: 255
          description: |
            URL de cancelación, a esta url se redirige al usuario cuando decide no continuar con el proceso.
            Ocurre cuando el usario da click en _No deseo continuar_
          example: https://commerce.test/cancel
        skipResult:
          type: boolean
          description: |
            Si se envía `true`, cuando el usuario finalice el proceso no se mostrará la página de resultado de sesión, en su lugar será redireccionado al `returnUrl`. Ver más en [Omitir resultado](/checkout/skip-result)
          default: false
        noBuyerFill:
          type: boolean
          description: |
            Por defecto los datos enviados como `buyer` se pre-diligencian en la interfaz de Checkout para agilizar el proceso de pago, si se envía este parámetro como `true` entonces no se hará este pre diligenciamiento.
          default: false
        type:
          type: enum
          description: |
            Parámetro usado para sesiones de tipos adicionales
            Usar `checkin` para generar una sesión de Preautorización.
            Usar `autopay` para generar una sesión de Autopago.
          enum:
            - checkin
            - autopay
          example: checkin
        metadata:
          $ref: '#/components/schemas/Metadata'
        autopay:
          $ref: '#/components/schemas/AutopayRequest'
      x-examples:
        Crear sesión básica:
          locale: es_CO
          payer:
            name: John
            surname: doe
            email: user_email@example.com
            documentType: CC
            document: '1036949824'
            mobile: '3102903560'
          payment:
            reference: '331122'
            description: Pago básico de ejemplo
            amount:
              currency: USD
              total: 100
            allowPartial: false
          expiration: '2021-06-31T00:00:00-05:00'
          returnUrl: https://mysite.com/response/3210
          ipAddress: 127.0.0.1
          userAgent: Placetopay Sandbox
        Crear sesión checkin:
          locale: es_CO
          type: checkin
          payer:
            name: John
            surname: doe
            email: user_email@example.com
            documentType: CC
            document: '1036949824'
            mobile: '3102903560'
          payment:
            reference: '331122'
            description: Pago básico de ejemplo
            amount:
              currency: USD
              total: 100
            allowPartial: false
          expiration: '2021-06-31T00:00:00-05:00'
          returnUrl: https://mysite.com/response/3210
          ipAddress: 127.0.0.1
          userAgent: Placetopay Sandbox
      x-internal: false
      examples:
        - locale: es_CO
          auth:
            login: aabbccdd1234567890aabbccdd123456
            tranKey: ABC123example456trankey+789abc012def3456ABC=
            nonce: NjE0OWVkODgwYjNhNw==
            seed: '2021-09-21T09:34:48-05:00'
          payer:
            document: '1122334455'
            documentType: CC
            name: John
            surname: Doe
            company: Evertec
            email: johndoe@app.com
            mobile: '+5731111111111'
            address:
              street: 123 Example Street, Sample City, ST 12345
              city: Medellín
              state: Poblado
              postalCode: '55555'
              country: CO
              phone: '+573111111111'
          buyer:
            document: '1122334455'
            documentType: CC
            name: John
            surname: Doe
            company: Evertec
            email: johndoe@app.com
            mobile: '+5731111111111'
            address:
              street: 123 Example Street, Sample City, ST 12345
              city: Medellín
              state: Poblado
              postalCode: '55555'
              country: CO
              phone: '+573111111111'
          payment:
            reference: '12345'
            description: Prueba de pago
            amount:
              currency: COP
              total: 2000
              taxes:
                - kind: valueAddedTax
                  amount: 1000
                  base: 0
              details:
                - kind: discount
                  amount: 1000
            allowPartial: false
            shipping:
              document: '1122334455'
              documentType: CC
              name: John
              surname: Doe
              company: Evertec
              email: johndoe@app.com
              mobile: '+5731111111111'
              address:
                street: 123 Example Street, Sample City, ST 12345
                city: Medellín
                state: Poblado
                postalCode: '55555'
                country: CO
                phone: '+573111111111'
            items:
              - sku: '12345'
                name: product_1
                category: physical
                qty: '1'
                price: 1000
                tax: 0
            fields:
              - keyword: _test_field_value_
                value: _test_field_
                displayOn: approved
            recurring:
              periodicity: D
              interval: '1'
              nextPayment: '2019-08-24'
              maxPeriods: 1
              'dueDate ': '2019-09-24'
              'notificationUrl ': https://checkout.placetopay.com
            subscribe: false
            dispersion:
              - agreement: '1299'
                agreementType: MERCHANT
                amount:
                  currency: USD
                  total: 200
            modifiers:
              - type: FEDERAL_GOVERNMENT
                code: 17934
                additional:
                  invoice: '123345'
          subscription:
            reference: '12345'
            description: Ejemplo de descripción
            fields:
              keyword: '1111'
              value: lastDigits
              displayOn: none
          fields:
            - keyword: _processUrl_
              value: https://checkout.redirection.test/session/1/a592098e22acc709ec7eb30fc0973060
              displayOn: none
          paymentMethod: visa
          expiration: '2019-08-24T14:15:22Z'
          returnUrl: https://commerce.test/return
          cancelUrl: https://commerce.test/cancel
          ipAddress: 127.0.0.1
          userAgent: Placetopay Sandbox
          skipResult: false
          noBuyerFill: false
          type: checkin
    Authentication:
      description: |
        La autenticación del sitio. Ver más en [Autenticación](/checkout/authentication)
      type: object
      title: Authentication
      examples:
        - auth:
            login: aabbccdd1234567890aabbccdd123456
            tranKey: ABC123example456trankey+789abc012def3456ABC=
            nonce: NjE0OWVkODgwYjNhNw==
            seed: '2021-09-21T09:34:48-05:00'
      properties:
        login:
          type: string
          minLength: 1
          maxLength: 32
          description: |
            Identificador del sitio.
        tranKey:
          type: string
          minLength: 1
          maxLength: 64
          description: |
            Credencial tranKey generado.   
            Ver más en [Autenticación](/checkout/authentication)
        nonce:
          type: string
          minLength: 1
          maxLength: 255
          description: |
            Valor aleatorio para cada solicitud codificado en Base64.
        seed:
          type: string
          minLength: 1
          maxLength: 35
          format: date-time
          description: |
            Fecha actual, la cual se genera en formato [ISO 8601](https://es.wikipedia.org/wiki/ISO_8601).
    Status:
      title: Status
      description: |
        Estructura que contiene el estado de una solicitud. Informa el estado actual de la sesión.
      type: object
      properties:
        status:
          type: enum
          description: Estado de una petición o pago
          example: APPROVED
          enum:
            - APPROVED
            - PENDING
            - PENDING_CONFIRMATION
            - REJECTED
            - APPROVED_PARTIAL
            - PARTIAL_EXPIRED
            - FAILED
        reason:
          type:
            - string
            - number
            - 'null'
          maxLength: 255
          description: |
            Código del motivo proporcionado.
          example: '00'
        message:
          type:
            - string
            - 'null'
          maxLength: 255
          description: |
            Descripción del código de razón.
          example: La petición ha sido aprobada exitosamente
        date:
          type: string
          maxLength: 35
          format: date-time
          description: |
            Fecha y hora en que se genera el estado de pago. Formato [ISO 8601](https://es.wikipedia.org/wiki/ISO_8601).
          example: '2022-07-27T14:51:27-05:00'
    Transaction:
      title: Transaction
      type: object
      description: |
        Estructura que contiene información sobre el proceso de pago de la transacción en Placetopay.
      examples:
        - status:
            status: APPROVED
            reason: '00'
            message: La petición ha sido aprobada exitosamente
            date: '2022-07-27T14:51:27-05:00'
          internalReference: 12345
          reference: '12345'
          paymentMethod: visa
          paymentMethodName: Visa
          issuerName: JPMORGAN CHASE BANK, N.A.
          amount:
            from:
              'currency ': COP
              'total ': 10000
            to:
              'currency ': COP
              'total ': 10000
            factor: 1
          receipt: '052617800175'
          franchise: PS_VS
          refunded: false
          authorization: '965960'
          processorFields:
            - keyword: '1111'
              value: lastDigits
              displayOn: none
            - value:
                code: '1'
                type: '03'
                groupCode: X
                installments: 3
              keyword: credit
              displayOn: none
            - value: 2056
              keyword: totalAmount
              displayOn: none
          dispersion: null
          agreement: null
          agreementType: null
          discount:
            base: 3000
            code: '17934'
            type: FRANCHISE
            amount: 1000
          subscription: null
      properties:
        status:
          $ref: '#/components/schemas/Status'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        reference:
          $ref: '#/components/schemas/Reference'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        paymentMethodName:
          $ref: '#/components/schemas/PaymentMethodName'
        issuerName:
          $ref: '#/components/schemas/IssuerName'
        amount:
          $ref: '#/components/schemas/AmountConversion'
        receipt:
          $ref: '#/components/schemas/Receipt'
        franchise:
          $ref: '#/components/schemas/Franchise'
        refunded:
          $ref: '#/components/schemas/Refunded'
        authorization:
          $ref: '#/components/schemas/Authorization'
        processorFields:
          $ref: '#/components/schemas/ProcessorFields'
        dispersion:
          $ref: '#/components/schemas/Dispersion'
        agreement:
          $ref: '#/components/schemas/Agreement'
        agreementType:
          $ref: '#/components/schemas/AgreementType'
        discount:
          $ref: '#/components/schemas/Discount'
    TransactionDispersion:
      title: Transaction Dispersion
      x-stoplight:
        id: sc9t9q5yfgeuj
      type: object
      description: |
        Estructura que contiene información sobre el proceso de la transacción dispersada.
      examples:
        - status:
            status: APPROVED
            reason: '00'
            message: La petición ha sido aprobada exitosamente
            date: '2022-07-27T14:51:27-05:00'
          agreement: null
          agreementType: null
          authorization: '965960'
          receipt: '052617800175'
          amount:
            from:
              'currency ': COP
              'total ': 10000
            to:
              'currency ': COP
              'total ': 10000
            factor: 1
          refunded: false
          paymentMethod: visa
      properties:
        status:
          $ref: '#/components/schemas/Status'
        agreement:
          $ref: '#/components/schemas/Agreement'
        agreementType:
          $ref: '#/components/schemas/AgreementType'
        authorization:
          $ref: '#/components/schemas/Authorization'
        receipt:
          $ref: '#/components/schemas/Receipt'
        amount:
          $ref: '#/components/schemas/AmountConversion'
        refunded:
          $ref: '#/components/schemas/Refunded'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
    Autopay:
      title: Autopay
      type: object
      description: |
        Autopago generado en proceso sesión de autopago.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        id:
          $ref: '#/components/schemas/AutopayId'
        siteId:
          type: integer
          description: Identificador del sitio donde se creó el autopago.
          example: 1234
        payer:
          $ref: '#/components/schemas/Person'
        buyer:
          $ref: '#/components/schemas/Person'
        subscription:
          type: object
          description: Estructura que contiene la información acerca de la suscripción asociada al AutoPago.
          properties:
            reference:
              $ref: '#/components/schemas/Reference'
            description:
              $ref: '#/components/schemas/Description'
            amount:
              $ref: '#/components/schemas/Amount'
            recurring:
              $ref: '#/components/schemas/AutopayRecurringResponse'
        instrument:
          type: object
          description: Estructura que contiene la información del medio de pago asociado al AutoPago.
          properties:
            token:
              $ref: '#/components/schemas/Token'
        additional:
          type: object
          description: Estructura que incluye datos adicionales del autopago.
          properties:
            dueDay:
              type: string
              $ref: '#/components/schemas/AutopayDueDay'
            customerAccountNumber:
              type: string
              description: Dato opcional enviado al iniciar el proceso de Autopago.
              example: '1234567890'
        acceptedAt:
          type: string
          format: date-time
          description: Fecha y hora en que se aceptó el autopago.
          example: '2021-09-24T10:02:17-05:00'
    AmountConversion:
      title: AmountConversion
      type: object
      description: |
        Estructura para definir el factor de conversión y los valores.
      properties:
        from:
          $ref: '#/components/schemas/AmountBase'
        to:
          $ref: '#/components/schemas/AmountBase'
        factor:
          type:
            - number
            - string
          minLength: 1
          maxLength: 20
          example: 1
          description: Factor de conversión
    AmountBase:
      title: AmountBase
      type: object
      description: |
        Estructura que representa una cantidad que define la moneda y el total.
      properties:
        'currency ':
          type: string
          minLength: 3
          maxLength: 3
          description: |
            Moneda acorde al [ISO 4217 alpha code](https://es.wikipedia.org/wiki/ISO_4217).
          example: COP
        'total ':
          type:
            - number
          description: |
            Valor total.
          example: 10000
    SubscriptionResponse:
      title: SubscriptionResponse
      type: object
      description: |
        Estructura que contiene información para el método de pago suscripción.
      examples:
        - status:
            status: OK
            reason: '00'
            message: La petición ha sido aprobada exitosamente
            date: '2022-07-27T14:51:27-05:00'
          type: token
          instrument:
            - keyword: token
              value: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
              displayOn: none
            - keyword: subtoken
              value: '8740257204881111'
              displayOn: none
            - keyword: franchise
              value: visa
              displayOn: none
            - keyword: franchiseName
              value: Visa
              displayOn: none
            - keyword: issuerName
              value: JPMORGAN CHASE BANK, N.A.
              displayOn: none
            - keyword: lastDigits
              value: '1111'
              displayOn: none
            - keyword: validUntil
              value: '2029-12-31'
              displayOn: none
            - keyword: installments
              value: null
              displayOn: none
      properties:
        status:
          $ref: '#/components/schemas/Status'
        type:
          type: enum
          description: Define tipo de suscripción que se devuelve
          example: token
          enum:
            - token
            - cuenta
        instrument:
          type: array
          items:
            $ref: '#/components/schemas/NameValuePair'
    RedirectInformation:
      title: RedirectInformation
      type: object
      description: |
        Estructura de respuesta a una solicitud para una información de transacción.
      properties:
        requestId:
          type:
            - number
            - integer
          example: 1
          description: Id de la petición
        status:
          $ref: '#/components/schemas/Status'
        request:
          $ref: '#/components/schemas/RedirectRequest'
        payment:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        subscription:
          $ref: '#/components/schemas/SubscriptionResponse'
        autopay:
          oneOf:
            - type: array
              title: array[Autopay]
              items:
                $ref: '#/components/schemas/Autopay'
            - type: 'null'
      examples:
        - requestId: 1
          status:
            status: APPROVED
            reason: '00'
            message: La petición ha sido aprobada exitosamente
            date: '2022-07-27T14:51:27-05:00'
          request:
            locale: es_CO
            payer:
              document: '1122334455'
              documentType: CC
              name: John
              surname: Doe
              company: Evertec
              email: johndoe@app.com
              mobile: '+5731111111111'
              address:
                street: 123 Example Street, Sample City, ST 12345
                city: Medellín
                state: Poblado
                postalCode: '55555'
                country: CO
                phone: '+573111111111'
            buyer:
              document: '1122334455'
              documentType: CC
              name: John
              surname: Doe
              company: Evertec
              email: johndoe@app.com
              mobile: '+5731111111111'
              address:
                street: 123 Example Street, Sample City, ST 12345
                city: Medellín
                state: Poblado
                postalCode: '55555'
                country: CO
                phone: '+573111111111'
            payment:
              reference: '12345'
              description: Prueba de pago
              amount:
                currency: COP
                total: 2000
                taxes:
                  - kind: valueAddedTax
                    amount: 1000
                    base: 0
                details:
                  - kind: discount
                    amount: 1000
              allowPartial: false
              shipping:
                document: '1122334455'
                documentType: CC
                name: John
                surname: Doe
                company: Evertec
                email: johndoe@app.com
                mobile: '+5731111111111'
                address:
                  street: 123 Example Street, Sample City, ST 12345
                  city: Medellín
                  state: Poblado
                  postalCode: '55555'
                  country: CO
                  phone: '+573111111111'
              items:
                - sku: '12345'
                  name: product_1
                  category: physical
                  qty: '1'
                  price: 1000
                  tax: 0
              fields:
                - keyword: _test_field_value_
                  value: _test_field_
                  displayOn: approved
              recurring:
                periodicity: D
                interval: '1'
                nextPayment: '2019-08-24'
                maxPeriods: 1
                'dueDate ': '2019-09-24'
                'notificationUrl ': https://checkout.placetopay.com
              subscribe: false
              dispersion:
                - agreement: '1299'
                  agreementType: MERCHANT
                  amount:
                    currency: USD
                    total: 200
              modifiers:
                - type: FEDERAL_GOVERNMENT
                  code: 17934
                  additional:
                    invoice: '123345'
            subscription:
              reference: '12345'
              description: Ejemplo de descripción
              fields:
                keyword: '1111'
                value: lastDigits
                displayOn: none
            fields:
              - keyword: _processUrl_
                value: https://checkout.redirection.test/session/1/a592098e22acc709ec7eb30fc0973060
                displayOn: none
            paymentMethod: visa
            expiration: '2019-08-24T14:15:22Z'
            returnUrl: https://commerce.test/return
            cancelUrl: https://commerce.test/cancel
            ipAddress: 127.0.0.1
            userAgent: Placetopay Sandbox
            skipResult: false
            noBuyerFill: false
            type: checkin
          payment:
            - status:
                status: APPROVED
                reason: '00'
                message: La petición ha sido aprobada exitosamente
                date: '2022-07-27T14:51:27-05:00'
              internalReference: 12345
              reference: '12345'
              paymentMethod: visa
              paymentMethodName: Visa
              issuerName: JPMORGAN CHASE BANK, N.A.
              amount:
                from:
                  'currency ': COP
                  'total ': 10000
                to:
                  'currency ': COP
                  'total ': 10000
                factor: 1
              receipt: '052617800175'
              franchise: PS_VS
              refunded: false
              authorization: '965960'
              processorFields:
                - keyword: '1111'
                  value: lastDigits
                  displayOn: none
              dispersion: null
              agreement: null
              agreementType: null
              discount:
                base: 3000
                code: '17934'
                type: FRANCHISE
                amount: 1000
              subscription: null
          subscription:
            status:
              status: OK
              reason: '00'
              message: La petición ha sido aprobada exitosamente
              date: '2022-07-27T14:51:27-05:00'
            type: token
            instrument:
              - keyword: token
                value: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                displayOn: none
              - keyword: subtoken
                value: '8740257204881111'
                displayOn: none
              - keyword: franchise
                value: visa
                displayOn: none
              - keyword: franchiseName
                value: Visa
                displayOn: none
              - keyword: issuerName
                value: JPMORGAN CHASE BANK, N.A.
                displayOn: none
              - keyword: lastDigits
                value: '1111'
                displayOn: none
              - keyword: validUntil
                value: '2029-12-31'
                displayOn: none
              - keyword: installments
                value: null
                displayOn: none
    CancelSessionRequest:
      title: CancelSessionRequest
      type: object
      description: Estructura de solicitud para cancelar una sesión.
      required:
        - auth
      properties:
        auth:
          $ref: '#/components/schemas/Authentication'
      examples:
        - auth:
            login: aabbccdd1234567890aabbccdd123456
            tranKey: ABC123example456trankey+789abc012def3456ABC=
            nonce: NjE0OWVkODgwYjNhNw==
            seed: '2021-09-21T09:34:48-05:00'
    CancelSessionResponse:
      title: CancelSessionResponse
      type: object
      description: |
        Estructura de respuesta a una solicitud de cancelar una sesión.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        session:
          $ref: '#/components/schemas/RedirectInformation'
      examples:
        - status:
            status: OK
            reason: '00'
            message: La petición se ha procesado correctamente
            date: '2025-07-11T14:05:44-05:00'
          session:
            requestId: 28
            status:
              status: REJECTED
              reason: MC
              message: La petición ha sido cancelada por el comercio
              date: '2025-07-11T14:05:44-05:00'
            request:
              locale: es_CO
              payer:
                document: '118877455'
                documentType: CC
                name: John
                surname: Doe
                email: Johny@Doe.com
                mobile: '+573111111111'
              payment:
                reference: 'Ord: 1001/2023'
                description: _pueba pagoEfectivo
                amount:
                  currency: USD
                  total: 20000
                allowPartial: false
                subscribe: false
                fields:
                  - keyword: _test_field_
                    value: _test_field_value_
                    displayOn: payment
              returnUrl: https://mysite.com/response/32120
              ipAddress: 127.0.0.1
              userAgent: Placetopay Sandbox
              expiration: '2025-07-11T19:25:39.497Z'
            payment: null
            subscription: null
    InstrumentCollect:
      title: Instrument-collect
      type: object
      description: |
        Estructura que contiene los detalles de un medio de pago suscrito.
      required:
        - token
      properties:
        token:
          $ref: '#/components/schemas/SimpleToken'
        pocket:
          type:
            - enum
          description: |
            Código de billetera. Aplica para Tarjetas en Uruguay

            Valores posibles:   
            `10` Cuenta de ahorros en UYU
            `20` Cuenta corriente en UYU
            `80` Cuenta de ahorros en USD
            `90` Cuenta corriente en USD
          example: '10'
          enum:
            - '10'
            - '20'
            - '80'
            - '90'
        credit:
          $ref: '#/components/schemas/Credit'
    InstrumentInvalidate:
      title: InstrumentInvalidate
      description: |
        Información del Token a invalidar.
      type:
        - object
      required:
        - token
      properties:
        token:
          description: |
            Información de un medio de pago "tokenizado". Se debe tokenizar con una sesión de suscripción.
            Debe contener el `token` o el `subtoken`, ambas representaciones válidas de un medio de pago tokenizado.
          type:
            - object
          properties:
            token:
              $ref: '#/components/schemas/InstrumentTokenToken'
            subtoken:
              $ref: '#/components/schemas/InstrumentTokenSubToken'
    InstrumentTokenToken:
      type: number
      maxLength: 64
      description: Representación del medio de pago.
      example: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
    InstrumentTokenSubToken:
      type: string
      maxLength: 16
      description: |
        Representación numérica del medio de pago. Se usa en casos donde es requerido que el token sea numérico.
        Los últimos 4 dígitos son iguales a los últimos 4 dígitos de la tarjeta de crédito.
      example: '8740257204881112'
    SimpleToken:
      title: SimpleToken
      type:
        - object
      description: |
        Información de un medio de pago "tokenizado". Se debe tokenizar con una sesión de suscripción.    
        Debe contener el `token` o el `subtoken`, ambas representaciones válidas de un medio de pago tokenizado.
      properties:
        token:
          $ref: '#/components/schemas/InstrumentTokenToken'
        subtoken:
          $ref: '#/components/schemas/InstrumentTokenSubToken'
        installments:
          type: integer
          description: Número de cuotas en las cuales se solicita el cobro. Aplica para Colombia.
          example: '`2` para 2 cuotas.'
        cvv:
          type: string
          minLength: 3
          maxLength: 4
          description: Código de seguridad de la tarjeta. Si el usuario está presente en el proceso de cobro, es recomendado anexar este dato..
          example: '123'
      examples:
        - token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
          subtoken: fakesubtoken00005
          installments: null
          cvv: '123'
    CollectRequest:
      title: CollectRequest
      type: object
      description: |
        Permite realizar cobros sin la intervención del usuario usando medios de pago previamente suscritos.
      required:
        - auth
        - payment
        - instrument
        - ipAddress
        - userAgent
        - payer
      properties:
        auth:
          $ref: '#/components/schemas/Authentication'
        payment:
          $ref: '#/components/schemas/PaymentRequest'
        instrument:
          $ref: '#/components/schemas/InstrumentCollect'
        ipAddress:
          $ref: '#/components/schemas/IpAddress'
        userAgent:
          $ref: '#/components/schemas/UserAgent'
        payer:
          $ref: '#/components/schemas/Person'
          description: |
            Datos del usuario **pagador**, hace referencia al dueño del medio de pago o usuario que pagó el monto solicitado.
        buyer:
          $ref: '#/components/schemas/Person'
          description: |
            Datos del usuario **comprador**, hace referencia al usuario que está comprando un producto o un servicio.
        locale:
          $ref: '#/components/schemas/Locale'
        type:
          type: string
          description: |
            Parámetro usado para sesiones de tipo preauthorización

            Sólo se soporta `checkin` para generar una sesión de preautorización
          enum:
            - checkin
        metadata:
          $ref: '#/components/schemas/Metadata'
        provider:
          type: string
          description: Código del proveedor de la transacción
    TransactionActionRequest:
      title: TransactionActionRequest
      type: object
      description: Estructura que permite realizar solicitudes de preauthorización como `checkout`, `reauthorization`, `reverse`, `confirm` y `cancel`
      x-examples:
        checkout example:
          internalReference: 1
          amount:
            currency: USD
            total: 100
          action: checkout
        reauthorization example:
          internalReference: 1
          amount:
            currency: USD
            total: 100
          action: reauthorization
        reverse example:
          internalReference: 1
          action: reverse
        confirm example:
          internalReference: 1
          action: confirm
        cancel example:
          internalReference: 1
          action: cancel
      examples: []
      required:
        - auth
        - internalReference
        - action
      properties:
        auth:
          $ref: '#/components/schemas/Authentication'
        action:
          type:
            - enum
          description: |
            Tipo de operación a realizar sobre la transacción

            `reverse` para reembolsar una transacción.
            `reauthorization` para modificar una transacción de checkin.
            `checkout` para cerrar y cobrar una transacción de checkin.
            `confirm` para confirmar una transacción en estado PENDING_CONFIRMATION.
            `cancel` para cancelar una transacción en estado PENDING_CONFIRMATION.
          enum:
            - checkout
            - reauthorization
            - reverse
            - confirm
            - cancel
          example: checkout
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        amount:
          $ref: '#/components/schemas/Amount'
    DispersionDetail:
      title: DispersionDetail
      type: object
      description: Estructura que refleja la información de los detalles para pago con dispersión.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
          description: |
            Monto a "dispersar" en este destino.
        agreement:
          nullable: true
          type:
            - number
          description: |
            Id del destino de este monto. Puede ser el id de un sitio.
            EJ: `122`
        agreementType:
          type: enum
          description: |
            Tipo de destino de este monto.   
            `MERCHANT` para sitios, `AIRLINE` para aerolineas.
          enum:
            - MERCHANT
            - AIRLINE
          example: MERCHANT
      examples:
        - agreement: '1299'
          agreementType: MERCHANT
          amount:
            currency: USD
            total: 200
    Modifiers:
      title: Modifiers
      type: object
      description: |
        Estructura para modificaciones adicionales en el cobro.

        Aplica para leyes de impuestos en paises especificos.
      properties:
        type:
          type: enum
          description: |
            Identificador del tipo de modificador.  
            Sólo `FEDERAL_GOVERMENT` es soportado actualmente.
          example: FEDERAL_GOVERNMENT
          enum:
            - FEDERAL_GOVERNMENT
        code:
          type:
            - number
          description: |
            Código del modificador. 

            Para `FEDERAL_GOVERMENT` representa el número de ley para descuento.   
            `17934` Servicios Gastronómicos   
            `18083` IMESI Brasil - Argentina   
            `19210` Inclusión Financiera   
            `18910` Asignaciones Familiares   
            `18999` Reintegro Inmobiliarias
          enum:
            - 17934
            - 18083
            - 19210
            - 18910
            - 18999
          example: 17934
        additional:
          type: object
          description: |
            Estructura para anexar información al modificador
          properties:
            invoice:
              type: string
              description: |
                Requerido cuando `modifiers.[n].type` es `FEDERAL_GOVERMENT`. Indica el número de factura.
              maxLength: 9
              example: '123456789'
      examples:
        - type: FEDERAL_GOVERNMENT
          code: 17934
          additional:
            invoice: '123345'
    Locale:
      x-stoplight:
        id: 0eakadh5w5h34
      type: string
      maxLength: 5
      format: regex
      pattern: ^\w{2}\_[A-Z]{2}
      example: en_US, es_CO
      description: Idioma en el que se tratará la petición y la sesión. Ver más en [Localización](/checkout/localization)
    Reference:
      title: Reference
      type: string
      minLength: 1
      maxLength: 32
      description: |
        Referencia única del proceso. Máximo de 32 caracteres
      example: PAYMENT_0001_ABC
    Description:
      title: Description
      type: string
      minLength: 1
      maxLength: 255
      description: |
        Descripción del proceso a realizar
      example: Consumo mes de Mayo
    InternalReference:
      type: integer
      description: Referencia interna única de la transacción
      example: 543423
    PaymentMethod:
      type: string
      description: Código del método de pago utilizado.
      minLength: 1
      maxLength: 255
      example: visa
    PaymentMethodName:
      type: string
      description: Nombre del método de pago utilizado.
      minLength: 1
      maxLength: 255
      example: Visa
    IssuerName:
      type: string
      description: Nombre del emisor o del procesador.
      minLength: 1
      maxLength: 255
      example: JPMORGAN CHASE BANK, N.A.
    Receipt:
      type: string
      minLength: 1
      maxLength: 255
      description: Numero de recibo de la transacción.
      example: '052617800175'
    Franchise:
      type: string
      minLength: 1
      maxLength: 5
      description: Franquicia de la tarjeta utilizada.
      example: PS_VS
    Refunded:
      type: boolean
      description: Se utiliza para definir si la transacción ha sido reembolsada
      default: false
    Authorization:
      type: string
      minLength: 1
      maxLength: 255
      description: Código de autorización.
      example: '965960'
    ProcessorFields:
      type: array
      description: Estructura que  puede variar en el tiempo según la información disponible para el medio de pago.  Ver más en [Datos de procesamiento](/checkout/processor-fields)
      items:
        $ref: '#/components/schemas/NameValuePair'
    Dispersion:
      type: array - 'null'
      description: Estructura que contiene información de dispersión
      items:
        $ref: '#/components/schemas/TransactionDispersion'
    Agreement:
      type:
        - integer
        - 'null'
        - number
      description: Identificador de destinatario de la transacción. Para el sitio principal de la transacción.
      example: 186
    AgreementType:
      type:
        - enum
        - 'null'
      description: Tipo de dispersión
      enum:
        - MERCHANT
        - AIRLINE
      example: MERCHANT
    Discount:
      type:
        - object
        - 'null'
      properties:
        base:
          type: number
          example: 3000
        code:
          type: string
          minLength: 1
          maxLength: 255
          example: '17934'
        type:
          type: string
          example: FRANCHISE
        amount:
          type: number
          example: 1000
    Expiration:
      type:
        - string
      minLength: 1
      maxLength: 35
      format: date-time
      example: '2024-09-03T12:23:39-05:00'
      description: |
        Fecha de expiración de una sesión. El usuario debe terminar el proceso antes de esta fecha.
        El tiempo de expiración debe ser de al menos 5 minutos desde el momento de la creación. Ver más en [Fecha de expiración](/checkout/expiration)
    IpAddress:
      type: string
      maxLength: 46
      description: Dirección IP del usuario que realizará el proceso.
      example: 134.10.163.36
    UserAgent:
      type: string
      maxLength: 255
      description: User Agent del navegador del usuario que realizará el proceso.
      example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
    ReturnUrl:
      type: string
      format: uri
      maxLength: 255
      description: |
        URL de retorno, a esta url se redirige al usuario una vez termina la sesión.
        Ocurre cuando el usuario da click en _Volver al comercio_.
      example: https://commerce.test/return
    PaymentResponse:
      title: PaymentResponse
      x-stoplight:
        id: etrozxrn4d2l6
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
          x-stoplight:
            id: gp6oc3txinq6a
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        paymentMethodName:
          $ref: '#/components/schemas/PaymentMethodName'
        issuerName:
          $ref: '#/components/schemas/IssuerName'
        amount:
          $ref: '#/components/schemas/AmountConversion'
        authorization:
          $ref: '#/components/schemas/Authorization'
        reference:
          $ref: '#/components/schemas/Reference'
        franchise:
          $ref: '#/components/schemas/Franchise'
        refunded:
          $ref: '#/components/schemas/Refunded'
        processorFields:
          $ref: '#/components/schemas/ProcessorFields'
        receipt:
          $ref: '#/components/schemas/Receipt'
      examples:
        - status:
            status: APPROVED
            reason: '00'
            message: Aprobada
            date: '2023-06-28T09:19:01-05:00'
          internalReference: '384912'
          paymentMethod: visa
          paymentMethodName: Visa
          issuerName: JPMORGAN CHASE BANK, N.A.
          amount:
            from:
              currency: USD
              total: 52
            to:
              currency: USD
              total: 52
            factor: 1
          authorization: '000000'
          reference: TEST_20230628_091643
          franchise: ID_VS
          refunded: false
          processorFields:
            - keyword: merchantCode
              value: '1465675'
              displayOn: none
            - keyword: terminalNumber
              value: '00990099'
              displayOn: none
            - keyword: credit
              value:
                code: '1'
                type: '00'
                groupCode: C
                installments: 1
              displayOn: none
            - keyword: totalAmount
              value: 52
              displayOn: none
            - keyword: interestAmount
              value: 0
              displayOn: none
            - keyword: installmentAmount
              value: 0
              displayOn: none
            - keyword: iceAmount
              value: 0
              displayOn: none
            - keyword: bin
              value: '411111'
              displayOn: none
            - keyword: expiration
              value: '1223'
              displayOn: none
            - keyword: lastDigits
              value: '1111'
              displayOn: none
            - keyword: id
              value: a10fe0690cfe557283310ba90746e159
              displayOn: none
            - keyword: b24
              value: '00'
              displayOn: none
    processFields:
      title: PaymentResponse
      x-stoplight:
        id: j80i0wo5z453m
      type: object
      properties:
        keyword:
          x-stoplight:
            id: gp6oc3txinq6a
          type: string
        value:
          type:
            - string
            - object
            - integer
            - array
          x-stoplight:
            id: 9069vdtfnw3nn
        displayOn:
          type: string
          x-stoplight:
            id: rrubobhx7er11
      examples:
        - keyword: string
          value: string
          displayOn: string
    Fields:
      type: array
      description: |
        Estructura para relacionar información adicional en el proceso. Ver más en [Campos Adicionales](/checkout/additional-fields)
      items:
        type: object
        $ref: '#/components/schemas/NameValuePair'
    CollectResponse:
      title: CollectResponse
      type: object
      properties:
        requestId:
          type: integer
        status:
          $ref: '#/components/schemas/Status'
        request:
          title: request
          type: object
          properties:
            locale:
              $ref: '#/components/schemas/Locale'
            payer:
              $ref: '#/components/schemas/Person'
            payment:
              $ref: '#/components/schemas/PaymentRequest'
            returnUrl:
              $ref: '#/components/schemas/ReturnUrl'
            ipAddress:
              $ref: '#/components/schemas/IpAddress'
            userAgent:
              $ref: '#/components/schemas/UserAgent'
            expiration:
              $ref: '#/components/schemas/Expiration'
        payment:
          $ref: '#/components/schemas/PaymentResponse'
        subscription:
          $ref: '#/components/schemas/SubscriptionResponse'
    CardType:
      title: CardType
      x-stoplight:
        id: x4y03rkspgz0b
      type: enum
      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
          minLength: 1
          maxLength: 4
          description: Código de la entidad bancaria
        description:
          type: string
          minLength: 1
          maxLength: 255
          description: Nombre de la entidad bancaria
    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
    Credit:
      title: Credit
      type: object
      description: Estructura que contiene la información del tipo de crédito. Ver más en [Créditos](/gateway/additional-data/#additional-data-credit)
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 6
        type:
          type: string
          minLength: 1
          maxLength: 2
        groupCode:
          type: string
          maxLength: 1
        installment:
          type: integer
        description:
          type: string
          minLength: 1
          maxLength: 255
    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:
          $ref: '#/components/schemas/ThreeDS'
        otp:
          type: string
          maxLength: 64
        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
          maxLength: 5
          pattern: ^[01]\d\/\d{2}$
        cvv:
          minLength: 3
          maxLength: 4
          type: string
        installments:
          type: number
      required:
        - 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.
    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:
        token:
          type: string
          maxLength: '64'
          minLength: '64'
          description: Código generado para identificar la tarjeta en el sistema
          example: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
        subtoken:
          type: string
          maxLength: '16'
          minLength: '16'
          description: Código alterno generado para identificar la tarjeta
          example: '8740257204881112'
        franchise:
          type: string
          minLength: 1
          maxLength: 20
          description: Codigo de la franquicia asociada al token (Solo como respuesta no es necesario enviarla)
          example: '`visa`, `visa_electron`, `master`, `diners`'
        franchiseName:
          type: string
          minLength: 1
          maxLength: 20
          example: '`Visa`,`Master`, `diners`'
        issuerName:
          $ref: '#/components/schemas/IssuerName'
        lastDigits:
          type: string
          maxLength: 4
          example: '1111'
        validUntil:
          type: string
          minLength: 1
          maxLength: 10
          format: date
          description: Fecha de expiración de la tarjeta
          example: 12/37
        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'
    ThreeDS:
      type: object
      x-examples:
        example-1:
          id: '1'
          enrolled: 'Y'
          authenticated: 'Y'
          validSignature: 'true'
          eci: '05'
          cavv: AAACCZJiUGVlF4U5AmJQEwAAAAA=
          xid: Z8UuHYF8Epz46M8V/MkGJDl2Y5E=
          version: v1
      properties:
        id:
          type: number
          description: Este valor solo aplica si la validación se hizo con el servicio de 3DS de Placetopay
        enrolled:
          type: enum
          enum:
            - 'Y'
            - 'N'
            - U
          description: Informa si la tarjeta se encuentra registrada en 3DS
        authenticated:
          type: enum
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - I
            - C
            - D
            - R
        validSignature:
          type: boolean
        eci:
          type: enum
          enum:
            - '02'
            - '01'
            - '00'
            - '05'
            - '06'
            - '07'
        cavv:
          type: string
          minLength: 1
          nullable: true
        xid:
          type: string
          minLength: 1
        version:
          type: enum
          minLength: 1
          enum:
            - v1
            - v2
            - v2x
        extra:
          type: object
          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
          maxLength: 36
          format: uuid
        positions:
          type: string
          maxLength: 10
        pinBlock:
          type: string
          maxLength: 16
        length:
          type: integer
    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: enum
          enum:
            - _PSE_
            - BTNBC
            - PGEFT
            - 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 (cuando aplica)
        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
    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
          minLength: 1
          maxLength: 250
          description: Identificador de esta operación en Kount, debe ser único por transacción
        type:
          type: enum
          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
    Address:
      title: address
      type: object
      description: Estructura para anexar información del domicilio o dirección
      properties:
        country:
          type: string
          description: El país en el que se encuentra la dirección. Código [ISO 3166-1 alpha-2](https://es.wikipedia.org/wiki/ISO_3166-1_alpha-2).
          minLength: 2
          maxLength: 2
          example: CO
        state:
          type: string
          maxLength: 3
          description: Estado/provincia/departamento. Código [ISO 3166-2](https://es.wikipedia.org/wiki/ISO_3166-2)
          example: ANT
        city:
          type: string
          maxLength: 30
          description: Ciudad del domicilio
          example: Medellín
        postalCode:
          type: string
          maxLength: 10
          description: Código postal del domicilio.
          example: '55555'
        street:
          type: string
          minLength: 1
          maxLength: 128
          description: Dirección del domicilio
          example: 'Calle 12 #33a-12, Apto 101'
        phone:
          type: string
          maxLength: 20
          description: Número telefónico del domicilio
          example: '+573111111111'
    Metadata:
      title: metadata
      type: object
      description: Estructura de tipo clave-valor que se utiliza para enviar información adicional y determinar comportamientos específicos durante el procesamiento de una sesión.
      properties:
        initiatorIndicator:
          type: string
          enum:
            - AGENT
            - CARDHOLDER_COF
            - CARDHOLDER_RECURRING_VARIABLE_AMOUNT
            - CARDHOLDER_RECURRING_FIXED_AMOUNT
            - CARDHOLDER_WITH_INSTALLMENTS
            - MERCHANT_COF
            - MERCHANT_RECURRING_VARIABLE_AMOUNT
            - MERCHANT_RECURRING_FIXED_AMOUNT
            - MERCHANT_WITH_INSTALLMENTS
          description: Indica que la sesión sera procesada por un agente con los datos del tarjetahabiente
        EBTDeliveryIndicator:
          type: string
          enum:
            - DIRECT_DELIVERY
            - CUSTOMER_PICKUP
            - COMMERCIAL_SHIPPING
            - OTHER
            - NOT_AVAILABLE
          description: '(Requerido para pagos con EBT): Define el tipo de entrega'
        openingDate:
          type: string
          description: 'Fecha de creación de la cuenta (formato: ''YYYY-MM-DD''). Requerida para PSE en comercios con categoría “Servicios Financieros.'
        beneficiaryId:
          type: string
          description: ID del beneficiario asociado a la cuenta receptora en una transacción PSE. Requerido para comercios con categoría “Servicios Financieros
        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 del comercio previo a su procesamiento final.
            Cuando se establece en `true`, la transacción se creará en estado PENDING_CONFIRMATION
            y el comercio deberá llamar a confirm o cancel mediante el endpoint de acciones de transacción.
          example: true
  securitySchemes: {}
  responses:
    StatusResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/Status'
            required:
              - status
          examples:
            APPROVED:
              value:
                status:
                  status: APPROVED
                  reason: '00'
                  message: La petición ha sido aprobada exitosamente
                  date: '2022-07-27T14:51:27-05:00'
            OK:
              value:
                status:
                  status: OK
                  reason: '00'
                  message: La petición ha sido aprobada exitosamente
                  date: '2022-07-27T14:51:27-05:00'
            FAILED:
              value:
                status:
                  status: FAILED
                  reason: XN
                  message: El token usado es inválido
                  date: '2022-07-27T14:51:27-05:00'
    GatewayInformationResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/Status'
              provider:
                type: string
                minLength: 1
                maxLength: 20
                example: EBUS
                description: Indicates which provider will be used in the transaction
              serviceCode:
                type: string
                minLength: 1
                maxLength: 5
                description: Indicates the code of the service that will process the transaction
                example: EB_VS
              cardTypes:
                type: array
                description: Indicates the card types supported by the provider
                items:
                  $ref: '#/components/schemas/CardType'
              cardType:
                $ref: '#/components/schemas/CardType'
              requiereOtp:
                type: boolean
                description: Indicates if it is necessary to perform the OTP flow
              requiereCvv2:
                type: boolean
                description: Indicates whether it is required to send CVV for transaction processing
              threeDS:
                type: string
                enum:
                  - optional
                  - required
                  - unsupported
                description: Indicates if 3DS is necessary
              credits:
                type: array
                description: Indicates the credits available per supplier
                items:
                  $ref: '#/components/schemas/Credit'
              requirePockets:
                type: boolean
                description: Indicates if a pocket is required for processing the transaction
              pockets:
                type: array
                description: Structure containing the card pockets
                items:
                  $ref: '#/components/schemas/Pocket'
              requireAvs:
                type: boolean
                description: Indicates whether zip code information is required
              zipCodeFormat:
                type: string
                description: Format to be used for postal code validation
                nullable: 'true'
              accountVerification:
                type: boolean
                description: Indicates whether it is necessary to perform the account verification flow
              requirePin:
                type: boolean
                description: Indicates if a pin is necessary to process the transaction
              requireRedirection:
                type: boolean
                description: Indicates if the payment method is of the redirect type
              bankList:
                type: array
                description: List of banks available to process a payment with PSE
                items:
                  $ref: '#/components/schemas/BankItem'
            required:
              - status
              - provider
              - serviceCode
          examples:
            Ejemplo:
              value:
                status:
                  status: OK
                  reason: '00'
                  message: The request has been processed successfully
                  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
                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'
    GatewayTokenResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/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: enum
                    description: Tipo de tokenización.
                    enum:
                      - card
                      - account
                  token:
                    $ref: '#/components/schemas/InstrumentTokenToken'
                  subtoken:
                    $ref: '#/components/schemas/InstrumentTokenSubToken'
                  franchise:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: Franquicia de la tarjeta utilizada.
                    example: visa
                  franchiseName:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: Nombre de la franquicia de la tarjeta.
                    example: Visa
                  issuerName:
                    $ref: '#/components/schemas/IssuerName'
                  lastDigits:
                    type: string
                    nullable: true
                    minLength: 1
                    maxLength: 4
                    description: Últimos dígitos de la tarjeta
                  validUntil:
                    type: string
                    minLength: 1
                    maxLength: 10
                    format: date
                    description: Fecha de expiración de la tarjeta
                    example: 12/37
                  owner:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: John Doe
                    description: Nombre del propietario de la tarjeta
                  bin:
                    type: string
                    example: '411111'
                    description: Primeros 6 dígitos de la tarjeta
                  accountType:
                    type: string
                    enum:
                      - SAV
                      - DDA
                      - CCD
                    description: Tipo de cuenta ACH, aplica solo para Puerto Rico
          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
  requestBodies:
    MerchantNotificationRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - requestId
              - reference
              - signature
            properties:
              status:
                $ref: '#/components/schemas/Status'
              requestId:
                type: integer
                description: |
                  Identificador único de la sesión asignado por Placetopay.
              reference:
                type: string
                description: Referencia asignada a la sesión por el comercio.
              signature:
                type: string
                description: Firma del mensaje, debe validarse en el servidor del comercio.
    InstrumentInvalidateRequest:
      content:
        application/json:
          schema:
            type:
              - object
            required:
              - auth
              - instrument
            properties:
              auth:
                $ref: '#/components/schemas/Authentication'
              instrument:
                $ref: '#/components/schemas/InstrumentInvalidate'
              locale:
                $ref: '#/components/schemas/Locale'
          examples:
            Using Token:
              value:
                auth:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                locale: en_US
                instrument:
                  token:
                    token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
            Using Subtoken:
              value:
                auth:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                locale: en_US
                instrument:
                  token:
                    subtoken: fakesubtoken00005
      description: Instrument Invalidate Request
    GatewayInformationRequest:
      content:
        application/json:
          schema:
            type:
              - object
            required:
              - auth
              - instrument
            properties:
              auth:
                $ref: '#/components/schemas/Authentication'
              locale:
                $ref: '#/components/schemas/Locale'
              instrument:
                $ref: '#/components/schemas/Instrument'
    GatewayTokenRequest:
      content:
        application/json:
          schema:
            type:
              - object
            required:
              - auth
              - instrument
            properties:
              auth:
                $ref: '#/components/schemas/Authentication'
              locale:
                $ref: '#/components/schemas/Locale'
              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:
                  token:
                    $ref: '#/components/schemas/InstrumentTokenToken'
                  subtoken:
                    $ref: '#/components/schemas/InstrumentTokenSubToken'
