openapi: 3.0.0
info:
  title: Gateway
  version: '1.0'
  license:
    name: Privative
    description: |-
      This web service and its architecture allows any application to connect to Placetopay to process transactions, independent of the development language.
      To use the web service, you will need to have a programming language that can communicate with a REST service.
      The integration method contemplates the basic operations for the processing of non-face-to-face cards, that is, types of credit, interest, OTP generation, authorization, reverse.
      Each of the uses and the data required in the plot for each of the cases will be described below. The response for each operation is unified into a single resulting frame type.
      By default the language of the responses is in Spanish, if you wish to change it is necessary to send the `locale` parameter in the requests.
      ### Services
      All consumption is made to the base URL, which will be provided by the operations area and the endpoint of the service to be consumed is added to said URL.
      For example, if the base URL was https://placetopay.com, to consume the service and request information, a POST is made with the data from the example to the URL https://placetopay.com/gateway/information
  contact:
    name: Evertec Placetopay
    email: servicioposventa@placetopay.com
servers:
  - url: https://api-co-dev.placetopay.ws
    description: Colombia Tests
  - url: https://api-ec-dev.placetopay.ws
    description: Ecuador Tests
tags:
  - name: Get information
    description: Once you have the card data, it allows you to determine the flow to follow
  - name: Transaction processing
    description: Different ways to process a request
  - name: Query a transaction
    description: Search for information about one or more transactions carried out
  - name: Actions on transactions
    description: Allows you to perform operations such as cancellation, checkout, processing a manual transaction
  - name: Card tokenization
    description: Allows you to securely store a card for automatic payment processes later
  - name: 3DS process
    description: Validate the transaction using 3DS
  - name: OTP process
    description: Allows you to generate and subsequently validate a One Time Password when required
  - name: Pinpad Operations
    description: Allows PIN validation with a secure Pinpad
  - name: Report of operations carried out
    description: Allows you to obtain a report of all transactions carried out in a period of time for the site used
  - name: Account validator
    description: Allows you to consume the account validator endpoints in a more secure way
paths:
  /gateway/information:
    post:
      summary: Information request
      operationId: post-rest-gateway-information
      description: This service provides information about the user's card that is going to be processed, such as what services will be used for it and the types of credit, if applicable, that are available for it. If there are no types of credit, an arrangement is returned. empty and if there are, each type of credit must be iterated with the installments found in the arrangement.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - title: Card
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determine the language of the response
                      example: es-CO
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    instrument:
                      $ref: '#/components/schemas/Instrument'
                    payment:
                      $ref: '#/components/schemas/Payment'
                    subscription:
                      $ref: '#/components/schemas/Subscription'
                    metadata:
                      type: object
                      description: Dynamic object that contains additional information.
                      properties:
                        preferredPaymentMethodIndex:
                          type: integer
                          description: Index of the Payment method to select from a list of available payment methods. This field is only required when using the Payment Orchestrator flow.
                          example: 2
                - title: Paystudio TS
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determines the response language
                      example: en-US
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    instrument:
                      $ref: '#/components/schemas/Instrument'
                    payment:
                      $ref: '#/paths/~1gateway~1process/post/requestBody/content/application~1json/schema/properties/payment'
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: PSE
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    locale:
                      type: string
                    payer:
                      $ref: '#/components/schemas/Person'
                    payment:
                      type: object
                      description: Structure that contains the information about the payment of the transaction required to the web service
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                    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:
                        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: string
                              enum:
                                - _PSE_
                            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)
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: Botón Bancolombia
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    locale:
                      type: string
                    payer:
                      $ref: '#/components/schemas/Person'
                    payment:
                      type: object
                      description: Structure that contains the information about the payment of the transaction required to the web service
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                    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:
                        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: string
                              enum:
                                - BTNBC
                            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)
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: Botón Aval
                  type: object
                  properties:
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    payment:
                      type: object
                      description: Structure that contains the information about the payment of the transaction required to the web service
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                    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:
                        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: string
                              enum:
                                - 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)
                    locale:
                      type: string
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
                - title: CeroPay
                  type: object
                  properties:
                    locale:
                      type: string
                      description: Determine the language of the response
                      example: es-CO
                    auth:
                      $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                    payment:
                      type: object
                      description: Structure that contains the information about the payment of the transaction required to the web service
                      properties:
                        reference:
                          type: string
                          minLength: 1
                          maxLength: 32
                        description:
                          type: string
                          maxLength: 250
                        amount:
                          title: Amount
                          type: object
                          description: Structure that contains the information about the payment of the transaction required to the web service
                          required:
                            - currency
                            - total
                          properties:
                            currency:
                              type: string
                              enum:
                                - COP
                              example: COP
                              minLength: 3
                              maxLength: 3
                            total:
                              type: number
                            taxes:
                              type: array
                              items:
                                title: TaxDetail
                                type: object
                                description: Structure to store information about a tax.
                                properties:
                                  kind:
                                    type: string
                                    example: valueAddedTax
                                    description: |
                                      Tax type identifier
                                    enum:
                                      - valueAddedTax
                                      - exciseDuty
                                      - ice
                                      - airportTax
                                      - stateTax
                                      - reducedStateTax
                                      - municipalTax
                                  amount:
                                    type: number
                                    description: |
                                      Full amount of tax
                                  base:
                                    description: |
                                      Base amount on which the tax is calculated
                                    type: number
                            details:
                              type: array
                              items:
                                title: AmountDetail
                                type: object
                                description: Structure to store information about an additional value.
                                properties:
                                  kind:
                                    type: string
                                    description: |
                                      Detail Type Identifier.
                                  amount:
                                    type: number
                                    description: |
                                      Total amount of detail
                    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:
                        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: string
                              enum:
                                - BB_CP
                            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)
                    ipAddress:
                      type: string
                    userAgent:
                      type: string
                  required:
                    - auth
                    - payment
                    - instrument
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0OWVkODgwYjNhNw==
                    seed: '2021-09-21T09:34:48-05:00'
                  payment:
                    reference: '1234567890'
                    description: Testing Payment
                    amount:
                      currency: COP
                      total: '3000'
                  instrument:
                    card:
                      number: '4110760000000008'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      tags:
        - Get information
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - title: Card
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: EBUS
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        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
                        items:
                          $ref: '#/components/schemas/BankItem'
                      requireBalance:
                        type: boolean
                        description: Indicates whether it is necessary to consume the get balance service
                      hasForwarding:
                        type: boolean
                        description: Indicates if the payment method has configured transaction forwarding
                      availablePaymentMethods:
                        type: integer
                        description: Indicates the total payment methods available for processing. This will only be indicated in the response if the service is selected by index.
                      requireCardExpiration:
                        type: boolean
                        description: Indicates whether the card's expiration date is required to process the transaction.
                      allowedDocumentTypes:
                        type: array
                        description: Indicates the document types allowed for the transaction.
                        items:
                          type: string
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Paystudio TS
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: PAYSTUDIO
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        description: Indicates the service code that will process the transaction
                        example: PS_VS
                      cardTypes:
                        type: array
                        description: Indicates the card types supported by the provider
                        items:
                          $ref: '#/components/schemas/CardType'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indicates whether transaction interest must be displayed
                      requiereOtp:
                        type: boolean
                        description: Indicates whether the OTP flow must be performed
                      requiereCvv2:
                        type: boolean
                        description: Indicates whether CVV is required for transaction processing
                      threeDS:
                        type: string
                        enum:
                          - optional
                          - required
                          - unsupported
                        description: Indicates whether 3DS is necessary
                      credits:
                        type: array
                        description: Indicates the credits available by provider. Structure under the **per-installment structure** model. See more at [Credit](/en/gateway/additional-data#additional-data-credit)
                        items:
                          $ref: '#/components/schemas/CreditPerInstallment'
                      hasForwarding:
                        type: boolean
                        description: Indicates whether the payment method has transaction forwarding configured
                      requireCardExpiration:
                        type: boolean
                        description: Indicates whether the card expiration date is required to process the transaction.
                      allowedDocumentTypes:
                        type: array
                        description: Indicates the document types allowed for the transaction.
                        items:
                          type: string
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: PSE
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: ACH
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        description: Indicates the code of the service that will process the transaction
                        example: _PSE_
                      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
                        items:
                          $ref: '#/components/schemas/BankItem'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indicates the card types supported by the provider
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indicates if it is necessary display the interest for transaction
                      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'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Botón Bancolombia
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: BANCOLOMBIA
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        description: Indicates the code of the service that will process the transaction
                        example: BTNBC
                      requireRedirection:
                        type: boolean
                        description: Indicates if the payment method is of the redirect type
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indicates the card types supported by the provider
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indicates if it is necessary display the interest for transaction
                      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'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: Botón Aval
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: AVAL
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        description: Indicates the code of the service that will process the transaction
                        example: BTNAV
                      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
                        items:
                          $ref: '#/components/schemas/BankItem'
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indicates the card types supported by the provider
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indicates if it is necessary display the interest for transaction
                      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'
                    required:
                      - status
                      - provider
                      - serviceCode
                  - title: CeroPay
                    type: object
                    properties:
                      status:
                        $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                      provider:
                        type: string
                        example: BANCO_BOGOTA
                        description: Indicates which provider will be used in the transaction
                      serviceCode:
                        type: string
                        description: Indicates the code of the service that will process the transaction
                        example: BB_CP
                      requireRedirection:
                        type: boolean
                        description: Indicates if the payment method is of the redirect type
                      cardType:
                        $ref: '#/components/schemas/CardType'
                      cardTypes:
                        type: array
                        description: Indicates the card types supported by the provider
                        items:
                          $ref: '#/components/schemas/CardType'
                      displayInterest:
                        type: boolean
                        description: Indicates if it is necessary display the interest for transaction
                      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'
                    required:
                      - status
                      - provider
                      - serviceCode
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-09-21T09:26:11-05:00'
                    provider: CREDIBANCO
                    serviceCode: CR_VS
                    cardType: C
                    cardTypes:
                      - C
                      - R
                      - A
                    displayInterest: 'false'
                    requireOtp: 'false'
                    requireCvv2: 'true'
                    threeDS: optional
                    requireCardExpiration: true
                    allowedDocumentTypes:
                      - CLRUT
                    credits:
                      - description: Cuotas
                        code: '0'
                        groupCode: C
                        type: '00'
                        installments:
                          - '1'
                          - '2'
                          - '3'
                          - '4'
                          - '5'
                          - '6'
                          - '7'
                          - '8'
                          - '9'
                          - '10'
                          - '11'
                          - '12'
                          - '13'
                          - '14'
                          - '15'
                          - '16'
                          - '17'
                          - '18'
                          - '19'
                          - '20'
                          - '21'
                          - '22'
                          - '23'
                          - '24'
                          - '25'
                          - '26'
                          - '27'
                          - '28'
                          - '29'
                          - '30'
                          - '31'
                          - '32'
                          - '33'
                          - '34'
                          - '35'
                          - '36'
  /gateway/process:
    post:
      summary: Transaction processing
      operationId: post-gateway-process
      description: This service allows the payment to be made to the user's card, the parameters of the instrument are variables, if type of credit or OTP is not requested, it is not necessary to send these variables, payer is always required, buyer is optional but recommended.
      tags:
        - Transaction processing
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: This field should be sent when a check-in process is carried out, otherwise, it should not be sent in the request.
                  enum:
                    - checkin
                locale:
                  type: string
                  example: es_CO
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payer:
                  $ref: '#/components/schemas/Person'
                buyer:
                  $ref: '#/components/schemas/Person'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  title: Payment
                  type: object
                  description: Structure that contains information about the transaction payment required by the web service.
                  properties:
                    reference:
                      type: string
                      minLength: 1
                      maxLength: 32
                    description:
                      type: string
                      maxLength: 250
                    amount:
                      $ref: '#/components/schemas/Payment/properties/amount'
                    dispersion:
                      type: array
                      items:
                        title: Dispersion
                        type: object
                        description: Structure that contains the information required for a dispersion payment.
                        properties:
                          agreement:
                            type: number
                            description: Identifier of the transaction recipient. For the main transaction site, the value must be null.
                            nullable: true
                          agreementType:
                            type: string
                            enum:
                              - AIRLINE
                              - MERCHANT
                          amount:
                            $ref: '#/components/schemas/Payment/properties/amount'
                    modifiers:
                      type: array
                      description: Structure that contains payment modifiers.
                      items:
                        title: PaymentModifier
                        type: object
                        description: |
                          Structure to store information about a payment modifier.
                          NOTE: If a modifier that applies a discount is sent, the discounts configured by promotions on the site will not be applied.
                        x-examples:
                          law-discount:
                            type: FEDERAL_GOVERNMENT
                            code: '17934'
                            additional:
                              invoice: '123456'
                        properties:
                          type:
                            type: string
                            enum:
                              - FEDERAL_GOVERNMENT
                            description: Modifier type
                          code:
                            type: string
                            example: '17934'
                            description: Modifier code. When the type is FEDERAL_GOVERNMENT, it represents the law number for the discount.
                          additional:
                            type: object
                            description: Additional modifier information
                            properties:
                              invoice:
                                type: string
                                description: Invoice number. Required when the type is FEDERAL_GOVERNMENT.
                    shipping:
                      description: Structure to relate shipping information.
                      title: Person
                      type: object
                      properties:
                        documentType:
                          type: string
                          description: '[Identification document type](/gateway/document-types)'
                          example: CC
                          maxLength: '6'
                        document:
                          type: string
                          description: Identification document number. It must be a valid number according to the document type. See more at [Identification document types](/gateway/document-types)
                          maxLength: '25'
                        name:
                          type: string
                          description: First name
                          maxLength: '60'
                        surname:
                          type: string
                          description: Last name
                          maxLength: '60'
                        company:
                          type: string
                          description: Company
                          maxLength: '60'
                        email:
                          type: string
                          description: Email address.
                          maxLength: '80'
                        address:
                          description: Object that contains a person's address information.
                          title: Address
                          type: object
                          properties:
                            street:
                              type: string
                              maxLength: '128'
                              description: Street
                            city:
                              type: string
                              maxLength: '30'
                              description: City
                            state:
                              type: string
                              maxLength: '3'
                              description: Country subdivision code representing the state or province. ISO 3166-2 format.
                              example: CUN
                            postalCode:
                              type: string
                              maxLength: '10'
                              description: Postal code
                              example: '110111'
                            country:
                              type: string
                              maxLength: '2'
                              example: CO
                              description: Country. ISO 3166-1 alpha-2 code.
                            phone:
                              type: string
                              maxLength: '20'
                              description: Phone number
                              example: '3003003000'
                        mobile:
                          type: string
                          description: Mobile phone number
                    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.
                additional:
                  type: object
                  description: |
                    Dynamic Object Key Value of information that you want to save with the transaction. The following keys are **NOT** allowed: `_accountNumber`, `userAgent`, `fingerprint`, `sourcePlatform`, `tokenizationID`, `trazabilyCode`, `transactionCycle`, `RequestId`, `PartnerAuthCode`, `onTest`, `threeDSEnrolled`, `threeDSAuthenticated`.
                    see more at [Additional data](/gateway/additional-data)
                metadata:
                  type: object
                  description: |
                    Dynamic object key value of additional information that external services request to be executed.
                  properties:
                    EBTDeliveryIndicator:
                      type: string
                      enum:
                        - DIRECT_DELIVERY
                        - CUSTOMER_PICKUP
                        - COMMERCIAL_SHIPPING
                        - OTHER
                        - NOT_AVAILABLE
                    openingDate:
                      type: string
                      description: Product opening date. Required in PSE transactions for merchants in the financial services category.
                      example: '2025-04-16'
                    beneficiaryId:
                      type: string
                      description: Beneficiary ID. Required in PSE transactions for merchants in the financial services category.
                      example: '12345'
                    preferredPaymentMethodIndex:
                      type: integer
                      description: Index of the Payment method to select from a list of available payment methods. This field is only required when using the Payment Orchestrator flow.
                      example: 2
                    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 confirmation prior to processing.
                      example: true
                    interestQueryCode:
                      type: string
                      description: Indicates whether the installment has information available to be applied during transaction processing. This field is valid for the **PAYSTUDIO** service, **TS** flavour, and the information must be available through the [interest inquiry service](/gateway/interests). If this value is submitted but the provided code is invalid or is not returned by that service, the transaction will be rejected.
                idempotenceKey:
                  type: string
                  description: Unique key to identify the transaction. See more at [Idempotency control](/en/gateway/idempotency)
                  example: ABCD1234
                  maxLength: 32
                notificationURL:
                  type: string
                  description: URL to which an HTTP notification with transaction information will be sent once the transaction has been processed. See more at [Notification](/en/gateway/notification)
                  example: https://your-site.com/your-notification-path
                ipAddress:
                  type: string
                userAgent:
                  type: string
                  example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
                sourcePlatform:
                  type: string
              required:
                - auth
                - payer
                - instrument
                - payment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    example: '2021-09-20T21:51:59-05:00'
                  transactionDate:
                    type: string
                    example: '2021-09-20T21:51:59-05:00'
                  internalReference:
                    type: integer
                    nullable: true
                  reference:
                    type: string
                    minLength: 1
                  paymentMethod:
                    type: string
                    nullable: true
                    minLength: 1
                  franchise:
                    type: string
                    nullable: true
                    minLength: 1
                  franchiseName:
                    type: string
                    nullable: true
                    minLength: 1
                    example: Botón Aval
                  issuerName:
                    type: string
                    minLength: 1
                    nullable: true
                    description: Name of the processing bank
                    example: Banco Bogotá
                  amount:
                    $ref: '#/components/schemas/Payment/properties/amount'
                  conversion:
                    $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema/properties/conversion'
                  authorization:
                    type: string
                    minLength: 1
                    nullable: true
                  receipt:
                    type: string
                    maxLength: 16
                    nullable: true
                  type:
                    type: string
                    minLength: 1
                    enum:
                      - AUTH_ONLY
                      - CHECKIN
                  refunded:
                    type: boolean
                    nullable: true
                  lastDigits:
                    type: string
                    minLength: 1
                    nullable: true
                  provider:
                    type: string
                    nullable: true
                    enum:
                      - ACH
                      - ATH-AVALNET
                      - ATH-MOVIL
                      - AUSTRO
                      - AVAL
                      - BANCOLOMBIA
                      - BRASPAG
                      - COMFANDI
                      - CREDIBANCO
                      - DATAFAST
                      - EBUS
                      - EVERTEC
                      - FLAMINGO
                      - INTERDIN
                      - MEDIANET
                      - PAYSTUDIO
                      - REDEBAN
                      - SABRE
                      - SUPERGIROS
                      - TECNICARD
                      - TRANSERVER
                      - TUYA-DIRECT
                  discount:
                    type: object
                    nullable: true
                    properties:
                      code:
                        type: string
                      type:
                        type: string
                      amount:
                        type: number
                      base:
                        type: number
                      percentage:
                        type: number
                  processorFields:
                    type: object
                    properties:
                      id:
                        type: string
                        nullable: true
                        example: e67122e3b9af1f7f72eacd430996d94b
                      b24:
                        type: string
                        example: '?-'
                      paymentURL:
                        type: string
                        nullable: true
                        example: https://avalpaycenter.labdigbdbstgpb.com/?trazabilityCode=000000437981
                  additional:
                    type: object
                    description: |
                      See more at [Additional data](/gateway/additional-data)
                    properties:
                      merchantCode:
                        type: string
                        nullable: true
                        description: Entity code
                      terminalNumber:
                        type: string
                        nullable: true
                        description: Payment method terminal number
                      trazabilyCode:
                        type: string
                      _wcTransactionId_:
                        type: string
                        description: Transaction identifier in commerce
                  preAuthorization:
                    type: object
                    items:
                      type: object
                      properties:
                        condition:
                          enum:
                            - ACTIVE
                            - PENDING
                            - COMPLETED
                        internalReference:
                          type: integer
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        salt:
                          type: string
                  dispersion:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                        type:
                          type: string
                          minLength: 1
                          enum:
                            - AUTH_ONLY
                        agreement:
                          type: integer
                          nullable: true
                        agreementType:
                          type: string
                          enum:
                            - AIRLINE
                            - MERCHANT
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        conversion:
                          $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema/properties/conversion'
                        refunded:
                          type: boolean
                        paymentMethod:
                          type: string
                  redirection:
                    $ref: '#/components/schemas/Redirection'
                  notificationURL:
                    type: string
                    description: URL to which an HTTP notification with transaction information will be sent once the transaction has been processed. See more at [Notification](/gateway/notification)
                    example: https://your-site.com/your-notification-path
  /gateway/tokenize:
    post:
      summary: Tokenization (tokenize)
      operationId: post-gateway-tokenize
      description: |-
        This service allows you to store a payment instrument such as: credit cards or bank account safely, through a request that contains its information, a token will be generated that can be used in the processing service and for all Indeed, in Placetopay it is equivalent to a credit card or bank account, the difference is that the token structure is sent instead of card or account.
        Prior to consuming this service, the information must be consulted to know whether or not it is necessary to generate an OTP for the client and, if necessary, request the token from the person and send it during consumption.
      tags:
        - Card tokenization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - instrument
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payer:
                  $ref: '#/components/schemas/Person'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/components/schemas/Payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
                ipAddress:
                  type: string
                userAgent:
                  type: string
            examples:
              Credit card:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    card:
                      number: '5180300000000005'
                      expiration: 12/18
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
              Cuenta bancaria:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    account:
                      bankName: Test Bank
                      bankCode: '0001234'
                      accountType: SAV
                      accountNumber: '4111111111111111'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
              Con cobro:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjBjYjc3YTYwZGZhYw==
                    seed: '2021-06-17T11:26:14-05:00'
                  payer:
                    name: John
                    surname: Doe
                    email: user_email@example.com
                  instrument:
                    card:
                      number: '5180300000000005'
                      expiration: 12/18
                      cvv: '123'
                  payment:
                    reference: TEST_PAYMENT_12345
                    amount:
                      currency: COP
                      total: '100'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  instrument:
                    $ref: '#/components/schemas/Instrument'
                  additional:
                    type: object
                    description: Object that stores additional information to tokenization response.
                    properties:
                      bin:
                        type: string
                        description: first 6 digits of the card number
              examples:
                Ok:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-06-17T11:29:37-05:00'
                    provider: CREDIBANCO
                    instrument:
                      token:
                        token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                        subtoken: fakesubtoken00005
                        franchise: master
                        franchiseName: Mastercard
                        lastDigits: '0005'
                        validUntil: '2018-12-31'
  /invalidate:
    post:
      summary: Tokenization (invalidate)
      operationId: post-gateway-tokenize
      description: This service allows you to invalidate and delete a token associated with a credit card.
      tags:
        - Card tokenization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  required:
                    - token
                  type: object
                  properties:
                    token:
                      type: object
                      required:
                        - token
                      properties:
                        token:
                          type: string
              required:
                - auth
                - instrument
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: /svw0VZ1UML5qEmaPbefQO7OXt098zOdfWsc/vHclGM=
                    nonce: NjQ0MWFlNGY0MWE1OQ==
                    seed: '2023-04-20T16:27:43-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    title: Status
                    type: object
                    description: Structure that contains information about a request or payment, informing its current status.
                    properties:
                      status:
                        type: string
                        enum:
                          - OK
                          - FAILED
                          - APPROVED
                          - APPROVED_PARTIAL
                          - PARTIAL_EXPIRED
                          - REJECTED
                          - PENDING
                          - PENDING_VALIDATION
                          - PENDING_PROCESS
                          - PENDING_CONFIRMATION
                          - REFUNDED
                          - REVERSED
                          - ERROR
                          - UNKNOWN
                          - MANUAL
                          - DISPUTE
                      reason:
                        type: string
                        minLength: '1'
                        maxLength: '4'
                      message:
                        type: string
                      date:
                        type: string
                        example: '2021-09-21T09:34:48-05:00'
              examples:
                Ok:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-06-17T11:29:37-05:00'
  /gateway/transaction:
    post:
      summary: Operations on a transaction
      operationId: post-gateway-transaction
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                description: Transaction data
                type: object
                x-examples:
                  Ejemplo:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: approved
                      date: '2021-09-20T20:10:57-05:00'
                    date: '2021-09-20T20:10:56-05:00'
                    transactionDate: '2021-09-20T20:10:56-05:00'
                    internalReference: 2
                    reference: '1234567890'
                    paymentMethod: DF_VS
                    franchise: visa
                    franchiseName: Visa
                    issuerName: Testing Bank
                    amount:
                      currency: USD
                      total: 1
                    conversion:
                      from:
                        currency: USD
                        total: 1
                      to:
                        currency: USD
                        total: 1
                      factor: 1
                    authorization: '000000'
                    receipt: '2'
                    type: AUTH_ONLY
                    refunded: 'false'
                    lastDigits: '0008'
                    provider: DATAFAST
                    discount: null
                    processorFields:
                      id: de7c331a0f5bebdd1996250296cdaf37
                      b24: '000'
                    additional:
                      merchantCode: '1000000505'
                      terminalNumber: PY100404
                      credit:
                        code: '0'
                        type: '00'
                        groupCode: C
                        installments: 0
                      totalAmount: 1
                      iceAmount: 0
                      batch: null
                      line: null
                      bin: '411076'
                      expiration: '1221'
                title: ''
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    format: date-time
                    description: 'Date when the transaction was created (ISO 8601, timezone offset required). Example: `2021-09-20T21:51:59-05:00`.'
                  transactionDate:
                    type: string
                    format: date-time
                    description: Processing date at provider (may differ from date).
                  internalReference:
                    type: number
                    description: Platform internal reference.
                    minimum: 1
                  reference:
                    type: string
                    description: Merchant order reference.
                    minLength: 1
                  paymentMethod:
                    type: string
                    description: 'Conventional format: processor_franchise (e.g., `ID_VS` for Interdin Visa, `DF_MS` for Datafast Mastercard), exceptions may exist.'
                    minLength: 5
                    maxLength: 5
                  franchise:
                    type: string
                    description: Franchise code.
                    enum:
                      - visa
                      - visa_electron
                      - amex
                      - master
                      - codensa
                      - diners
                      - jbc
                      - discover
                      - ris
                      - credencial
                      - comfama
                      - colsubsidio
                      - falabella
                      - elo
                      - somos
                      - tuya
                      - exito
                      - alkosto
                      - maestro
                      - mefia
                      - ath_card
                      - ath
                      - athmv
                      - bancolombia
                      - cooperativa
                      - debito
                      - pagoefectivo
                      - cafam
                      - efecty
                      - gana
                      - masterpass
                      - ppd
                      - pse
                      - safetypay
                      - supergiros
                      - visa_checkout
                      - procesa
                      - comfandi
                      - ach
                      - telered
                      - aval
                      - dilo
                      - banco_bogota
                      - ebt
                      - alia
                      - deuna
                  franchiseName:
                    type: string
                    description: Franchise display name.
                    minLength: 1
                  issuerName:
                    type: string
                    description: Issuing bank name.
                    minLength: 1
                    nullable: true
                  amount:
                    $ref: '#/components/schemas/Payment/properties/amount'
                  conversion:
                    $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema/properties/conversion'
                  authorization:
                    type: string
                    description: Authorization code.
                    minLength: 1
                    maxLength: 32
                    nullable: true
                  receipt:
                    type: string
                    description: Receipt / ticket number.
                    maxLength: 16
                    minLength: 1
                    nullable: true
                  type:
                    type: string
                    description: Transaction operation type.
                    minLength: 1
                    enum:
                      - AUTH_ONLY
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                      - AUTH_CAPTURE
                      - CAPTURE_ONLY
                      - CREDIT
                      - SETTLE
                      - VOID
                      - CHARGEBACK
                      - DISPUTE
                      - DISPUTE_LOSS
                      - DISPUTE_WIN
                      - DISPERSION
                      - REFUND
                      - PRE_AUTH
                      - CHECKIN
                      - CHECKOUT
                      - RE_AUTH
                      - DISPERSION_CAPTURE
                      - DISPERSION_SETTLE
                      - DISPERSION_CREDIT
                  refunded:
                    type: boolean
                    description: Refunded flag.
                  lastDigits:
                    type: string
                    description: Masked card, last digits.
                    minLength: 2
                    nullable: true
                  provider:
                    type: string
                    description: Processor/provider code.
                    enum:
                      - CREDIBANCO
                      - REDEBAN
                      - INTERDIN
                      - DATAFAST
                      - TUYA-DIRECT
                      - BRASPAG
                      - TRANSERVER
                      - SABRE
                      - EVERTEC
                      - ACH
                      - ATH-AVALNET
                      - SUPERGIROS
                      - TECNICARD
                      - MEDIANET
                      - AUSTRO
                      - COMFANDI
                      - PAYSTUDIO
                      - FLAMINGO
                      - ATH-MOVIL
                      - EBUS
                      - BANCOLOMBIA
                  discount:
                    type: object
                    nullable: true
                    description: Applied discount info.
                    properties:
                      code:
                        type: string
                        description: Discount code.
                        maxLength: 32
                      type:
                        type: string
                        description: Discount type.
                        maxLength: 32
                      amount:
                        type: number
                        description: Discount amount.
                        minimum: 0
                      base:
                        type: number
                        description: Base used.
                        minimum: 0
                      percentage:
                        type: number
                        description: Discount percent.
                        minimum: 0
                        maximum: 100
                  processorFields:
                    type: object
                    description: Raw processor fields.
                    properties:
                      id:
                        type: string
                        description: Processor id.
                        maxLength: 64
                      b24:
                        type: string
                        description: Extra field.
                  additional:
                    type: object
                    description: |
                      See more in [Additional data](/en/gateway/additional-data)
                  preAuthorization:
                    type: object
                    description: Pre-authorization segments.
                    items:
                      type: object
                      properties:
                        condition:
                          type: string
                          description: Segment condition.
                        internalReference:
                          type: number
                          description: Segment reference.
                        authorization:
                          type: string
                          description: Segment auth code.
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          description: Segment receipt.
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        salt:
                          type: string
                          description: Segment salt.
                  dispersion:
                    type: array
                    description: Dispersion splits list.
                    items:
                      type: object
                      properties:
                        status:
                          $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                        agreement:
                          type: integer
                          description: Agreement id.
                          nullable: true
                        agreementType:
                          type: string
                          description: Agreement type.
                          enum:
                            - AIRLINE
                            - MERCHANT
                        authorization:
                          type: string
                          description: Leg auth code.
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          description: Leg receipt.
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        refunded:
                          type: boolean
                          description: Leg refunded flag.
                        paymentMethod:
                          type: string
                          description: Payment method code.
                required:
                  - status
                  - provider
                  - internalReference
                  - reference
                  - paymentMethod
                  - franchise
                  - franchiseName
                  - amount
                  - authorization
                  - receipt
                  - type
                  - refunded
                  - processorFields
              examples:
                Ejemplo:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-20T21:56:29-05:00'
                    date: '2021-09-20T21:56:29-05:00'
                    transactionDate: '2021-09-20T21:56:29-05:00'
                    internalReference: 455
                    reference: '1945768'
                    paymentMethod: CR_VS
                    franchise: visa
                    franchiseName: Visa
                    issuerName: Testing Bank
                    amount:
                      taxes:
                        - kind: valueAddedTax
                          amount: 705.66
                          base: 0
                      currency: USD
                      total: 3714
                    conversion:
                      from:
                        currency: USD
                        total: 3714
                      to:
                        currency: USD
                        total: 3714
                      factor: 1
                    authorization: '000000'
                    receipt: '455'
                    type: CREDIT
                    refunded: 'false'
                    lastDigits: '0008'
                    provider: CREDIBANCO
                    discount: null
                    processorFields:
                      id: f4ec45ea4c83039384b189df2c1a6891
                      b24: '000'
                    additional:
                      merchantCode: null
                      terminalNumber: null
                      bin: '411076'
                      expiration: '1228'
                      installments: 1
        200 Confirm:
          description: Response of the a confirmation transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    description: Date of the operation request
                    example: '2021-09-20T21:56:29-05:00'
                  transactionDate:
                    type: string
                    description: Date of execution of the operation
                    example: '2021-09-20T21:56:29-05:00'
                  internalReference:
                    type: integer
                    description: Internal reference of the operation
                    nullable: true
                  type:
                    type: string
                    description: Transaction type
                    enum:
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                  transactionProcessed:
                    type: object
                    description: Object containing the information of the original processed transaction.
                    $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/transactionProcessed'
      description: Allows you to perform a reversal, re-authorization, refund, checkout, confirmation or cancellation on an existing transaction
      tags:
        - Actions on transactions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  description: Localization code
                  example: es-CO
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                action:
                  type: string
                  description: |
                    Type of operation to be performed on the transaction

                    `reverse` to reverse a transaction.

                    `reauthorization` to modify a checkin transaction.

                    `checkout` to close and collect a checkin transaction.

                    `refund` to refund a transaction.

                    `process`, to manually approve a transaction.

                    `void` to cancel processing of a transaction pending manual approval.

                    `confirm` to confirm a transaction pending confirmation.

                    `cancel` to cancel a transaction pending confirmation.
                  enum:
                    - reverse
                    - refund
                    - process
                    - void
                    - dispersion
                    - checkout
                    - reauthorization
                    - confirm
                    - cancel
                  example: reverse
                internalReference:
                  type: number
                  description: |
                    Unique internal transaction reference

                    EJ: `543423`
                authorization:
                  type: string
                  description: |
                    Transaction Authorization

                    EJ: `9999999`
                payment:
                  type: object
                  description: |
                    Structure that contains information about the payment of the transaction
                  items:
                    type: object
                    properties:
                      amount:
                        type: object
                        properties:
                          currency:
                            type: number
                            description: |
                              Alphabetical code of the currency to use (ISO 4217 alpha code)

                              EJ: `USD`
                          total:
                            type: number
                            description: |
                              Total value in indicated base currency

                              EJ: `1000` Total value in indicated base currency
                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.
                  items:
                    type: object
                    properties:
                      credit:
                        description: Selected credit to process. Available for action `confirm`
                        $ref: '#/components/schemas/CreditPerInstallment'
                metadata:
                  type: object
                  description: |
                    Dynamic key-value object of additional information required by external services to be executed.
                  properties:
                    interestQueryCode:
                      type: string
                      description: Indicates whether the installment has information available to be applied during transaction processing. This field is valid for the **PAYSTUDIO** service, **TS** flavour, and the information must be available through the [interest inquiry service](/gateway/interests). If this value is submitted but the provided code is invalid or is not returned by that service, the transaction will be rejected.
                ipAddress:
                  type: string
                  description: Client IP address
                  example: 127.0.0.1
                userAgent:
                  type: string
                  description: Customer User Agent
                  example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
              required:
                - auth
                - action
                - internalReference
              x-conditional: credit
            examples:
              Reembolso:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: MzgwYWYwMjc2ZWUzODA5YmI1MDQ1YmNjYzdlNzY1MTY=
                    seed: '2021-03-02T17:03:50+01:00'
                  internalReference: '1505723583'
                  authorization: '999999'
                  action: reverse
              Checkout:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE0ZTNiZGEzZTNlNA==
                    seed: '2021-09-24T15:58:02-05:00'
                  internalReference: '62342'
                  authorization: '580883'
                  action: checkout
                  payment:
                    amount:
                      total: '2000'
  /gateway/query:
    post:
      summary: Transaction query by internal reference
      operationId: post-rest-gateway-query
      description: Allows you to consult a particular transaction using its internal reference
      tags:
        - Query a transaction
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: ''
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                internalReference:
                  type: number
              required:
                - auth
                - internalReference
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: MzgwYWYwMjc2ZWUzODA5YmI1MDQ1YmNjYzdlNzY1MTY=
                    seed: '2021-03-02T17:03:50+01:00'
                  internalReference: '230364'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  date:
                    type: string
                    description: |
                      EJ: `2021-09-20T21:51:59-05:00`
                  transactionDate:
                    type: string
                    description: |
                      EJ: `2021-09-20T21:51:59-05:00`
                  internalReference:
                    type: number
                  reference:
                    type: string
                    minLength: 1
                  paymentMethod:
                    type: string
                    minLength: 1
                  franchise:
                    type: string
                    minLength: 1
                  franchiseName:
                    type: string
                    minLength: 1
                  issuerName:
                    type: string
                    minLength: 1
                    nullable: true
                  amount:
                    $ref: '#/components/schemas/Payment/properties/amount'
                  conversion:
                    title: AmountConversion
                    type: object
                    description: Structure to define the conversion factor and values.
                    properties:
                      from:
                        $ref: '#/paths/~1cash~1orders/post/requestBody/content/application~1json/schema/properties/payment/properties/amount'
                      to:
                        $ref: '#/paths/~1cash~1orders/post/requestBody/content/application~1json/schema/properties/payment/properties/amount'
                      factor:
                        type: number
                        example: 1
                        description: Conversion factor
                  authorization:
                    type: string
                    minLength: 1
                    nullable: true
                  receipt:
                    type: string
                    maxLength: 16
                    nullable: true
                  type:
                    type: string
                    minLength: 1
                  refunded:
                    type: boolean
                  lastDigits:
                    type: string
                    minLength: 1
                    nullable: true
                  provider:
                    type: string
                    enum:
                      - CREDIBANCO
                      - REDEBAN
                      - INTERDIN
                      - DATAFAST
                      - TUYA-DIRECT
                      - BRASPAG
                      - TRANSERVER
                      - SABRE
                      - EVERTEC
                      - ACH
                      - ATH-AVALNET
                      - SUPERGIROS
                      - TECNICARD
                      - MEDIANET
                      - AUSTRO
                      - COMFANDI
                      - PAYSTUDIO
                      - FLAMINGO
                      - ATH-MOVIL
                      - EBUS
                      - BANCOLOMBIA
                  discount:
                    type: object
                    nullable: true
                    properties:
                      code:
                        type: string
                      type:
                        type: string
                      amount:
                        type: number
                      base:
                        type: number
                      percentage:
                        type: number
                  processorFields:
                    type: object
                    properties:
                      id:
                        type: string
                      b24:
                        type: string
                  additional:
                    type: object
                    description: |
                      See more in [Additional data](/en/gateway/additional-data)
                  preAuthorization:
                    type: object
                    items:
                      type: object
                      properties:
                        condition:
                          type: string
                        internalReference:
                          type: number
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        salt:
                          type: string
                  dispersion:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                        agreement:
                          type: integer
                          nullable: true
                        agreementType:
                          type: string
                          enum:
                            - AIRLINE
                            - MERCHANT
                        authorization:
                          type: string
                          minLength: 1
                          nullable: true
                        receipt:
                          type: string
                          minLength: 1
                          nullable: true
                        amount:
                          $ref: '#/components/schemas/Payment/properties/amount'
                        refunded:
                          type: boolean
                        paymentMethod:
                          type: string
                required:
                  - status
                  - provider
                  - internalReference
                  - reference
                  - paymentMethod
                  - franchise
                  - franchiseName
                  - issuerName
                  - amount
                  - conversion
                  - authorization
                  - receipt
                  - type
                  - refunded
                  - lastDigits
                  - discount
                  - processorFields
                  - additional
              examples:
                Ejemplo:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-24T14:04:23-05:00'
                    date: '2021-09-24T10:02:17-05:00'
                    transactionDate: '2021-09-24T10:02:18-05:00'
                    internalReference: 230364
                    reference: '800166551'
                    paymentMethod: ID_DN
                    franchise: diners
                    franchiseName: Diners
                    issuerName: Diners
                    amount:
                      taxes:
                        - kind: valueAddedTax
                          amount: 0
                          base: 0
                      currency: USD
                      total: 120
                    conversion:
                      from:
                        currency: USD
                        total: 120
                      to:
                        currency: USD
                        total: 120
                      factor: 1
                    authorization: '999999'
                    receipt: '230364'
                    type: AUTH_ONLY
                    refunded: 'false'
                    lastDigits: '0008'
                    provider: INTERDIN
                    discount: null
                    processorFields:
                      id: cf3e77878a07d6e3ee667c60081dc39d
                      b24: '00'
                    additional:
                      merchantCode: '1065152'
                      terminalNumber: '00990099'
                      credit:
                        code: '1'
                        type: '03'
                        groupCode: X
                        installments: 3
                      totalAmount: 120
                      interestAmount: 0
                      installmentAmount: 40
                      iceAmount: 0
                      batch: null
                      line: null
                      bin: '365454'
                      expiration: '1122'
                    notificationURL: https://test.placetopay.ec/redirection/api/notify
        200 Confirm:
          description: Response of the a confirmation transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    title: Status
                    type: object
                    description: Estructura que contiene la información sobre una solicitud o pago, informa al estado actual de la misma.
                    properties:
                      status:
                        type: string
                        enum:
                          - OK
                          - FAILED
                          - APPROVED
                          - APPROVED_PARTIAL
                          - PARTIAL_EXPIRED
                          - REJECTED
                          - PENDING
                          - PENDING_VALIDATION
                          - PENDING_PROCESS
                          - PENDING_CONFIRMATION
                          - REFUNDED
                          - REVERSED
                          - ERROR
                          - UNKNOWN
                          - MANUAL
                          - DISPUTE
                      reason:
                        type: string
                        minLength: '1'
                        maxLength: '4'
                      message:
                        type: string
                      date:
                        type: string
                        example: '2021-09-21T09:34:48-05:00'
                  date:
                    type: string
                    description: Date of the operation request
                    example: '2021-09-20T21:56:29-05:00'
                  transactionDate:
                    type: string
                    description: Date of execution of the operation
                    example: '2021-09-20T21:56:29-05:00'
                  internalReference:
                    type: integer
                    description: Internal reference of the operation
                    nullable: true
                  type:
                    type: string
                    description: Transaction type
                    enum:
                      - AUTH_CONFIRM
                      - AUTH_CANCEL
                  transactionProcessed:
                    type: object
                    description: Object containing the information of the original processed transaction.
                    title: ''
                    properties:
                      status:
                        $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/status'
                      date:
                        type: string
                        format: date-time
                        description: 'Fecha de creación (ISO 8601 con zona). Ej: `2021-09-20T21:51:59-05:00`.'
                      transactionDate:
                        type: string
                        format: date-time
                        description: Fecha de procesamiento en el proveedor (puede diferir de date).
                      internalReference:
                        type: number
                        description: Referencia interna.
                        minimum: 1
                      reference:
                        type: string
                        description: Referencia del comercio.
                        minLength: 1
                        maxLength: 64
                      paymentMethod:
                        type: string
                        description: 'Formato convencional: procesador_franquicia (ej: `ID_VS` para Interdin Visa, `DF_MS` para Datafast Mastercard), pueden existir excepciones.'
                        minLength: 5
                        maxLength: 5
                      franchise:
                        type: string
                        description: Franquicia / marca.
                        enum:
                          - visa
                          - visa_electron
                          - amex
                          - master
                          - codensa
                          - diners
                          - jbc
                          - discover
                          - ris
                          - credencial
                          - comfama
                          - colsubsidio
                          - falabella
                          - elo
                          - somos
                          - tuya
                          - exito
                          - alkosto
                          - maestro
                          - mefia
                          - ath_card
                          - ath
                          - athmv
                          - bancolombia
                          - cooperativa
                          - debito
                          - pagoefectivo
                          - cafam
                          - efecty
                          - gana
                          - masterpass
                          - ppd
                          - pse
                          - safetypay
                          - supergiros
                          - visa_checkout
                          - procesa
                          - comfandi
                          - ach
                          - telered
                          - aval
                          - dilo
                          - banco_bogota
                          - ebt
                          - alia
                          - deuna
                      franchiseName:
                        type: string
                        description: Nombre mostrado de la franquicia.
                        minLength: 1
                      issuerName:
                        type: string
                        description: Nombre del emisor.
                        minLength: 1
                        nullable: true
                      amount:
                        title: Amount
                        type: object
                        description: Estructura que contiene la información acerca del pago de la transacción requerida al servicio web
                        required:
                          - currency
                          - total
                        properties:
                          currency:
                            type: string
                            description: |
                              Código alfabético de la moneda a usar (ISO 4217 alpha code)
                            enum:
                              - USD
                              - COP
                              - CRC
                              - EUR
                              - CAD
                              - AUD
                              - GBP
                              - MXN
                              - CLP
                            example: COP
                            minLength: 3
                            maxLength: 3
                          total:
                            type: number
                            example: 2000
                            description: |
                              Valor total en la moneda base indicada
                          taxes:
                            type: array
                            description: |
                              Estructura para definir impuestos en el proceso de pago.
                            items:
                              title: TaxDetail
                              type: object
                              description: Estructura para almacenar información sobre un impuesto.
                              properties:
                                kind:
                                  type: string
                                  example: valueAddedTax
                                  description: Tipo de impuesto reportado
                                  enum:
                                    - valueAddedTax
                                    - exciseDuty
                                    - ice
                                    - airportTax
                                    - stateTax
                                    - reducedStateTax
                                    - municipalTax
                                amount:
                                  type: number
                                  description: |
                                    Monto total del impuesto
                                base:
                                  description: |
                                    Monto base sobre el cual se calcula el impuesto
                                  type: number
                          details:
                            type: array
                            description: |
                              Estructura para definir detalles adicionales del monto en el proceso de pago.
                            items:
                              title: AmountDetail
                              type: object
                              description: Estructura para almacenar información sobre un valor adicional.
                              properties:
                                kind:
                                  type: string
                                  description: |
                                    Identificador del tipo de detalle.
                                amount:
                                  type: number
                                  description: |
                                    Monto total del detalle
                      conversion:
                        title: AmountConversion
                        type: object
                        description: Estructura para definir el factor de conversión y los valores.
                        properties:
                          from:
                            $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/transactionProcessed/properties/conversion/properties/to'
                          to:
                            title: AmountBase
                            type: object
                            description: Estructura que representa una cantidad que define la moneda y el total.
                            properties:
                              currency:
                                type: string
                                description: |
                                  Moneda acorde al ISO 4217 (alphabetic code).
                              total:
                                type: number
                                description: |
                                  Valor total.
                          factor:
                            type: number
                            example: 1
                            description: Factor de conversión
                      authorization:
                        type: string
                        description: Código de autorización.
                        minLength: 1
                        nullable: true
                      receipt:
                        type: string
                        description: Recibo / comprobante.
                        maxLength: 16
                        nullable: true
                      type:
                        type: string
                        description: Tipo de operación.
                        minLength: 1
                        enum:
                          - AUTH_ONLY
                          - AUTH_CONFIRM
                          - AUTH_CANCEL
                          - AUTH_CAPTURE
                          - CAPTURE_ONLY
                          - CREDIT
                          - SETTLE
                          - VOID
                          - CHARGEBACK
                          - DISPUTE
                          - DISPUTE_LOSS
                          - DISPUTE_WIN
                          - DISPERSION
                          - REFUND
                          - PRE_AUTH
                          - CHECKIN
                          - CHECKOUT
                          - RE_AUTH
                          - DISPERSION_CAPTURE
                          - DISPERSION_SETTLE
                          - DISPERSION_CREDIT
                      refunded:
                        type: boolean
                        description: Indicador reembolsada.
                        example: false
                      lastDigits:
                        type: string
                        description: Últimos dígitos de cuenta.
                        minLength: 2
                        nullable: true
                      provider:
                        type: string
                        description: Código del procesador/proveedor.
                        enum:
                          - CREDIBANCO
                          - REDEBAN
                          - INTERDIN
                          - DATAFAST
                          - TUYA-DIRECT
                          - BRASPAG
                          - TRANSERVER
                          - SABRE
                          - EVERTEC
                          - ACH
                          - ATH-AVALNET
                          - SUPERGIROS
                          - TECNICARD
                          - MEDIANET
                          - AUSTRO
                          - COMFANDI
                          - PAYSTUDIO
                          - FLAMINGO
                          - ATH-MOVIL
                          - EBUS
                          - BANCOLOMBIA
                          - PAGOEFECTIVO
                          - PROCESA
                          - TELERED
                          - AVAL
                          - DILO
                          - BANCO_BOGOTA
                          - BANET
                          - DEUNA
                      discount:
                        type: string
                        description: Información de descuento aplicada (si existe).
                      processorFields:
                        type: object
                        description: Campos crudos del procesador.
                        properties:
                          id:
                            type: string
                            description: Id procesador.
                            maxLength: 64
                          b24:
                            type: string
                            description: Campo extra.
                            maxLength: 64
                      additional:
                        type: object
                        description: |
                          Ver más en [Datos adicionales](/gateway/additional-data)
                      preAuthorization:
                        type: object
                        description: Segmentos de preautorización.
                        items:
                          type: object
                          properties:
                            condition:
                              type: string
                              description: Condición.
                            internalReference:
                              type: number
                              description: Ref. segmento.
                            authorization:
                              type: string
                              description: Auth segmento.
                              minLength: 1
                              nullable: true
                            receipt:
                              type: string
                              description: Recibo segmento.
                              minLength: 1
                              nullable: true
                            amount:
                              $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/transactionProcessed/properties/amount'
                            salt:
                              type: string
                              description: Salt segmento.
                      dispersion:
                        type: array
                        description: Lista de dispersiones.
                        items:
                          type: object
                          properties:
                            status:
                              $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/status'
                            agreement:
                              type: integer
                              description: Id acuerdo.
                              nullable: true
                            agreementType:
                              type: string
                              description: Tipo acuerdo.
                              enum:
                                - AIRLINE
                                - MERCHANT
                            authorization:
                              type: string
                              description: Auth. dispersión.
                              minLength: 1
                              nullable: true
                            receipt:
                              type: string
                              description: Recibo dispersión.
                              minLength: 1
                              nullable: true
                            amount:
                              $ref: '#/paths/~1gateway~1query/post/responses/200%20Confirm/content/application~1json/schema/properties/transactionProcessed/properties/amount'
                            refunded:
                              type: boolean
                              description: Dispersión reembolsada.
                              example: false
                            paymentMethod:
                              type: string
                              description: Código del método de pago.
                    required:
                      - status
                      - provider
                      - internalReference
                      - reference
                      - paymentMethod
                      - franchise
                      - franchiseName
                      - amount
                      - authorization
                      - receipt
                      - type
                      - refunded
                      - processorFields
  /gateway/search:
    post:
      summary: Transaction search
      operationId: post-gateway-search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  transactions:
                    type: array
                    uniqueItems: 'true'
                    minItems: '1'
                    items:
                      $ref: '#/paths/~1gateway~1transaction/post/responses/200/content/application~1json/schema'
                required:
                  - status
                  - transactions
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-09-20T21:51:59-05:00'
                    transactions:
                      - status:
                          status: PENDING
                          reason: '?-'
                          message: Pending transaction
                          date: '2021-09-20T21:51:59-05:00'
                        date: '2021-09-20T21:51:59-05:00'
                        transactionDate: '2021-09-20T21:51:59-05:00'
                        internalReference: 453
                        reference: TEST_3
                        paymentMethod: ID_VS
                        franchise: visa
                        franchiseName: Visa
                        issuerName: Testing Bank
                        amount:
                          taxes:
                            - kind: valueAddedTax
                              amount: 3.27
                              base: 0
                          currency: USD
                          total: 17.2
                        conversion:
                          from:
                            currency: USD
                            total: 17.2
                          to:
                            currency: USD
                            total: 17.2
                          factor: 1
                        authorization: null
                        receipt: null
                        type: AUTH_ONLY
                        refunded: 'false'
                        lastDigits: '0008'
                        provider: INTERDIN
                        discount: null
                        processorFields:
                          id: a9cb4b7a7aa03f681a0545ba6807e1fc
                          b24: '?-'
                        additional:
                          merchantCode: '000468232'
                          terminalNumber: '00990101'
                          credit: null
                          totalAmount: 17.2
                          interestAmount: 0
                          installmentAmount: 0
                          iceAmount: 0
                          batch: null
                          line: null
                          bin: '411076'
                          expiration: '1228'
                      - status:
                          status: PENDING
                          reason: '?-'
                          message: Pending transaction
                          date: '2021-09-20T21:51:59-05:00'
                        date: '2021-09-20T21:51:59-05:00'
                        transactionDate: '2021-09-20T21:51:59-05:00'
                        internalReference: '452'
                        reference: TEST_3
                        paymentMethod: ID_VS
                        franchise: visa
                        franchiseName: Visa
                        issuerName: Testing Bank
                        amount:
                          taxes:
                            - kind: valueAddedTax
                              amount: 3.27
                              base: 0
                          details:
                            - kind: shipping
                              amount: 100
                          currency: USD
                          total: 17.2
                        conversion:
                          from:
                            currency: USD
                            total: 17.2
                          to:
                            currency: USD
                            total: 17.2
                          factor: 1
                        authorization: null
                        receipt: null
                        type: AUTH_ONLY
                        refunded: 'false'
                        lastDigits: '0008'
                        provider: INTERDIN
                        discount: null
                        processorFields:
                          id: cbc65da9667ca078dc774cad2fd510e4
                          b24: '?-'
                        additional:
                          merchantCode: '000468232'
                          terminalNumber: '00990101'
                          credit: null
                          totalAmount: 17.2
                          interestAmount: 0
                          installmentAmount: 0
                          iceAmount: 0
                          batch: null
                          line: null
                          bin: '411076'
                          expiration: '1228'
      tags:
        - Query a transaction
      description: This service must be consumed if the card requires interest to be displayed (`displayInterest` set to `true`) or its credit conditions allow it (see condition in [Credits by provider](/en/gateway/additional-data/#additional-data-credit-providers)). It is available for flows that expose interest calculation, including Ecuador and Chile with PAYSTUDIO `TS` flavour.
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                reference:
                  type: string
                  minLength: 1
                amount:
                  $ref: '#/components/schemas/Payment/properties/amount'
              required:
                - auth
                - reference
                - amount
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: +FSGHsW3e6WrrHcIdBmqI+j6FFeUN4bidfPL7LeZgvE=
                    nonce: N2YzMGM1M2QxOTU3YzZmMzVlYmIzZTAyOGMwNjNkMmU=
                    seed: '2021-03-03T19:40:37+01:00'
                  reference: TEST_20171108_144400
                  amount:
                    currency: COP
                    total: 1000
  /gateway/interests:
    post:
      summary: Interest Calculation
      operationId: post-rest-gateway-interests
      description: This service must be consumed if the card requires interest to be displayed (`displayInterest` set to `true`). It is available for flows that expose interest calculation, including Ecuador and Chile with PAYSTUDIO `TS` flavour. In PAYSTUDIO `TS` flavour, send the selected installment in `instrument.credit.installment` together with the `kind` returned by the information service.
      tags:
        - Get information
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  values:
                    $ref: '#/components/schemas/InterestValues'
                  conversion:
                    $ref: '#/paths/~1gateway~1query/post/responses/200/content/application~1json/schema/properties/conversion'
                  additional:
                    type: object
                    description: Interest additional information.
                    properties:
                      interestQueryCode:
                        type: string
                        description: Indicates whether the installment contains additional information that must be considered during transaction processing. This field applies only to **Paystudio TS**. When this field is returned, the `metadata.interestQueryCode` value must also be explicitly included in the processing request so that the information obtained from the installment inquiry can be applied.
                        nullable: true
    parameters: null
  /gateway/otp/generate:
    post:
      summary: OTP generation (Ecuador only)
      operationId: post-rest-otp-generate
      description: This service is consumed if the OTP is required for the card provided by the client (requireOtp is true) and the user must be allowed to enter the OTP to send it later in the processing service, as an example this is captured in the interface redirection
      tags:
        - Proceso OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: q/7k0WUshvLEpQ5gqNWqne+ZfWXSXUP/b7T80TuAUSY=
                    nonce: NjE0YTM3OGIwNjA2NA==
                    seed: '2021-09-21T14:50:35-05:00'
                  payer:
                    name: John
                    email: user_email@example.com
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: USD
                      total: '3'
                  instrument:
                    card:
                      number: '36545400000008'
                      expiration: 12/20
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-09-21T14:52:28-05:00'
                    provider: INTERDIN
                No Requerido:
                  value:
                    status:
                      status: REJECTED
                      reason: NR
                      message: OTP is not required with this card
                      date: '2021-09-21T14:53:21-05:00'
                    provider: INTERDIN
  /gateway/otp/validate:
    post:
      summary: OTP validation (Ecuador only)
      operationId: post-rest-otp-validate
      description: |-
        It allows you to validate that the OTP provided matches the one sent by the provider and will provide a signature that serves to authenticate the transaction
        > Important Note > > It is necessary to send the returned value as `signature` in the response as `instrument.otp` in the processing request so that it is recorded in the transaction
      tags:
        - OTP process
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/components/schemas/Payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
            examples:
              Ejemplo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: q/7k0WUshvLEpQ5gqNWqne+ZfWXSXUP/b7T80TuAUSY=
                    nonce: NjE0YTM3OGIwNjA2NA==
                    seed: '2021-09-21T14:50:35-05:00'
                  payer:
                    name: John
                    email: user_email@example.com
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: USD
                      total: '3'
                  instrument:
                    card:
                      number: '36545400000008'
                      expiration: 12/20
                      cvv: '123'
                    otp: '123456'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  provider:
                    type: string
                  signature:
                    type: string
                    nullable: 'true'
                  validated:
                    type: boolean
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: OTP Validation successful
                      date: '2021-09-21T15:12:01-05:00'
                    provider: INTERDIN
                    signature: a586077cd77ec2dbcb9b7f68b896368a
                    validated: 'true'
                Errado:
                  value:
                    status:
                      status: FAILED
                      reason: OT1
                      message: The OTP entered does not match the one provided to you
                      date: '2021-09-21T15:14:41-05:00'
                    provider: INTERDIN
                    signature: null
                    validated: 'false'
  /gateway/report:
    post:
      summary: Request a report
      operationId: post-report
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  id:
                    type: number
                required:
                  - status
                  - id
              examples:
                example:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2020-01-18T18:00:00-05:00'
                    id: '1231'
                error:
                  value:
                    status:
                      status: FAILED
                      reason: BR
                      message: The requested report exceeds 10 days
                      date: '2020-01-18T18:00:00-05:00'
                    id: '0'
      description: Allows you to request that a transaction report be generated and returns an identifier for the process, which once the callback is called can be obtained at the following endpoint
      tags:
        - Report of operations carried out
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                filters:
                  type: object
                  required:
                    - startDate
                    - endDate
                    - processStartDate
                    - processEndDate
                  properties:
                    startDate:
                      type: string
                      format: date-time
                      example: '2021-01-10T18:01:27-05:00'
                      description: This field is required if processingStartDate is not sent
                    endDate:
                      type: string
                      format: date-time
                      example: '2021-01-12T18:01:27-05:00'
                    processStartDate:
                      type: string
                      format: date-time
                      example: '2021-01-10T18:01:27-05:00'
                      description: |-
                        This field is required if startDate is not sent.

                        It allows filtering by the transaction processing date.
                    processEndDate:
                      type: string
                      format: date-time
                      example: '2021-01-12T18:01:27-05:00'
                    state:
                      type: array
                      description: 'It allows you to define the status of the transactions in the report, it is a an arrangement: APPROVED, REJECTED, FAILED and PENDING'
                      items:
                        type: string
                        example: '[''APPROVED'', ''REJECTED'']'
                        enum:
                          - APPROVED
                          - REJECTED
                          - PENDING
                          - FAILED
                    type:
                      type: array
                      description: 'It allows you to define the type of the transactions in the report, it an arrangement:  AUTH_ONLY, CAPTURE_ONLY, CREDIT, REFUND, SETTLE, AUTH_CAPTURE, VOID, DISPUTE, CHARGEBACK, DISPUTE_LOSS, DISPUTE_WIN, PRE_AUTH, CHECKIN, CHECKOUT, RE_AUTH'
                      items:
                        type: string
                        example: '[''AUTH_ONLY'', ''CHARGEBACK'']'
                        enum:
                          - AUTH_ONLY
                          - CAPTURE_ONLY
                          - CREDIT
                          - REFUND
                          - SETTLE
                          - AUTH_CAPTURE
                          - VOID
                          - DISPUTE
                          - CHARGEBACK
                          - DISPUTE_LOSS
                          - DISPUTE_WIN
                          - PRE_AUTH
                          - CHECKIN
                          - CHECKOUT
                          - RE_AUTH
                callbackUrl:
                  type: string
                  format: uri
              required:
                - auth
                - filters
            examples:
              Basic:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: cV5MJlkUgPq/BLG40M1Cp2mSkJcZg7FPL4FBxKo+t5A=
                    nonce: NjQ4MjMzMjY0MDIyYw==
                    seed: '2023-06-08T14:59:34-05:00'
                  filters:
                    startDate: '2023-06-07 14:59:34'
                    endDate: '2023-06-08 14:59:34'
                  callbackUrl: https://dnetix.co/ping/report
              Con estado:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: cV5MJlkUgPq/BLG40M1Cp2mSkJcZg7FPL4FBxKo+t5A=
                    nonce: NjQ4MjMzMjY0MDIyYw==
                    seed: '2023-06-08T14:59:34-05:00'
                  filters:
                    startDate: '2023-06-07 14:59:34'
                    endDate: '2023-06-08 14:59:34'
                    state:
                      - APPROVED
                      - REJECTED
                  callbackUrl: https://dnetix.co/ping/report
  /gateway/report/obtain:
    post:
      summary: Obtain a previously requested report
      operationId: post-report-obtain
      responses:
        '200':
          description: |-
            OK
            Once the report is available, the information is returned, which is a file separated by tabs with the following headers
            The type field is added if report use the type filter
            ``` id date transaction_date reference currency_code amount tax payment_method internal_reference status reason merchant terminal authorization refunded installments last_digits bank_currency bank_factor bank_amount issuer_name payer_document payer_first_name payer_last_name payer_email ip_address batch_number line_number type ```
          content:
            text/plain:
              schema:
                type: string
              examples:
                example:
                  value: "id\tdate transaction_date\t\treference\tcurrency_code\t\tamount tax payment_method\tinternal_reference\t status\t\treason merchant\t\tterminal\t authorization refunded\t\tinstallments\t last_digits\t bank_currency bank_factor bank_amount issuer_name payer_document\tpayer_first_name payer_last_name payer_email ip_address\tbatch_number line_number\t type c42977b5d4ff9d9613320c7ee98e9eb0\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t4113943\t\tUSD\t\t2327\t 442.13\t\tID_VS\t221\t\t\t APPROVED\t 000468232\t00990101\t\t\t\t1 0008\t\tUSD\t\t1\t2327 Testing Bank\t\t32694548\t Miss Joanne Fadel MD\tPrice\t\tuser@example.com 237.234.250.30\tAUTH_ONLY 315c9ca9e64bed46f24a2e18bdd76468\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t8122\t USD\t 4457\t846.83\t ID_VS 222 \t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 4457\t\tTesting Bank\t 44056172\tCharlotte Maggio Steuber user@example.com\t 164.233.22.247\tAUTH_ONLY fd239e99125c326e92137197fd5d1959\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t753446151\tUSD\t3798 721.62\tID_VS\t\t223\t\t\t\t APPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t3798\t Testing Bank\t51751981 Mr. Abdiel Schroeder DDS\t\tMcKenzie\t leonard.beier@runte.com\t 250.136.231.200\t\tAUTH_ONLY be945b27ff13291409b929cc9cb15274\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t482657 USD 1401\t\t266.19 ID_VS\t 224\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 1401\tTesting Bank 98958097\t\tDr. Mia Abshire\t\tDouglas\t\tantonia.blanda@wyman.com\t 32.1.213.30 \tAUTH_ONLY 3aaa74df49cf3634276675c95e49f2af\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t77616851\t USD\t 1921\t364.99\t ID_VS 225 \t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 1921\t\tTesting Bank\t 6211299\t Dr. Marcelina Huel I\tConsidine\t\tvlangworth@emard.biz\t 249.218.136.4\tAUTH_ONLY 6e89e692975bb117db78360c8ebf0a00\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t74141\tUSD\t773\t146.87\t ID_VS 226 \t\t\t\tAPPROVED\t\t 000468232 00990101\t\t\t\t 1\t\t0008\t USD\t 1 773 Testing Bank\t\t22736252\t Melody Goodwin DDS\t\tGerlach\t\tiblock@ohara.com\t 168.87.8.132\tAUTH_ONLY b50e4e8cca851a578fa40917030397a3\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t828\t\tUSD\t\t473\t\t89.87\tID_VS\t\t227\t\t\t\t\tAPPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t473\t\tTesting Bank\t 9397147\t Freeman Kirlin\t\tAufderhar\tdrobel@kshlerin.com\t21.185.38.170\t\tAUTH_ONLY b66ffe1bff91a15986cba677bbaeaa7f\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t581122 USD 1767\t\t335.73 ID_VS\t 228\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 1767\tTesting Bank 62818359\t\tMrs. Rosina Mann\t Schaefer\tuser@example.com\t15.8.188.238 \tAUTH_ONLY 135afcb2f872cf55168461e7e874242a\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t3896507\t\tUSD\t\t7\t1.33 ID_VS\t 229\t\t\t\t\tAPPROVED\t 0468232\t 00990101\t\t\t 1\t0008 USD 1\t 7 Testing Bank\t\t10597030\t Kristy Purdy IV\t Mills user@example.com 148.232.85.97 \tAUTH_ONLY 19868ea1110eca766186806ef0e38f71\t\t2021-01-13T01:54:50-05:00\t2021-01-13T01:54:50-05:00\t\t68490\tUSD\t4987 947.53\tID_VS\t\t230\t\t\t\t APPROVED\t 000468232\t\t00990101\t\t\t1\t 0008\tUSD\t1\t\t4987\t Testing Bank\t32385057 Mr. Harley Howe Rogahn\tuser@example.com 87.121.113.190\t\tAUTH_ONLY\t "
        '425':
          description: When the request is made before the report is finished generating
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                id:
                  type: number
              required:
                - auth
                - id
        description: ''
      description: Allows you to obtain a previously generated report
      tags:
        - Report of operations carried out
      parameters:
        - schema:
            type: string
            enum:
              - gzip
          in: header
          name: accept-encoding
          description: Allows to provide gzip as a compression format
  /gateway/mpi/lookup:
    post:
      summary: 3DS Lookup
      operationId: post-mpi-lookup
      description: Performs the initial 3DS validation process by returning the data so that the user can continue with the process
      tags:
        - 3DS Process
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                userAgent:
                  type: string
                  description: User Agent Information
                  example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36
                buyer:
                  $ref: '#/components/schemas/Buyer'
                payer:
                  $ref: '#/components/schemas/Payer'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                payment:
                  $ref: '#/components/schemas/Payment'
                subscription:
                  $ref: '#/components/schemas/Subscription'
                version:
                  type: string
                  nullable: true
                  description: 3DS version on which the request is being processed.
                  enum:
                    - v2
                    - v2x
                returnUrl:
                  type: string
                  format: uri
                  maxLength: 250
                  description: Return URL to regain user control
                additional:
                  type: object
                  properties:
                    initiatorIndicator:
                      type: string
                      description: Actor that generates the transaction. It can be AGENT when it is different from the cardholder
                      nullable: true
                      enum:
                        - AGENT
                metadata:
                  type: object
                  properties:
                    merchantRiskIndicator:
                      type: object
                      description: Object containing information related to the merchant's assessment of the level of fraud  risk for a specific authentication. ncluding this additional data in the request allows for a more  accurate assessment, which can significantly improve the authentication success rate.
                      properties:
                        deliveryEmailAddress:
                          type: string
                          maxLength: 254
                          description: For electronic delivery, the email address to which the merchandise was delivered.
                          nullable: true
                        deliveryTimeframe:
                          type: string
                          enum:
                            - ELECTRONIC_DELIVERY
                            - SAME_DAY_SHIPPING
                            - OVERNIGHT_SHIPPING
                            - TWO_DAYS_OR_MORE_SHIPPING
                          description: Indicates the delivery time of the merchandise.
                          nullable: true
                          example: ELECTRONIC_DELIVERY
                        giftCardAmount:
                          type: string
                          maxLength: 15
                          description: For gift card or prepaid purchases, the total amount of the gift card or prepaid purchase in major units (e.g., $123.45 is 123).
                          nullable: true
                          example: '123'
                        giftCardCount:
                          type: string
                          maxLength: 2
                          description: For gift card or prepaid purchases, total count of cards, individual gift or prepaid codes purchased.
                          nullable: true
                          example: '10'
                        giftCardCurrency:
                          type: string
                          maxLength: 3
                          description: For gift card or prepaid purchases, the gift card's ISO 4217 three-digit currency code.
                          nullable: true
                          example: '021'
                        preOrderDate:
                          type: string
                          format: YYYY-MM-DD
                          description: For a pre-order purchase, the expected date the merchandise will be available.
                          nullable: true
                          example: '2025-10-08'
                        preOrderPurchaseIndicator:
                          type: string
                          enum:
                            - MERCHANDISE_AVAILABLE
                            - FUTURE_AVAILABILITY
                          description: Indicates whether the cardholder is ordering merchandise with a future availability or release date.
                          nullable: true
                          example: FUTURE_AVAILABILITY
                        reOrderItemsIndicator:
                          type: string
                          enum:
                            - REORDERED
                            - FIRST_TIME_ORDERED
                          description: Indicates whether the cardholder is reordering previously purchased merchandise.
                          nullable: true
                          example: REORDERED
                        shipIndicator:
                          type: string
                          enum:
                            - SHIP_TO_CARDHOLDER_BILLING_ADDR
                            - SHIP_TO_ANOTHER_VERIFIED_ADDR_ON_FILE
                            - SHIP_TO_ADDR_DIFF_CARDHOLDER_BILLING_ADDR
                            - SHIP_TO_STORE
                            - DIGITAL_GOODS
                            - TRAVEL_EVENT_TICKETS_NOT_SHIPPED
                            - OTHER
                          description: Indicates the shipping method chosen for the transaction.
                          nullable: true
                          example: SHIP_TO_STORE
                    cardholderAccountInformation:
                      type: object
                      description: Object that contains additional information about the cardholder's account. Including  this additional data in the request allows for a more accurate assessment, which can significantly  improve the authentication success rate.
                      properties:
                        cardholderAccountAgeIndicator:
                          type: string
                          description: Length of time the account was created on the merchant's website.
                          enum:
                            - NO_ACCOUNT
                            - CREATED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          nullable: true
                          example: LESS_30_DAYS
                        cardholderAccountChangeDate:
                          type: string
                          format: YYYY-MM-DD
                          description: Date of the last change made to the cardholder's account on the merchant's website.
                          nullable: true
                          example: '2025-12-29'
                        cardholderAccountChangeIndicator:
                          type: string
                          enum:
                            - CHANGED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Length of time since the last change was made to the account on the merchant's website.
                          nullable: true
                          example: MORE_60_DAYS
                        cardholderAccountDate:
                          type: string
                          format: YYYY-MM-DD
                          description: Date of the last password change or reset.
                          nullable: true
                          example: '2025-08-01'
                        cardholderAccountPasswordChangeIndicator:
                          type: string
                          enum:
                            - NO_CHANGE
                            - CHANGED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Length of time since the last password change or recovery.
                          nullable: true
                          example: MORE_60_DAYS
                        cardholderPurchaseCount:
                          type: string
                          maxLength: 4
                          description: Number of purchases during the last 6 months.
                          nullable: true
                          example: '1234'
                        addCardAttemptsDay:
                          type: string
                          description: Number of attempts to add cards in the last 24 hours.
                          maxLength: 3
                          nullable: true
                          example: '05'
                        trxActivityDay:
                          description: Number of transactions (successful and abandoned) for this account in the last 24 hours.
                          type: string
                          maxLength: 3
                          nullable: true
                          example: '05'
                        trxActivityYear:
                          description: Number of transactions (successful and abandoned) for this account in the last year.
                          type: string
                          maxLength: 3
                          nullable: true
                          example: '123'
                        paymentAccountAge:
                          type: string
                          format: YYYY-MM-DD
                          description: Date the payment method was added to the user's account on the merchant's website.
                          nullable: true
                          example: '2025-04-04'
                        paymentAccountIndicator:
                          type: string
                          enum:
                            - NO_ACCOUNT
                            - CREATED_DURING_TRANSACTION
                            - LESS_30_DAYS
                            - BETWEEN_30_AND_60_DAYS
                            - MORE_60_DAYS
                          description: Length of time since the payment method was enrolled in the account on the merchant's website.
                          nullable: true
                          example: MORE_60_DAYS
                        shipAddressUsage:
                          type: string
                          format: YYYY-MM-DD
                          description: Date the delivery address was first used on the merchant's website.
                          nullable: true
                          example: '2025-04-04'
                        shipNameIndicator:
                          type: string
                          enum:
                            - ACCOUNT_NAME_IDENTICAL_SHIPPING_NAME
                            - ACCOUNT_NAME_DIFFERENT_SHIPPING_NAME
                          description: Indicates whether the cardholder name is the same as the shipping name used in this transaction.
                          nullable: true
                          example: ACCOUNT_NAME_DIFFERENT_SHIPPING_NAME
                        suspiciousAccountActivity:
                          type: string
                          enum:
                            - NO_SUSPICIOUS_ACTIVITY_OBSERVED
                            - SUSPICIOUS_ACTIVITY_OBSERVED
                          description: Indicates whether the merchant has experienced suspicious activity (including prior fraud) on the cardholder's account.
                          nullable: true
                          example: NO_SUSPICIOUS_ACTIVITY_OBSERVED
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/LookupResponseDataV2X'
                      - $ref: '#/components/schemas/LookupResponseDataV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
  /gateway/mpi/query:
    post:
      summary: 3DS Query
      operationId: post-mpi-query
      tags:
        - 3DS process
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
                id:
                  type: string
                  description: Identifier returned in the initial lookup on which the query is to be made.
              required:
                - auth
                - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    $ref: '#/components/schemas/Instrument/properties/threeDS'
                required:
                  - status
                  - data
  /gateway/balance:
    post:
      summary: Service to obtain the balance
      operationId: post-rest-gateway-balance
      description: This service allows you to check the balance and must be used when the payment method requires it ('requireBalance' flag in information service response set to 'true').
      tags:
        - Get information
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/BalanceInstrument'
                payment:
                  $ref: '#/components/schemas/Payment'
            examples:
              Consumo:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: E0gHh8C6fceHnbsLlgBq2n7nRNjr8MVPcz0um1ZYCfs=
                    nonce: NjE0YjUwZGNlYjJiNA==
                    seed: '2021-09-22T10:50:52-05:00'
                  payment:
                    reference: '1234567890'
                    amount:
                      currency: CRC
                      total: '1000'
                  instrument:
                    card:
                      number: '4111111111111111'
                      expiration: 12/30
                      cvv: '123'
                  ipAddress: 127.0.0.1
                  userAgent: Testing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  total:
                    type: number
                    example: '4973.19'
              examples:
                Ejemplo:
                  value:
                    status:
                      status: OK
                      reason: '00'
                      message: The request has been processed successfully
                      date: '2021-09-22T16:08:19-05:00'
                    total: 42563.36
        '400':
          description: FAILED
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
              examples:
                Ejemplo:
                  value:
                    status:
                      status: FAILED
                      reason: BR
                      message: The instrument.card.expiration field is required.
                      date: '2024-11-01T07:12:57-05:00'
  /security/pinpad/transaction:
    post:
      summary: Pinpad Request
      operationId: post-rest-security-transaction
      description: |-
        A PINPAD is an electronic device used in a debit, credit, or smart card transaction to accept and encrypt the cardholder's personal identification number (PIN).
        This API provides a PinPad service with encrypted PinBlock generation according to ISO 9564.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              Solicitud por tarjeta:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    card:
                      number: '4111111111111111'
              Solicitud por token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    properties:
                      pinPad:
                        $ref: '#/components/schemas/PinPad'
              examples:
                Respuesta exitosa:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: approved
                      date: '2021-09-14T17:43:48-05:00'
                    data:
                      pinPad:
                        positions: '7915864032'
                        transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                        pinLength: '4'
                Error:
                  value:
                    status:
                      status: FAILED
                      reason: '0'
                      message: ''
                      date: '2021-09-22T16:53:48-05:00'
                Rechazo:
                  value:
                    status:
                      status: REJECTED
                      reason: '05'
                      message: The required service is not available on the site
                      date: '2021-09-27T09:35:03-05:00'
                Service unavailable:
                  value:
                    status:
                      status: REJECTED
                      reason: SU
                      message: The required service is not available on the site
                      date: '2021-09-27T09:35:03-05:00'
      tags:
        - Pinpad Operations
  /security/pinpad/pinblock:
    post:
      summary: Generation of PinBlock from Pinpad
      operationId: post-rest-security-pinblock
      description: Allows you to generate the PinBlock with a transaction based on the positions provided by the user that were selected from the PinPad
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  $ref: '#/components/schemas/Instrument'
            examples:
              PinBlock request by card:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    card:
                      number: '0215020177972730'
                    pinPad:
                      transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                      positions: '0123'
              PinBlock request by token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                    pinPad:
                      transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                      positions: '0123'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    properties:
                      pinPad:
                        $ref: '#/components/schemas/PinPad'
              examples:
                Successful generation:
                  value:
                    status:
                      status: APPROVED
                      reason: '00'
                      message: Aprobada
                      date: '2021-09-14T17:43:48-05:00'
                    data:
                      pinPad:
                        positions: '0123'
                        transactionId: b0c62f97-3b06-4c33-b68f-e281e95eb4bb
                        pinBlock: 106C56A4819B68EA
                        pinLength: '4'
                Error:
                  value:
                    status:
                      status: FAILED
                      reason: '0'
                      message: ''
                      date: '2021-09-22T16:53:48-05:00'
                Rechazo:
                  value:
                    status:
                      status: REJECTED
                      reason: '05'
                      message: The required service is not available on the site
                      date: '2021-09-27T09:35:03-05:00'
                Service unavailable:
                  value:
                    status:
                      status: REJECTED
                      reason: SU
                      message: The required service is not available on the site
                      date: '2021-09-27T09:35:03-05:00'
            application/xml:
              schema:
                title: Authentication
                type: object
                properties:
                  login:
                    type: string
                    description: Site identifier
                  tranKey:
                    type: string
                    description: Generated **tranKey** credential
                  nonce:
                    type: string
                    description: |
                      **Random** value for each request encoded in **Base64**.
                  seed:
                    type: string
                    description: |
                      **Timestamp**, in **ISO 8601** format.
                description: Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1
      tags:
        - Operaciones con Pinpad
  /cash/orders:
    post:
      summary: Search payment orders
      operationId: post-gateway-search-cashorder
      description: This service allows consulting payment orders by reference, total and currency.
      tags:
        - Payment order operations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - payment
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                payment:
                  title: Payment data
                  type: object
                  properties:
                    reference:
                      title: Payment reference
                      type: string
                    amount:
                      title: AmountBase
                      type: object
                      description: Structure that represents an amount that defines the currency and the total.
                      properties:
                        currency:
                          type: string
                          description: |
                            Currency according to ISO 4217 (alphabetic code).
                        total:
                          description: |
                            Total value.
                          type: number
                  required:
                    - reference
                    - amount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: array
                    description: Structure that contains the cash orders found. If no records were found matching the provided filters it will be an empty array.
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        status:
                          type: string
                          enum:
                            - PAYED
                            - EXPIRED
                            - ACTIVE
                        payment:
                          type: object
                          properties:
                            reference:
                              type: string
                            description:
                              type: string
                            amount:
                              $ref: '#/components/schemas/Payment/properties/amount'
                            allowPartial:
                              type: boolean
                            subscribe:
                              type: boolean
                        createdAt:
                          type: string
                        expirationDate:
                          type: string
                        notificationUrl:
                          type: string
                        sessionId:
                          type: number
  /cash/delete:
    post:
      summary: Delete cash order
      operationId: post-gateway-delete-cashorder
      description: This service allows deleting pending cash orders.
      tags:
        - Payment order operations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - id
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                id:
                  type: number
                  description: Cash order id.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  id:
                    type: number
                    description: Deleted cash order id.
  /gateway/token:
    post:
      summary: Query token
      operationId: post-gateway-search-token
      description: This service allows you to search for a token by the value of the token or subtoken.
      tags:
        - Card tokenization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - instrument
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  title: Instrument
                  type: object
                  properties:
                    token:
                      title: Token
                      type: object
                      description: Structure containing the tokenization information to be searched.
                      properties:
                        id:
                          type: number
                          description: Token identifier in the system.
                        token:
                          type: string
                          description: Code generated to identify the card in the system.
                        subtoken:
                          type: string
                          description: Alternate code generated to identify the card.
                  required:
                    - token
            examples:
              Consulta por token:
                value:
                  auth:
                    login: aabbccdd1234567890aabbccdd123456
                    tranKey: ABC123example456trankey+789abc012def3456ABC=
                    nonce: NjE1MWQ4MDE5YWViMw==
                    seed: '2021-09-27T09:41:05-05:00'
                  instrument:
                    token:
                      token: faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    description: Object with token information.
                    properties:
                      id:
                        type: number
                        description: Tokenization identifier.
                      type:
                        type: string
                        description: Tokenization type.
                      token:
                        type: string
                        description: Code generated to identify the card within the system.
                      subtoken:
                        type: string
                        description: Alternative code used to identify the card.
                      franchise:
                        type: string
                        description: Card franchise
                      franchiseName:
                        type: string
                        description: Name of the card franchise
                      issuerName:
                        type: string
                        description: Name of the card issuer bank
                      lastDigits:
                        type: string
                        description: Last digits of the card
                      validUntil:
                        type: string
                        format: date
                        description: Card expiration date
                      owner:
                        type: string
                        description: Cardholder's name
                      bin:
                        type: string
                        description: First 6 digits of the card number
                      accountType:
                        type: string
                        description: ACH account type (SAV, DDA, CCD), applies only to Puerto Rico
                      isPromotedToBrandToken:
                        type: boolean
                        description: Indicates whether the token has been promoted to a brand token. Applies only if the site has brand tokenization integration enabled.
              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
  /gateway/account-validator/session:
    post:
      summary: Create Session
      description: This endpoint allows creating a session for account validation
      operationId: create-session
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - user
                - returnUrl
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                user:
                  type: object
                  description: |
                    User owner of the account to validate
                  required:
                    - name
                    - email
                  properties:
                    name:
                      type: string
                      description: |
                        First name or names of the user owner of the account
                      maxLength: 50
                      example: John
                    surname:
                      type: string
                      description: |
                        Surname of the user owner of the account
                      maxLength: 50
                      example: Doe
                    email:
                      type: email
                      description: |
                        Email of the user owner of the account
                      maxLength: 80
                      example: John.doe@test.com
                returnUrl:
                  type: string
                  description: |
                    Return URL once the account validation process is completed
                  maxLength: 255
                  example: https://www.placetopay.com/return
                locale:
                  type: string
                  description: Determines the language of the response
                  maxLength: 5
                  example: es_CO
                isAuthenticated:
                  type: boolean
                  description: Determines if an external authentication process has already been completed. The intention is not to validate the user's email twice. By default it is false, meaning that an OTP will be sent to validate the user if they have already validated accounts with microdeposits in the system
                  example: true
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: |
                      Structure containing the response to the request in the case of a successful status
                    properties:
                      requestId:
                        type: string
                        description: |
                          Unique identifier of the session you want to consult.
                        maxLength: 36
                        format: regex
                        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                        example: 9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea
                      redirectUrl:
                        type: string <url>
                        description: Redirect URL to the account validator
                        example: https://dev-account-validator.placetopay.ws/verification/redirect/9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea
                      expiresAt:
                        type: string
                        description: Expiration date of the session
                        example: '2024-04-19 17:36:57'
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
        '400':
          description: |
            Invalid request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
  /gateway/account-validator/query:
    post:
      summary: Check session status
      description: This endpoint will allow you to consult the status of the created session.
      operationId: check-session-status
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - requestId
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                requestId:
                  type: string
                  description: Unique identifier of the session you want to consult.
                  maxLength: 36
                  format: regex
                  pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  example: 1f630ff7-9c02-4da4-82d4-d676709acb21
      responses:
        '200':
          description: Session status checked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                  data:
                    type: object
                    description: Structure containing the response to the request in the case of a successful status
                    properties:
                      requestId:
                        type: string
                        description: Unique identifier of the session you want to consult.
                        maxLength: 36
                        format: regex
                        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                        example: 1f630ff7-9c02-4da4-82d4-d676709acb21
                      expiresAt:
                        type: string
                        description: Expiration date of the session
                        example: '2022-08-30 15:19:33'
                      isAuthenticated:
                        type: boolean
                        description: Indicates if the user has already completed an external authentication process
                        example: true
                      token:
                        $ref: '#/components/schemas/Token'
        '400':
          description: |
            Invalid request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
  /gateway/account-validator/validate:
    post:
      summary: Validate existing account
      description: Once the initial session creation is successfully completed, you can perform validations to the account as many times as you consider necessary, you only need to have the account information and the verification code delivered in the previous process.
      operationId: validate-existing-account
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              required:
                - auth
                - instrument
              properties:
                auth:
                  $ref: '#/paths/~1security~1pinpad~1pinblock/post/responses/200/content/application~1xml/schema'
                instrument:
                  type: object
                  description: Token on which the validation will be performed.
                  required:
                    - token
                  properties:
                    token:
                      type: object
                      description: The token or subtoken of the account to be validated is required.
                      properties:
                        token:
                          type: string
                          examples:
                            - faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891
                        subtoken:
                          type: string
                          examples:
                            - fakesubtoken00005
                payment:
                  type: object
                  description: Structure containing payment information.
                  required:
                    - name
                    - email
                  properties:
                    amount:
                      type: object
                      description: Structure containing payment information.
                      properties:
                        currency:
                          type: string
                          description: Currency of the payment.
                          minLength: 3
                          maxLength: 3
                          example: USD
                        total:
                          type: number
                          description: Total amount of the payment.
                          minimum: 0
                          example: 100
                locale:
                  type: string
                  description: Language of the payment.
                  default: en
                  example: es_CO
      responses:
        '200':
          description: Validation status response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1invalidate/post/responses/200/content/application~1json/schema/properties/status'
                required:
                  - status
components:
  schemas:
    Subscription:
      title: Subscription
      x-stoplight:
        id: vip3u3guypqyd
      type: object
      description: Structure that contains information about a subscription or transaction that does not require a specific amount
      properties:
        reference:
          type: string
          x-stoplight:
            id: hpkr64f4l7gwo
          maxLength: '32'
        description:
          type: string
          minLength: '1'
          x-stoplight:
            id: cc6z3gqusoy1k
          maxLength: '254'
    Document:
      title: Document
      type: object
      description: Structure that contains information about a document
      properties:
        type:
          type: string
          maxLength: '3'
          enum:
            - NIT
            - CC
            - CE
            - RUT
            - TI
          example: NIT
          description: Type of identification document. [For more information](/en/gateway/document-types)
        number:
          type: string
          example: '123456123'
          description: Identification document number.
        expeditionDate:
          type: string
          description: Expedition date
        expirationDate:
          type: string
          description: Expiration dat
      required:
        - type
        - number
    Address:
      title: Address
      type: object
      description: Structure that contains information about a physical address
      properties:
        street:
          type: string
          maxLength: '128'
          description: Street
        city:
          type: string
          maxLength: '30'
          description: City
        state:
          type: string
          maxLength: '3'
          description: Country subdivision code representing the state or province. ISO 3166-2 format
          example: NY
        postalCode:
          type: string
          maxLength: '10'
          description: Postal Code
          example: '110111'
        country:
          type: string
          maxLength: '2'
          example: CO
          description: Country code. ISO 3166-1 alpha-2 code
        phone:
          type: string
          maxLength: '20'
          description: Phone number
          example: '3003003000'
    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
    Person:
      title: Person
      type: object
      description: Structure that reflects the information of a person involved in a transaction.
      properties:
        documentType:
          type: string
          description: '[Type of identification document](/en/gateway/document-types)'
          example: CC
          maxLength: '6'
        document:
          type: string
          description: Identification document number. Must be a valid number according to the document type. See more at [Identification Document Types](/en/gateway/document-types)
          maxLength: '25'
        name:
          type: string
          description: Names
          maxLength: '60'
        surname:
          type: string
          description: Surnames
          maxLength: '60'
        company:
          type: string
          description: Company
          maxLength: '60'
        email:
          type: string
          description: Email.
          maxLength: '80'
        address:
          $ref: '#/components/schemas/Address'
          description: Object that contains information about a person's address.
        mobile:
          type: string
          description: Mobile phone
    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:
          type: object
          properties:
            version:
              type: string
              enum:
                - v2
                - v2x
            id:
              type: number
              description: This value only applies if the validation was done with the Placetopay 3DS service
            enrolled:
              type: string
              minLength: 1
              enum:
                - 'Y'
                - 'N'
                - U
              description: Reports whether the card is registered in 3DS
            authenticated:
              type: string
              minLength: 1
              enum:
                - 'Y'
                - 'N'
                - U
                - A
                - I
                - C
                - D
                - R
              maxLength: 1
            eci:
              type: string
              minLength: 1
              description: Authentication result indicator generated by e-commerce.
              enum:
                - '02'
                - '01'
                - '00'
                - '05'
                - '06'
                - '07'
            cavv:
              type: string
              minLength: 28
              maxLength: 28
              nullable: true
              description: Authentication value for the franchise generated by the ACS. (3DS field `authenticationValue`).
              example: AJkBABIWcQAAAAM5FwIzdGiYeHM
            xid:
              type: string
              minLength: 1
              description: DS Transaction ID (3DS `dsTransID` field).
            extra:
              type: object
              properties:
                transStatusReason:
                  type: string
                  description: Provides information about the status of the transaction.
                  nullable: true
                acsTransId:
                  type: string
                  description: Unique transaction identifier generated by the ACS.
                  example: 37a7b6e0-fd58-4e38-98de-79c70c526a47
                threeDSServerTransID:
                  type: string
                  description: Unique transaction identifier generated by the 3DS Server.
                  example: eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
                deviceChannel:
                  type: string
                  description: Channel through which the transaction is carried out.
                  enum:
                    - APP
                    - BRW
                    - RI
                messageCategory:
                  type: string
                  description: Indicates the category of the message.
                  enum:
                    - PA
                    - NPA
                authMethod:
                  type: string
                  description: Indicates whether or not the transaction was challenged.
                  example: FRICTIONLESS_AUTHENTICATION
                authTimestamp:
                  type: string
                  description: Specifies the authentication timestamp.
                  example: '2020-04-21T01:44:54.000Z'
                authInd:
                  type: string
                  description: Defines the type of authentication applied depending on the channel used.
                  example: RECURRING_TRANSACTION
            validSignature:
              type: boolean
          required:
            - enrolled
            - authenticated
            - eci
            - cavv
            - xid
            - version
        otp:
          type: string
        pinPad:
          $ref: '#/components/schemas/PinPad'
        pin:
          type: string
          example: 0B880E2326F6409E
          minLength: '2'
          maxLength: '20'
          description: 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
    Card:
      title: Card
      type: object
      description: Structure containing card information.
      properties:
        number:
          type: string
          maxLength: '20'
        expiration:
          type: string
          example: 12/22
          pattern: ^[01]\d\/\d{2}$
        cvv:
          type: string
      required:
        - number
    Token:
      title: Token
      type: object
      description: |-
        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:
        id:
          type: number
          description: Token identifier in the system; this only applies if the site has a configured token notification URL.
        token:
          type: string
          maxLength: '64'
          minLength: '64'
          description: Code generated to identify the card in the system
        subtoken:
          type: string
          maxLength: '16'
          minLength: '16'
          description: Alternate code generated to identify the card
        franchise:
          type: string
          enum:
            - visa
            - visa_electron
            - amex
            - master
            - codensa
            - diners
            - jbc
            - discover
            - ris
            - credencial
            - comfama
            - colsubsidio
            - falabella
            - elo
            - somos
            - tuya
            - exito
            - alkosto
            - maestro
            - mefia
            - ath_card
          description: Franchise code associated with the token (Only as a response, it is not necessary to send it)
        franchiseName:
          type: string
        issuerName:
          type: string
        lastDigits:
          type: string
        validUntil:
          type: string
        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'
    Credit:
      title: Credit
      type: object
      description: Structure that contains information about the credit type. See more at [Credit](/en/gateway/additional-data#additional-data-credit)
      properties:
        code:
          type: string
          nullable: true
        type:
          type: string
        groupCode:
          type: string
        installment:
          type: integer
        installments:
          type: array
          items:
            type: integer
        kind:
          type: string
          description: Classification of the credit modality. (Paystudio TS)
        description:
          type: string
    CreditPerInstallment:
      title: Credit
      type: object
      description: Structure that contains information about the credit type. See more at [Credit](/en/gateway/additional-data#additional-data-credit-providers-paystudio-ts)
      properties:
        installment:
          type: integer
          description: Number of installments
        kind:
          type: string
          description: Classification of the credit modality.
        description:
          type: string
          description: Credit description.
      required:
        - installment
        - kind
    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
    Payment:
      title: Payment
      type: object
      description: Structure that contains the information about the payment of the transaction required to the web service
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 32
        description:
          type: string
          maxLength: 250
        amount:
          title: Amount
          type: object
          description: Structure that contains the information about the payment of the transaction required to the web service
          properties:
            currency:
              type: string
              description: |
                Alphabetical code of the currency to be used (ISO 4217 alpha code)
              enum:
                - USD
                - COP
                - CRC
                - EUR
                - CAD
                - AUD
                - GBP
                - MXN
                - CLP
              example: COP
              minLength: 3
              maxLength: 3
            total:
              description: |
                Total value in the indicated base currency
              example: 2000
              type: number
            taxes:
              type: array
              description: |
                Structure to define taxes in the payment process.
              items:
                $ref: '#/paths/~1gateway~1information/post/requestBody/content/application~1json/schema/oneOf/5/properties/payment/properties/amount/properties/taxes/items'
            details:
              description: |
                Structure to define additional details of the amount in the payment process.
              type: array
              items:
                $ref: '#/paths/~1gateway~1information/post/requestBody/content/application~1json/schema/oneOf/5/properties/payment/properties/amount/properties/details/items'
          required:
            - currency
            - total
        dispersion:
          type: array
          items:
            $ref: '#/components/schemas/Dispersion'
        modifiers:
          type: array
          description: Structure containing payment modifiers
          items:
            $ref: '#/components/schemas/PaymentModifier'
        shipping:
          $ref: '#/components/schemas/Person'
          description: Structure for relating shipping information.
    PaymentModifier:
      title: PaymentModifier
      type: object
      description: |-
        Structure to store information about a payment modifier.
        NOTE: If a modifier that applies a discount is sent, discounts configured for promotions on the site will not be taken.
      x-examples:
        law-discount:
          type: FEDERAL_GOVERNMENT
          code: '17934'
          additional:
            invoice: '123456'
      properties:
        type:
          type: string
          enum:
            - FEDERAL_GOVERNMENT
          description: Modifier type
        code:
          type: string
          example: '17934'
          description: Modifier code. When the type is FEDERAL_GOVERMENT, it represents the law number for discount.
        additional:
          type: object
          description: Additional modifier information
          properties:
            invoice:
              type: string
              description: Invoice number. Required when type is FEDERAL_GOVERMENT.
    Dispersion:
      title: Dispersion
      type: object
      description: Structure containing the information required for a scatter payment
      properties:
        agreement:
          type: number
          description: Transaction recipient identifier. For the primary transaction site, the value must be null.
          nullable: true
        agreementType:
          type: string
          enum:
            - AIRLINE
            - MERCHANT
        amount:
          $ref: '#/components/schemas/Payment/properties/amount'
    InterestValues:
      title: InterestValues
      type: object
      description: Structure that contains the interest calculation information for a type of credit and amount
      properties:
        original:
          type: number
        installment:
          type: number
        interest:
          type: number
        total:
          type: number
    LookupResponseDataV2:
      title: LookupResponseDataV2
      type: object
      description: This structure contains the properties needed to proceed with a 3DS authentication.
      properties:
        version:
          type: string
          description: API version on which the authentication session was made
          enum:
            - v2
        sessionToken:
          type: string
          example: 1bbf97e3660511d0ce82c15fca343307ba2f87fe84ba421368afb041ba1f638f
        redirectUrl:
          type: string
          description: URL to which the client should be redirected to continue the authentication process.
          example: https://3dss-test.placetopay.com/threeds/v2/sessions/100950/examplea974d40500a650b6a77973985d367ad389a28b747dfdc918756a4ddc1
        identifier:
          type: number
          description: Authentication session identifier.
          example: 263325
      required:
        - version
        - identifier
        - sessionToken
        - redirectUrl
    LookupResponseDataV2X:
      title: LookupResponseDataV2X
      type: object
      description: The fields described here correspond to a response from the [3DS](/three-d-s-server/api/transactions/values) service
      properties:
        action:
          type: string
          enum:
            - continue
            - redirect
          example: continue
        version:
          type: string
          enum:
            - v2x
        sessionToken:
          type: string
          example: 1bbf97e3660511d0ce82c15fca343307ba2f87fe84ba421368afb041ba1f638f
        redirectUrl:
          type: string
          description: URL to which the client should be redirected to continue the authentication process.
          example: https://3dss-test.placetopay.com/threeds/v2/sessions/100950/examplea974d40500a650b6a77973985d367ad389a28b747dfdc918756a4ddc1
        id:
          type: number
          description: Authentication session identifier.
          example: 263325
        enrolled:
          type: string
          enum:
            - 'Y'
            - 'N'
            - U
          description: Present if `action` was `continue`. Indicates whether the card with which the transaction was made is enrolled (registered in the card ranges for the specific issuer).
        authenticated:
          type: string
          description: Present if `action` was `continue`. Reports the authentication status.
          enum:
            - 'Y'
            - 'N'
            - U
            - A
            - I
            - C
            - D
            - R
          maxLength: 1
        validSignature:
          type: boolean
          description: Present if `action` was `continue`. Reports whether the response signature is valid.
        eci:
          type: string
          description: Authentication code per franchise. Indicator of the authentication result generated by the e-commerce.
          num:
            - '02'
            - '01'
            - '00'
            - '05'
            - '06'
            - '07'
        cavv:
          type: string
          minLength: 28
          maxLength: 28
          nullable: true
          description: Present if `action` was `continue`. Authentication value for the franchise generated by the ACS. (3DS `authenticationValue` field).
          example: AJkBABIWcQAAAAM5FwIzdGiYeHM
        xid:
          type: string
          minLength: 1
          description: Present if `action` was `continue`. DS Transaction ID (3DS field `dsTransID`).
        extra:
          type: object
          description: Present if `action` was `continue`. Additional transaction information.
          properties:
            transStatusReason:
              type: string
              description: Provides information about the status of the transaction.
              nullable: true
            acsTransId:
              type: string
              description: Unique transaction identifier generated by the ACS.
              example: 37a7b6e0-fd58-4e38-98de-79c70c526a47
            threeDSServerTransID:
              type: string
              description: Unique transaction identifier generated by the 3DS Server.
              example: eadd3a60-b870-41d0-977f-921b3dbe6323/MkGJDl2Y5E=
            deviceChannel:
              type: string
              description: Channel through which the transaction is carried out.
              enum:
                - APP
                - BRW
                - RI
            messageCategory:
              type: string
              description: Indicates the category of the message.
              enum:
                - PA
                - NPA
            authMethod:
              type: string
              description: Indicates whether or not the transaction was challenged.
              example: FRICTIONLESS_AUTHENTICATION
            authTimestamp:
              type: string
              description: Specifies the authentication timestamp.
              example: '2020-04-21T01:44:54.000Z'
            authInd:
              type: string
              description: Defines the type of authentication applied depending on the channel used.
              example: RECURRING_TRANSACTION
            messageVersion:
              type: string
              description: The 3DS protocol version number used by the system to execute the authentication flow.
              example: 2.2.0
              nullable: true
      required:
        - enrolled
        - authenticated
        - eci
        - cavv
        - xid
        - version
    PinPad:
      title: PinPad
      type: object
      description: Structure containing PinPad service information
      properties:
        transactionId:
          type: string
          description: Identifier of the transaction in the PinPad service
        positions:
          type: string
          description: Positions of the PinPad
        pinBlock:
          type: string
          description: PIN encrypted in PinBlock format
        length:
          type: integer
          description: Length of the PIN
        format:
          type: integer
          description: PIN encryption format
    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: string
          enum:
            - _PSE_
            - BTNBC
            - PGEFT
            - BTNAV
            - ATHMV
            - BB_CP
            - BDILO
            - TR_TC
        returnURL:
          type: string
          format: uri
          maxLength: 250
          description: URL so that once the payment process is completed, control is returned (when applicable)
          example: http://your-site.com/your-return-route
        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
        additional:
          type: object
          description: Structure to relate additional data in the process.
          properties:
            bankCode:
              type: string
              description: Code that identifies the bank on the network.
              example: '1007'
            userType:
              type: string
              description: Indicates whether the payer is a natural person or a legal entity
              enum:
                - person
                - company
            skipRegister:
              type: boolean
              description: Indicates whether the user wants to skip enrollment in Tarjeta Clave
              default: true
            dispersion:
              type: array
              description: List of dispersions to be made in the transaction
              items:
                type: object
                properties:
                  serviceCode:
                    type: string
                    description: Code of the service
                  entityCode:
                    type: string
                    description: Code of the entity
                  amountValue:
                    type: number
                    description: Value of the amount to be paid
                  taxValue:
                    type: number
                    description: Value of the tax applied
                  description:
                    type: string
                    description: Description of the dispersion
    Kount:
      title: Kount
      x-stoplight:
        id: qevzv57mju2tp
      type: object
      description: Manages specific information to use with the Kount risk filter
      properties:
        session:
          type: string
          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
    CardType:
      title: CardType
      x-stoplight:
        id: x4y03rkspgz0b
      type: string
      enum:
        - C
        - R
        - A
      description: Indicates the type of the card. C = credit, R = debit, A = savings
    BankItem:
      title: BankItem
      x-stoplight:
        id: 60487hsjhovs9
      type: object
      properties:
        code:
          type: string
          description: Banking entity code
        description:
          type: string
          description: Name of the banking entity
    BalanceInstrument:
      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/BalanceCard'
    BalanceCard:
      title: Card
      type: object
      description: Structure containing card information.
      properties:
        number:
          type: string
          maxLength: '20'
        expiration:
          type: string
          example: 12/22
          pattern: ^[01]\d\/\d{2}$
      required:
        - number
        - expiration
    Payer:
      type: object
      properties:
        name:
          type: string
          example: John
        surname:
          type: string
          example: Doe
        email:
          type: string
          example: johnDoe@email.com
        mobile:
          type: string
          description: The mobile number can contain the country code
          example: '+573111111111'
        address:
          $ref: '#/components/schemas/Address'
    Buyer:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
