openapi: 3.1.0
info:
  title: Placetopay WebCheckout
  version: '1.0'
  description: |
    WebCheckout is a pre-designed, optimized web page hosted at Placetopay that allows you to accept online payments quickly and securely from mobile and desktop devices. You can accept single payments, recurring payments, mixed payments and subscribe payment methods.

    Webcheckout allows you to:

    * **Custom design:** Customize your company's names, logos and colors.
    * **Different languages and currencies:** Accept payments in multiple languages and currencies.
    * **Adapted to different resolutions:** Responsive design for different devices.
    * **Placetopay Wallet:** WebCheckout has its own wallet that allows users to save frequent payment methods, providing greater security and ease in the payment process.
    * **Information security:** PCI guidelines that guarantee security in capturing and processing sensitive card information.
    * **Advanced payments:** Payments with taxes, mixed payments, subscriptions, recurring charges, promotions and more...

    <!-- theme: info -->
    > #### About HTTPS
    >
    > To use this service, your system must support communication with version 1.2 of the TLS protocol.
  contact:
    url: https://www.evertecinc.com/pasarela-de-pagos-e-commerce/
    name: Placetopay by Evertec
  summary: Use WebCheckout to accept online payments simply and securely
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: Production (CO, PR, CR, PA)
  - url: https://checkout.placetopay.ec
    description: Production (EC)
paths:
  /api/session:
    post:
      summary: Create session (CreateRequest)
      operationId: post-api-session
      description: Requests the creation of the session returns the identifier and the processing URL.
      x-internal: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedirectRequest'
            examples:
              Create simple session:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Test
                    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
              'Create preauthorization session ':
                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: Test
                    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
              Create session with mixed payment:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Test
                    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
              Create session with taxes:
                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
              Create session with disbursement:
                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
              Create subscription session:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  subscription:
                    reference: '331122'
                    description: A trial subscription
                  expiration: '2021-12-31T00:00:00-05:00'
                  returnUrl: https://dnetix.co/p2p/client
                  ipAddress: 127.0.0.1
                  userAgent: Placetopay Sandbox
              Create session with recurrence:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Recurring payment
                    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
              Create session with modifiers:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '331122'
                    description: Payment with modifiers
                    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
              Create session with details:
                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
              Create session with payment and subscription:
                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: Payment and subscription test
                    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: The request has been processed successfully
                      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: Authentication failed 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: Query session (getSessionInformation)
      operationId: post-api-session-requestId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedirectInformation'
              examples:
                Approved:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED
                      reason: '00'
                      message: The petition has been successfully approved
                      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: Test
                        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: Approved
                          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
                Pending:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: The request is pending
                      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: Test
                        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
                Rejected:
                  value:
                    requestId: 1
                    status:
                      status: REJECTED
                      reason: XN
                      message: The request has been rejected
                      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: Payment aborted by the user
                              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
                Partially expired:
                  value:
                    requestId: 1
                    status:
                      status: PARTIAL_EXPIRED
                      reason: PX
                      message: The request is expired or cancelled and payments have been made
                      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: Declined, Amount exceeds the maximum defined by the Financial Entity in the Cardholder file
                        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: Approved
                            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: Declined, Amount exceeds the maximum defined by the Financial Entity in the Cardholder file
                            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
                Partially approved:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED_PARTIAL
                      reason: P0
                      message: The request is partially approved
                      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: Cuenca Municipal GAD payment
                        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: Approved
                        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
                Pending Confirmation:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: The petition is pending
                      date: '2025-01-21T21:20:07-05:00'
                    request:
                      locale: es_CO
                      payment:
                        reference: TEST_VISA
                        description: Test payment
                        amount:
                          currency: USD
                          total: 100
                      metadata:
                        requiresConfirmation: true
                      returnUrl: https://merchant.com/return
                      ipAddress: 127.0.0.1
                      userAgent: Placetopay Sandbox
                      expiration: '2026-12-30T00:00:00-05:00'
                    payment:
                      - status:
                          status: PENDING_CONFIRMATION
                          reason: PT
                          message: Pending confirmation transaction
                          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: |
        Gets the session information; if the session has transactions, their details are shown.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
              properties:
                auth:
                  $ref: '#/components/schemas/Authentication'
            examples:
              Example:
                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: Identifier of the session to be cancelled
    post:
      summary: Cancel session
      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: An unexpected error occurred and the operation could not be completed.
          $ref: '#/components/responses/StatusResponse'
  /api/notify:
    post:
      summary: Notify Payment
      operationId: post-api-notify
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/components/schemas/Authentication'
                internalReference:
                  type:
                    - string
                    - number
                    - integer
                  description: |
                    Internal reference of the transaction to refund, found in the transaction list of getRequestInformation (payment).
                reference:
                  type: string
                  description: Payment reference
                signature:
                  type: string
                  description: Signature of the transaction stored in core
            examples:
              Example:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 1
                  reference: '12345'
                  signature: 3ccbae73d6a5bb1be7e00f9a2cfc3cc7cd95a311
      description: Allows requesting the status change of a transaction that is in pending status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                Approved:
                  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:
                Invalid signature:
                  value:
                    status:
                      status: FAILED
                      reason: 0
                      message: Invalid signature
                      date: '2021-12-07T16:24:20-05:00'
      x-internal: true
    parameters: []
  /api/collect:
    post:
      summary: Collect using token (Collect)
      operationId: post-api-collect
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectResponse'
              examples:
                Approved:
                  value:
                    requestId: 1
                    status:
                      status: APPROVED
                      reason: '00'
                      message: The petition has been successfully approved
                      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: Test
                        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: Approved
                          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
                Pending:
                  value:
                    requestId: 1
                    status:
                      status: PENDING
                      reason: PT
                      message: The request is pending
                      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: Test
                        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
                Rejected:
                  value:
                    requestId: 1
                    status:
                      status: REJECTED
                      reason: XN
                      message: The request has been rejected
                      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:
              Simple token charge:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Test
                    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
              Token charge to a preauthorization:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Test
                    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
              Charge with card pocket:
                value:
                  locale: es_CO
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1122334455'
                    description: Test
                    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: |
        Allows making charges without user intervention using previously subscribed payment methods.
      x-internal: false
  /api/transaction:
    post:
      summary: Transaction actions (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: Approved
                      date: '2021-11-30T09:36:00-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Approved
                        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: Approved
                      date: '2021-11-30T09:26:50-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Approved
                        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: Approved
                      date: '2021-11-30T09:37:46-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Approved
                        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
                Confirm:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Approved
                      date: '2025-01-21T21:20:07-05:00'
                    payment:
                      status:
                        status: APPROVED
                        reason: '00'
                        message: Approved
                        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
                Cancel:
                  value:
                    status:
                      status: REJECTED
                      reason: '?C'
                      message: Cancelled by the merchant
                      date: '2025-01-21T21:20:07-05:00'
                    payment:
                      status:
                        status: REJECTED
                        reason: '?C'
                        message: Cancelled by the merchant
                        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: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
              examples:
                SessionNotSupported:
                  value:
                    status:
                      status: FAILED
                      reason: request_not_valid
                      message: The [confirm] action is not supported for this session
                      date: '2025-01-21T21:20:07-05:00'
                InvalidTransactionState:
                  value:
                    status:
                      status: FAILED
                      reason: request_not_valid
                      message: The [confirm] action is only available for transactions in a pending confirmation state
                      date: '2025-01-21T21:20:07-05:00'
                ServiceUnavailable:
                  value:
                    status:
                      status: FAILED
                      reason: transaction_request_error
                      message: The transaction has already expired
                      date: '2025-01-21T21:20:07-05:00'
      description: Allows performing basic preauthorization operations such as `checkout`, `reauthorization` (not applicable in Puerto Rico). It also allows confirming (`confirm`) or canceling (`cancel`) transactions in PENDING_CONFIRMATION state, and reversing an approved payment with `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
              Confirm:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  internalReference: 84
                  action: confirm
              Cancel:
                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: Allows invalidating an existing token of the site. This will prevent the token or subtoken from being used again.
      requestBody:
        $ref: '#/components/requestBodies/InstrumentInvalidateRequest'
  /api/gateway/information:
    post:
      summary: This service provides information about the user's card/token to be processed. It is recommended to always integrate through the [Gateway](/gateway/api/reference/information) API.
      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: Allows invalidating an existing token of the site. This will prevent the token or subtoken from being used again.
      requestBody:
        $ref: '#/components/requestBodies/GatewayInformationRequest'
  /api/gateway/token:
    post:
      summary: This service allows you to search for a tokenization using the value of the token or subtoken. It is recommended to always integrate via the [Gateway](/en/gateway/api/reference/tokenize#token-search-request).
      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: Notification sent to the merchant (MerchantNotificationRequest)
      operationId: merchant-api-notification-url
      requestBody:
        $ref: '#/components/requestBodies/MerchantNotificationRequest'
components:
  schemas:
    Person:
      description: Structure that reflects the information of a person involved in a transaction.
      type: object
      title: Person
      properties:
        document:
          type: string
          maxLength: 25
          description: Identity document. Format and length validation is applied dynamically based on the country and the selected document type.
          example: '1122334455'
        documentType:
          type: string
          example: CC
          maxLength: 6
          description: |
            Document type identifier. View options in [Document Types](/en/checkout/document-types)

            e.g.: `CC` for "Cédula de Ciudadanía" in Colombia.
        name:
          type: string
          minLength: 1
          maxLength: 60
          description: Name of the person or company
          example: John
        surname:
          type: string
          minLength: 1
          maxLength: 60
          description: Last name of the person. Does not apply when the type of document corresponds to that of a company
          example: Doe
        company:
          type: string
          minLength: 1
          maxLength: 60
          description: |
            Name of the company to which the person belongs

            e.g.: `Placetopay`
          example: Evertec
        email:
          type: string
          minLength: 1
          maxLength: 80
          example: johndoe@app.com
          description: |
            Email of the user or company

            e.g.: `juan.perez@example.com`
        mobile:
          type: string
          minLength: 1
          maxLength: 30
          description: |
            User or company phone number

            e.g.: `+573214445566`
          example: '+573111111111'
        address:
          $ref: '#/components/schemas/Address'
    PaymentRequest:
      title: PaymentRequest
      type: object
      description: |
        Requested payment information.
      required:
        - reference
        - amount
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 32
          description: |
            Unique payment reference, consisting of up to 32 alphanumeric characters and permitted symbols 
            e.g.: `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: |
            Description of the process to be performed, allowing up to 250 alphanumeric, accented characters, and common symbols 
            e.g.: `Appointment with Dr. Pérez at 10:00 am. on 5/12/2024, for $100.00`
          example: Consumo mes de Mayo
        amount:
          $ref: '#/components/schemas/Amount'
        allowPartial:
          type: boolean
          description: |
            Defines if the amount to be charged can be paid in several transactions.
            When set to `true` the user will be able to complete the payment in multiple transactions.
          default: false
        shipping:
          $ref: '#/components/schemas/Person'
          description: |
            Structure to relate shipping information.
        items:
          type: array
          items:
            description: Possesses a collection of element structures.
            title: Item
            type: object
            properties:
              sku:
                type: string
                minLength: 1
                maxLength: 30
                description: |
                  Item SKU.   
                  e.g.: `SKU-12345`
                example: SKU-12345
              id:
                type: string
                minLength: 1
                maxLength: 30
                description: null
                example: SKU-12345
              description:
                type: enum
                description: Description of the article.
                example: Item description
              name:
                type: string
                minLength: 1
                maxLength: 120
                description: |
                  Article name.   
                  e.g.: `Manta de lana`
                example: product_1
              category:
                type: enum
                description: |
                  Article category. One of: `digital` `physical`
                enum:
                  - digital
                  - physical
                example: physical
              qty:
                type: number
                description: |
                  Number of articles of this type.   
                  e.g.: `23`
                example: '1'
              price:
                type: number
                description: |
                  Total cost of the article.   
                  e.g.: `1400`
                example: 1400
              tax:
                type: number
                description: |
                  Item Tax Amount.   
                  e.g.: `100`
              additional:
                type: object
                description: Object that allows sending additional data in JSON format.
                nullable: true
          description: |
            Structure to relate products or items in the process.
        fields:
          $ref: '#/components/schemas/Fields'
        recurring:
          $ref: '#/components/schemas/Recurring'
        subscribe:
          type: boolean
          description: |
            When `true` is sent, a subscription payment session is generated.

            In the payment process, the user can choose whether or not to save his payment method to be used in future charges..
          default: false
        dispersion:
          type: array
          description: |
            When defined, a scatter payment session is generated.
            The generated payment can be divided into different destinations according to the given conditions.
          items:
            $ref: '#/components/schemas/DispersionDetail'
        modifiers:
          type: array
          items:
            $ref: '#/components/schemas/Modifiers'
          description: |
            Structure to define modifiers in the collection.

            Applies to tax laws in specific countries.
        processorFields:
          type: array
          description: Structure that may vary over time depending on the information available for the means of payment. See more in [Processor Fields](/en/checkout/processor-fields)
          items:
            $ref: '#/components/schemas/NameValuePair'
      examples:
        - reference: '12345'
          description: Payment test
          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: |
        Information on the amount to be collected
      properties:
        currency:
          type: string
          example: COP
          minLength: 3
          maxLength: 3
          description: |
            Alphabetical code of the currency to be used [ISO 4217 alpha code](https://en.wikipedia.org/wiki/ISO_4217)   
            e.g.: `USD`
        total:
          type: number
          example: 2000
          description: |
            Total value in the indicated base currency   
            e.g.: `1000` equals _one thousand dollars_
        taxes:
          description: |
            Structure to define taxes in the payment process.
          type: array
          items:
            $ref: '#/components/schemas/Taxes'
        details:
          description: |
            Structure to define additional details of the amount in the payment process.
          type: array
          items:
            $ref: '#/components/schemas/Details'
    NameValuePair:
      title: NameValuePair
      description: |
        Structure to relate additional data in the process.
      type: object
      properties:
        keyword:
          type: string
          minLength: 1
          maxLength: 50
          description: |
            Identifier or index of the data to be attached.   
            e.g.: `cmsInvoiceId`
          example: '1111'
        value:
          type:
            - string
            - object
            - array
            - number
            - boolean
          minLength: 1
          maxLength: 255
          description: |
            Value of the data to be attached.   
            e.g.: `ID_2233`
          example: lastDigits
        displayOn:
          type: enum
          description: |
            Indicates under what conditions the attached data is displayed. See more in [Additional Fields](/en/checkout/additional-fields)

            One of: `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: Required when `action` is `CREATE`. Indicates the recurrence conditions of the autopay.
      required:
        - type
        - periodicity
        - interval
        - nextPayment
      properties:
        type:
          type: string
          description: |
            Corresponds to the type of charge that the recurrence will have. Only used in self-pay sessions.
            `FIXED`: The amount is fixed and was defined from the creation of the self-payment,
            `MINIMUM_BALANCE`: The minimum amount to keep the recurrence active, defined by an external service,
            `TOTAL_BALANCE`: The total defined in the asset, defined by an external service
          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: Conditions of the autopay recurrence.
      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: Informative start date of the recurrence, format YYYY-MM-DD. Only used in self-pay sessions.
          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: |
        Structure to indicate the frequency of a recurring charge.
      required:
        - periodicity
        - interval
        - maxPeriods
      properties:
        periodicity:
          type: enum
          description: |
            Billing frequency. `D` day, `M` month, `Y` year
          enum:
            - D
            - M
            - 'Y'
          example: D
        interval:
          type: integer
          min: 1
          description: |
            In combination with `periodicity`, indicates how often the charge will be made.
            E.g.: For 15 days, use `interval: 15` `periodicity: "D"`.
          example: 15
        nextPayment:
          type: string
          description: Next payment date
          format: date
          example: '2019-08-24'
        maxPeriods:
          type: number
          description: |
            Maximum number of periods. Use `-1` if there is no limit
          example: 12
          min: -1
        dueDate:
          type: string
          format: date
          description: |
            Recurrence due date
            E.g.: `2019-09-24`
          example: '2019-09-24'
        notificationUrl:
          type: string
          maxLength: 255
          format: uri
          description: URL where the service will notify each time a charge is made
          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: |
        Structure to define information about a tax.
      examples:
        - kind: valueAddedTax
          amount: 1000
          base: 0
      properties:
        kind:
          type: enum
          description: |
            Tax type identifier

            One of: `valueAddedTax` `exciseDuty` `ice` `airportTax` `stateTax` `reducedStateTax` `municipalTax`.
          enum:
            - valueAddedTax
            - exciseDuty
            - ice
            - airportTax
            - stateTax
            - reducedStateTax
            - municipalTax
          example: valueAddedTax
        amount:
          type:
            - number
          description: |
            Full amount of tax   
            e.g.: `200`
        base:
          type:
            - number
          description: |
            Base amount on which the tax is calculated   
            e.g.: `1000`
    Details:
      title: Details
      type: object
      description: |
        Structure to store information about a detail.
      x-internal: false
      examples:
        - kind: discount
          amount: 1000
      properties:
        kind:
          type: enum
          description: |
            Detail Type Identifier. 
            One of:  `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: |
            Total amount of detail

            e.g.: `200`
    SubscriptionRequest:
      title: SubscriptionRequest
      type: object
      description: |
        When sent, a subscription session is generated.

        The user registers a payment method so that later the merchant can charge on that payment method.
      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: |
        Detail of the autopay to be generated. The user must register a payment method so that automatic charges are made on that payment method according to the agreed conditions. Required when `.type` is `autopay`.
      properties:
        action:
          type: enum
          description: |
            Indicates the action to be performed with the autopay.
            One of: `CREATE` to create an autopay, `EDIT` to edit an existing autopay.
          enum:
            - CREATE
            - EDIT
          example: CREATE
        reference:
          $ref: '#/components/schemas/Reference'
        description:
          $ref: '#/components/schemas/Description'
        id:
          $ref: '#/components/schemas/AutopayId'
          description: Required when `action` is `EDIT`. Identifier of the existing autopay.
        dueDay:
          $ref: '#/components/schemas/AutopayDueDay'
        recurring:
          $ref: '#/components/schemas/AutopayRecurring'
        amount:
          $ref: '#/components/schemas/Amount'
          description: Required when `recurring.type` is `FIXED`. Defines the fixed amount to be charged in each recurrence.
    AutopayId:
      type: string
      format: uuid
      description: Identifier of the Autopay.
      example: f7b347d7-c922-4c68-8750-99fb43c9e5ff
    AutopayDueDay:
      type: integer
      minimum: 1
      maximum: 28
      description: |
        For recurring payments with a monthly frequency, it corresponds to the payment cutoff day.
        It is an informative value to indicate to the user the maximum expected day to make the payment.
        It usually indicates that charges after this day may have surcharges or may not be available.    
        E.g.: `15` for the fifteenth day of each month.
      example: 15
    RedirectRequest:
      title: CreateSessionRequest
      type: object
      description: |
        Information to create a WebCheckout session.
      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: |
            User data **buyer**, refers to the user who is buying a product or service.

            **When a session is created**: It can be sent if you know the user who is making the purchase, as it helps to complete the session information.
            If this data is sent, the user will have their personal data pre-filled and will be able to change them at Checkout.
        payer:
          $ref: '#/components/schemas/Person'
          description: |
            Data of the user **payer**, refers to the owner of the means of payment or user who paid the requested amount.

            **When a session is created**: It should only be used when you want to "force" the data of the user who will complete the process.
            If this data is sent, the user will have their personal data pre-filled but **will not be able to change them**.
        subscription:
          $ref: '#/components/schemas/SubscriptionRequest'
        fields:
          $ref: '#/components/schemas/Fields'
        paymentMethod:
          type: enum
          description: |
            It is used to restrict the payment methods available at checkout.
            Multiple codes can be sent separated by commas.
            See more in [Payment methods](/en/checkout/payment-methods)
          example: visa,master,pse
        cancelUrl:
          type: string
          format: uri
          maxLength: 255
          description: |
            Cancellation URL, the user is redirected to this url when he decides not to continue with the process.
            Occurs when the user clicks on _I don't want to continue_

            e.g.: `https://merchant.com/cancel`
          example: https://commerce.test/cancel
        skipResult:
          type: boolean
          description: |
            If `true` is sent, when the user finishes the process the session result page will not be displayed, instead they will be redirected to the `returnUrl`. See more in [Skip result](/en/checkout/skip-result)
          default: false
        noBuyerFill:
          type: boolean
          description: |
            By default, the data sent as `buyer` is pre-filled in the Checkout interface to speed up the payment process, if this parameter is sent as `true` then this pre-fill will not be done.
          default: false
        type:
          type: enum
          description: |
            Parameter used for additional type sessions
            Use `checkin` to generate a Pre-authorization session.
            Use `autopay` to generate an Autopay session.
          enum:
            - checkin
            - autopay
          example: checkin
        metadata:
          $ref: '#/components/schemas/Metadata'
        autopay:
          $ref: '#/components/schemas/AutopayRequest'
      x-examples:
        Create basic session:
          locale: es_CO
          payer:
            name: John
            surname: doe
            email: user_email@example.com
            documentType: CC
            document: '1036949824'
            mobile: '3102903560'
          payment:
            reference: '331122'
            description: Example basic payment
            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
        Create checkin session:
          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: Example basic payment
            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: Payment test
            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
          subscription:
            reference: '12345'
            description: Example description
            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: |
        Site authentication. See more in [Authentication](/en/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: |
            Site identifier.
        tranKey:
          type: string
          minLength: 1
          maxLength: 64
          description: |
            Generated tranKey credential.
            See more in [Authentication](/en/checkout/authentication)
        nonce:
          type: string
          minLength: 1
          maxLength: 255
          description: |
            Random value for each Base64 encoded request.
        seed:
          type: string
          format: date-time
          minLength: 1
          maxLength: 35
          description: |
            Current date, which is generated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format .
    Status:
      title: Status
      description: |
        Structure that contains the response information about a request or payment, and reports the current status of the same.
      type: object
      properties:
        status:
          type: enum
          description: Status of a request or payment
          example: APPROVED
          enum:
            - APPROVED
            - PENDING
            - PENDING_CONFIRMATION
            - REJECTED
            - APPROVED_PARTIAL
            - PARTIAL_EXPIRED
            - FAILED
        reason:
          type:
            - string
            - number
            - 'null'
          maxLength: 255
          description: |
            Reason Code Provided.
          example: '00'
        message:
          type:
            - string
            - 'null'
          maxLength: 255
          description: |
            Description of the reason code.
          example: The petition has been successfully approved
        date:
          type: string
          maxLength: 35
          format: date-time
          description: |
            Date and time when the payment status is generated. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Format.
          example: '2022-07-27T14:51:27-05:00'
    Transaction:
      title: Transaction
      type: object
      description: |
        Structure containing information about the payment process of the transaction in Placetopay.
      examples:
        - status:
            status: APPROVED
            reason: '00'
            message: The petition has been successfully approved
            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
            - value: 685.33
              keyword: installmentAmount
              displayOn: none
      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: |
        Structure containing information about the sparse transaction process.
      examples:
        - status:
            status: APPROVED
            reason: '00'
            message: The petition has been successfully approved
            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: |
        Autopay generated during the autopay session process.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        id:
          $ref: '#/components/schemas/AutopayId'
        siteId:
          type: integer
          description: Identifier of the site where the autopay was created.
          example: 1234
        payer:
          $ref: '#/components/schemas/Person'
        buyer:
          $ref: '#/components/schemas/Person'
        subscription:
          type: object
          description: Structure containing information about the subscription associated with the AutoPay.
          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: Structure containing information about the payment method associated with the AutoPay.
          properties:
            token:
              $ref: '#/components/schemas/Token'
        additional:
          type: object
          description: Structure that includes additional autopay data.
          properties:
            dueDay:
              type: string
              $ref: '#/components/schemas/AutopayDueDay'
            customerAccountNumber:
              type: string
              description: Optional data sent when starting the Autopay process.
              example: '1234567890'
        acceptedAt:
          type: string
          format: date-time
          description: Date and time when the autopay was accepted.
          example: '2021-09-24T10:02:17-05:00'
    AmountConversion:
      title: AmountConversion
      type: object
      description: |
        Structure to define the conversion factor and values.
      properties:
        from:
          $ref: '#/components/schemas/AmountBase'
        to:
          $ref: '#/components/schemas/AmountBase'
        factor:
          type:
            - number
            - string
          minLength: 1
          maxLength: 20
          example: 1
          description: Conversion factor
    AmountBase:
      title: AmountBase
      type: object
      description: |
        Structure that represents a quantity that defines the currency and the total.
      properties:
        'currency ':
          type: string
          minLength: 3
          maxLength: 3
          description: |
            Currency according to [ISO 4217 alpha code](https://en.wikipedia.org/wiki/ISO_4217).
          example: COP
        'total ':
          type:
            - number
          description: |
            Total value.
          example: 10000
    SubscriptionResponse:
      title: SubscriptionResponse
      type: object
      description: |
        Structure containing information for the subscription payment method.
      examples:
        - status:
            status: OK
            reason: '00'
            message: The petition has been successfully approved
            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: Defines type of subscription that is returned
          example: token
          enum:
            - token
            - cuenta
        instrument:
          type: array
          items:
            $ref: '#/components/schemas/NameValuePair'
    RedirectInformation:
      title: RedirectInformation
      type: object
      description: |
        Response structure to a request for transaction information.
      properties:
        requestId:
          type:
            - number
            - integer
          example: 1
          description: Request ID
        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: The petition has been successfully approved
            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:
            - status:
                status: APPROVED
                reason: '00'
                message: The petition has been successfully approved
                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: The petition has been successfully approved
              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: Request structure to cancel a session.
      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: |
        Response structure to a cancel session request.
      properties:
        status:
          $ref: '#/components/schemas/Status'
        session:
          $ref: '#/components/schemas/RedirectInformation'
      examples:
        - status:
            status: OK
            reason: '00'
            message: The request has been processed correctly
            date: '2025-07-11T14:05:44-05:00'
          session:
            requestId: 28
            status:
              status: REJECTED
              reason: MC
              message: The request has been cancelled by the merchant
              date: '2025-07-11T14:05:44-05:00'
            request:
              locale: en_US
              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: |
        Structure containing the details of a subscribed means of payment.
      required:
        - token
      properties:
        token:
          $ref: '#/components/schemas/SimpleToken'
        pocket:
          type:
            - enum
          description: |
            Wallet code. Applies to Cards in Uruguay

            Possible values:   
            `10` Savings account en UYU
            `20` current account en UYU
            `80` Savings account en USD
            `90` current account en USD
          example: '10'
          enum:
            - '10'
            - '20'
            - '80'
            - '90'
        credit:
          $ref: '#/components/schemas/Credit'
    InstrumentInvalidate:
      title: InstrumentInvalidate
      description: |
        Information of the Token to invalidate.
      type:
        - object
      required:
        - token
      properties:
        token:
          description: |
            Information of a "tokenized" payment method. It must be tokenized with a subscription session.
            It must contain the `token` or the `subtoken`, both valid representations of a tokenized payment method.
          type:
            - object
          properties:
            token:
              $ref: '#/components/schemas/InstrumentTokenToken'
            subtoken:
              $ref: '#/components/schemas/InstrumentTokenSubToken'
    InstrumentTokenToken:
      type: number
      maxLength: 64
      description: Representation of the means of payment.
      example: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
    InstrumentTokenSubToken:
      type: string
      maxLength: 16
      description: |
        Numerical representation of the means of payment. It is used in cases where the token is required to be numeric.
        The last 4 digits are the same as the last 4 digits of the credit card.
      example: '8740257204881112'
    SimpleToken:
      title: SimpleToken
      type:
        - object
      description: |
        Information of a "tokenized" means of payment. It must be tokenized with a subscription session.
        It must contain the `token` or the `subtoken`, both valid representations of a tokenized means of payment.
      properties:
        token:
          $ref: '#/components/schemas/InstrumentTokenToken'
        subtoken:
          $ref: '#/components/schemas/InstrumentTokenSubToken'
        installments:
          type: integer
          description: Number of installments in which the collection is requested. Applies to Colombia.
          example: '`2` for 2 installments.'
        cvv:
          type: string
          minLength: 3
          maxLength: 4
          description: Card Security Code. If the user is present in the collection process, it is recommended to attach this information.
          example: '123'
      examples:
        - token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
          subtoken: fakesubtoken00005
          installments: null
          cvv: '123'
    CollectRequest:
      title: CollectRequest
      type: object
      description: |
        Allows payments to be made without user intervention using previously subscribed means of payment.
      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: |
            Data of the user **payer**, refers to the owner of the means of payment or user who paid the requested amount.
        buyer:
          $ref: '#/components/schemas/Person'
          description: |
            User data **buyer**, refers to the user who is buying a product or service.
        locale:
          $ref: '#/components/schemas/Locale'
        type:
          type: string
          description: |
            Parameter used for pre-authorization type sessions

            Only `checkin` is supported to generate a pre-authorization session
          enum:
            - checkin
        metadata:
          $ref: '#/components/schemas/Metadata'
        provider:
          type: string
          description: Provider code to use for the transaction.
    TransactionActionRequest:
      title: TransactionActionRequest
      type: object
      description: Structure that allows performing preauthorization requests such as `checkout`, `reauthorization`, `reverse`, `confirm` and `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: |
            Type of operation to perform on the transaction

            `reverse` to reverse a transaction.
            `reauthorization` to modify a checkin transaction.
            `checkout` to close and collect a checkin transaction.
            `confirm` to confirm a transaction in PENDING_CONFIRMATION state.
            `cancel` to cancel a transaction in PENDING_CONFIRMATION state.
          enum:
            - checkout
            - reauthorization
            - reverse
            - confirm
            - cancel
          example: checkout
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        amount:
          $ref: '#/components/schemas/Amount'
    DispersionDetail:
      title: DispersionDetail
      type: object
      description: Structure that reflects the information of the details for payment with dispersion.
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
          description: |
            I ride to "scatter" in this destination.
        agreement:
          nullable: true
          type:
            - number
          description: |
            Id of the destination of this amount. It can be the id of a site.

            e.g.: `122`
        agreementType:
          type: enum
          description: |
            Type of destination of this amount.
            `MERCHANT` for sites, `AIRLINE` for airlines.
          enum:
            - MERCHANT
            - AIRLINE
          example: MERCHANT
      examples:
        - agreement: '1299'
          agreementType: MERCHANT
          amount:
            currency: USD
            total: 200
    Modifiers:
      title: Modifiers
      type: object
      description: |
        Structure for additional modifications in the collection.

        Applies to tax laws in specific countries.
      properties:
        type:
          type: enum
          description: |
            Modifier type identifier. 
            Only `FEDERAL_GOVERNMENT` is currently supported.
          example: FEDERAL_GOVERNMENT
          enum:
            - FEDERAL_GOVERNMENT
        code:
          type:
            - number
          description: |
            Modifier code.

             For `FEDERAL_GOVERMENT` represents the law number for discount.
            `17934` Gastronomic Services
            `18083` IMESI Brazil - Argentina
            `19210` Financial Inclusion
            `18910` Family Allowances
            `18999` Real Estate Reimbursement
          enum:
            - 17934
            - 18083
            - 19210
            - 18910
            - 18999
          example: 17934
        additional:
          type: object
          description: |
            Structure for appending information to the modifier
          properties:
            invoice:
              type: string
              description: |
                Required when `modifiers.[].type` is `FEDERAL_GOVERMENT`. Indicates the invoice number.

                e.g.: `123456789`
              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: Language in which the request and the session will be processed. See more in [Location](/en/checkout/localization)
    Reference:
      title: Reference
      type: string
      minLength: 1
      maxLength: 32
      description: |
        Unique reference of the process. Maximum of 32 characters

        e.g.: `PAYMENT_0001_ABC`
      example: '12345'
    Description:
      title: Description
      type: string
      minLength: 1
      maxLength: 255
      description: |
        Description of the process to be carried out
      example: Consumption for the month of May
    InternalReference:
      type: integer
      description: Unique internal reference of the transaction
      example: 543423
    PaymentMethod:
      type: string
      description: Code for the payment method used.
      minLength: 1
      maxLength: 255
      example: visa
    PaymentMethodName:
      type: string
      description: Name of the payment method used..
      minLength: 1
      maxLength: 255
      example: Visa
    IssuerName:
      type: string
      description: Name of the issuer or processor.
      minLength: 1
      maxLength: 255
      example: JPMORGAN CHASE BANK, N.A.
    Receipt:
      type: string
      minLength: 1
      maxLength: 255
      description: Transaction receipt number.
      example: '052617800175'
    Franchise:
      type: string
      minLength: 1
      maxLength: 5
      description: Franchise of the card used.
      example: PS_VS
    Refunded:
      type: boolean
      description: It is used to define if the transaction has been reversed
      default: false
    Authorization:
      type: string
      minLength: 1
      maxLength: 255
      description: Authorization code.
      example: '965960'
    ProcessorFields:
      type: array
      description: Structure that may vary over time depending on the information available for the payment method. See more in [Processing data](/en/checkout/processor-fields)
      items:
        $ref: '#/components/schemas/NameValuePair'
    Dispersion:
      type: array - 'null'
      description: Structure containing dispersion information
      items:
        $ref: '#/components/schemas/TransactionDispersion'
    Agreement:
      type:
        - integer
        - 'null'
        - number
      description: Transaction recipient identifier. For the main site of the transaction.
      example: 186
    AgreementType:
      type:
        - enum
        - 'null'
      description: Dispersion type
      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
      description: |
        Expiration date of a session. The user must finish the process before this date.
        The expiration time must be at least 5 minutes from the time of creation. See more in [Expiration date](/en/checkout/expiration)   
        e.g.: `2024-09-03T12:23:39-05:00`
    IpAddress:
      type: string
      maxLength: 46
      description: IP address of the user who will perform the process.
      example: 134.10.163.36
    UserAgent:
      type: string
      maxLength: 255
      description: User Agent of the user's browser that will carry out the process.
      example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
    ReturnUrl:
      type: string
      format: uri
      maxLength: 255
      description: |
        Return URL, to this url the user is redirected once the session ends.
        Occurs when the user clicks on _Return to commerce_.

        e.g.: `https://merchant.com/return`
      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: Approved
            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: |
        Structure to relate additional information in the process. See more in [Additional Fields](/en/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'
    Instrument:
      title: Instrument
      type: object
      description: Structure that contains information about the means of payment to be used in a transaction. This structure is variable according to the request that is generated. Each service requires that one or another data be used.
      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: Receives the PIN code when it is flat or when it is a PinBlock
        redirection:
          $ref: '#/components/schemas/Redirection'
        kount:
          $ref: '#/components/schemas/Kount'
        pocket:
          type: string
          description: Card pocket used for payment
    CardType:
      title: CardType
      x-stoplight:
        id: x4y03rkspgz0b
      type: enum
      enum:
        - C
        - R
        - A
      description: Indicates the type of the card. C = credit, R = debit, A = savings
    Credit:
      title: Credit
      type: object
      description: Structure that contains information on the type of credit. See more in [Credits](/en/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
    Pocket:
      title: Pocket
      type: object
      description: Structure containing card pocket information
      properties:
        code:
          type: string
          description: Pocket value
        description:
          type: string
          description: Pocket description
      x-examples: null
    BankItem:
      title: BankItem
      x-stoplight:
        id: 60487hsjhovs9
      type: object
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 4
          description: Banking entity code
        description:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the banking entity
    Account:
      title: Account
      type: object
      description: Structure that contains bank account information.
      required:
        - bankCode
        - accountType
        - accountNumber
      properties:
        bankName:
          type: string
          maxLength: '30'
          description: Name of the bank of the account to be processed
        bankCode:
          type: string
          maxLength: '17'
          description: Code that identifies the bank on the network
        accountType:
          type: string
          description: Account type
          enum:
            - SAV
            - DDA
            - CCD
        accountNumber:
          type: string
          maxLength: '17'
          description: Account number
        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: The verificationCode is a JSON Web Signature (JWS). It is intended to be the instrument for verifying the status of the account
    Token:
      title: Token
      type: object
      description: |-
        Structure that contains the token information associated with the card.
        For entry, only the token or subtoken and the cvv are necessary if it is an operation where the user is present.
        For output if all data is returned when tokenizing.
      properties:
        token:
          type: string
          maxLength: '64'
          minLength: '64'
          description: Code generated to identify the card in the system
          example: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
        subtoken:
          type: string
          maxLength: '16'
          minLength: '16'
          description: Alternate code generated to identify the card
          example: '8740257204881112'
        franchise:
          type: string
          minLength: 1
          maxLength: 20
          description: Franchise code associated with the token (Only as a response, it is not necessary to send it)
          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: Card expiration date
          example: 12/37
        cvv:
          type: string
          minLength: 3
          maxLength: 4
          description: CVV requested from the user in case it is present in the operation
      x-examples:
        Response example:
          value:
            token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
            subtoken: fakesubtoken00005
            franchise: master
            franchiseName: Mastercard
            lastDigits: '0005'
            validUntil: '2018-12-31'
            installments: '3'
        Request example:
          value:
            token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
            cvv: '123'
    Card:
      title: Card
      type: object
      description: Structure containing card information.
      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
    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: This value only applies if the validation was done with the Placetopay 3DS service
        enrolled:
          type: enum
          enum:
            - 'Y'
            - 'N'
            - U
          description: Informs if the card is registered in 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: Structure containing PinPad service information
      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: It represents a redirect payment method, meaning that it requires the user to be sent to another URL to complete the process.
      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 so that once the payment process is completed, control is returned (when applicable)
        processURL:
          type: string
          format: uri
          maxLength: 250
          description: URL to which the client must be sent to continue the process, it is provided by the service
    Kount:
      title: Kount
      x-stoplight:
        id: qevzv57mju2tp
      type: object
      description: Manages specific information to use with the Kount risk filter
      properties:
        session:
          type: string
          minLength: 1
          maxLength: 250
          description: Identifier of this operation in Kount, it must be unique per transaction
        type:
          type: string
          description: Describes the type of operation that is being handled in the session to define the additional fields to be sent
          enum:
            - airline
            - soat
      required:
        - session
    Address:
      title: address
      type: object
      description: Structure to attach address or address information
      properties:
        country:
          type: string
          description: The country in which the address is located. [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.
          minLength: 2
          maxLength: 2
          example: CO
        state:
          type: string
          maxLength: 3
          description: State/province/department. [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) code
          example: ANT
        city:
          type: string
          maxLength: 30
          description: City of residence
          example: Medellín
        postalCode:
          type: string
          maxLength: 10
          description: Postal code of the address
          example: '55555'
        street:
          type: string
          minLength: 1
          maxLength: 128
          description: Home address.
          example: 'Calle 12 #33a-12, Apto 101'
        phone:
          type: string
          maxLength: 20
          description: Home phone number
          example: '+573111111111'
    Metadata:
      title: metadata
      type: object
      description: Key-value structure used to send additional information and determine specific behaviors during session processing.
      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: Indicates that the session will be processed by an agent using the cardholder's data
        EBTDeliveryIndicator:
          type: string
          enum:
            - DIRECT_DELIVERY
            - CUSTOMER_PICKUP
            - COMMERCIAL_SHIPPING
            - OTHER
            - NOT_AVAILABLE
          description: ' (Required for EBT payments): Defines the delivery type'
        openingDate:
          type: string
          description: 'Account creation date (format: ''YYYY-MM-DD''). Required for PSE in merchants with “Financial Services” category.'
        beneficiaryId:
          type: string
          description: Beneficiary ID linked to the receiving account in a PSE transaction. Required for merchants in the “Financial Services” category
        kount:
          type: object
          description: Additional information about the transaction that can be used for risk analysis and fraud prevention.
          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: Type of shipping ("SHIPPED", "DIGITAL", "STORE_PICK_UP", "LOCAL_DELIVERY", "STORE_DRIVE_UP", "IN_PERSON").
                provider:
                  type: string
                  description: Name of the shipping or delivery provider.
                trackingNumber:
                  type: string
                  description: Tracking number provided by the carrier.
                shippingMethod:
                  type: string
                  description: Delivery method ("STANDARD", "EXPRESS", "SAME_DAY", "NEXT_DAY", "SECOND_DAY").
                store:
                  type: object
                  properties:
                    address:
                      type: object
                      properties:
                        street:
                          type: string
                          description: Street address of the store.
                        city:
                          type: string
                        state:
                          type: string
                        postalCode:
                          type: string
                        country:
                          type: string
                        phone:
                          type: string
                          description: Store contact phone number.
                accessUrl:
                  type: string
                  format: uri
                  description: URL for accessing shipping or download information.
                digitalDownloaded:
                  type: boolean
                  description: Indicates whether the digital product has been downloaded.
                downloadDeviceIp:
                  type: string
                  format: ipv4
                  description: IP address of the device used for download.
            store:
              type: object
              description: Information about the physical store associated with the transaction.
              properties:
                id:
                  type: string
                  description: Store identifier.
                  example: STORE001
                name:
                  type: string
                  description: Store name.
                  example: Sucursal centro
                address:
                  type: object
                  description: Store address.
                  properties:
                    line1:
                      type: string
                      description: First line of the address.
                      example: calle 80
                    line2:
                      type: string
                      description: Second line of the address.
                      example: casa 3
                    city:
                      type: string
                      description: Store city.
                      example: Medellin
                    region:
                      type: string
                      description: Region or state of the store.
                      example: ANTIOQUIA
                    countryCode:
                      type: string
                      description: Country code (ISO 3166-1 alpha-2).
                      example: CO
                    postalCode:
                      type: string
                      description: Store postal code.
                      example: '10001'
        requiresConfirmation:
          type: boolean
          description: |
            Indicates whether the transaction requires merchant confirmation before final processing.
            When set to `true`, the transaction will be created in PENDING_CONFIRMATION state
            and the merchant must call confirm or cancel via the transaction actions endpoint.
          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: The petition has been successfully approved
                  date: '2022-07-27T14:51:27-05:00'
            OK:
              value:
                status:
                  status: OK
                  reason: '00'
                  message: The petition has been successfully approved
                  date: '2022-07-27T14:51:27-05:00'
            FAILED:
              value:
                status:
                  status: FAILED
                  reason: XN
                  message: The token used is invalid
                  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:
            Example:
              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: Object with token information.
                properties:
                  id:
                    type: number
                    description: Tokenization identifier.
                  type:
                    type: enum
                    description: Tokenization type.
                    enum:
                      - card
                      - account
                  token:
                    $ref: '#/components/schemas/InstrumentTokenToken'
                  subtoken:
                    $ref: '#/components/schemas/InstrumentTokenSubToken'
                  franchise:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: Franchise of the card used.
                    example: visa
                  franchiseName:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: Name of the card franchise.
                    example: Visa
                  issuerName:
                    $ref: '#/components/schemas/IssuerName'
                  lastDigits:
                    type: string
                    nullable: true
                    minLength: 1
                    maxLength: 4
                    description: Last digits of the card
                  validUntil:
                    type: string
                    minLength: 1
                    maxLength: 10
                    format: date
                    description: Card expiration date
                    example: 12/37
                  owner:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: John Doe
                    description: Cardholder's name
                  bin:
                    type: string
                    example: '411111'
                    description: Bank Identification Number
                  accountType:
                    type: string
                    enum:
                      - SAV
                      - DDA
                      - CCD
                    description: ACH account type, applies only to Puerto Rico
          examples:
            Ok:
              value:
                status:
                  status: OK
                  reason: '00'
                  message: The request has been successfully processed
                  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: |
                  Unique identifier for the session assigned by Placetopay.
              reference:
                type: string
                description: Reference assigned to the session by the merchant.
              signature:
                type: string
                description: Message signature, must be validated on the merchant's server.
    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: Structure that contains information about the means of payment to be used in a transaction. This structure is variable according to the request that is generated. Each service requires that one or another data be used.
                properties:
                  token:
                    $ref: '#/components/schemas/InstrumentTokenToken'
                  subtoken:
                    $ref: '#/components/schemas/InstrumentTokenSubToken'
