onepay-api-swagger.yml

swagger: "2.0"

info:
  version: "1.0.0"
  title: "Onepay REST API doc"
  description: "Input and outputs documentation of Transbank Onepay API"

schemes:
  - "https"
host: "web2desa.test.transbank.cl"
basePath: "/ewallet-plugin-api-services/services/transactionservice"

paths:
  /sendtransaction:
    post:
      summary: "Create a new transaction on Onepay system"
      operationId: "createTransaction"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "jsonIn"
          description: "Transaction details"
          required: true
          schema:
            $ref: "#/definitions/SendTransactionRequest"
      responses:
        "200":
          description: "This service does not respect any rest compliance and it return always 200 code. If there is some
            error it's informed in the json response."
          schema:
            $ref: "#/definitions/SendTransactionResponse"
  /gettransactionnumber:
    post:
      summary: "Confirm transaction. It's mandatory to call this service in order to charge could be commited on client
        card.

        If this service is never called the charge will be reversed automatically."
      operationId: "commitTransation"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "jsonIn"
          description: "Transaction details"
          required: true
          schema:
            $ref: "#/definitions/GetTransactionNumberRequest"
      responses:
        "200":
          description: "This service does not respect any rest compliance and it return always 200 code. If there is some
            error it's informed in the json response."
          schema:
            $ref: "#/definitions/GetTransactionNumberResponse"
  /nullifytransaction:
    post:
      summary: "Make a refund of part of entire transaction"
      operationId: "reverseTransaction"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "jsonIn"
          description: "ransaction details"
          required: true
          schema:
            $ref: "#/definitions/NullifyTrnsactionRequest"
      responses:
        "200":
          description: "This service does not respect any rest compliance and it return always 200 code. If there is some
            error it's informed in the json response."
          schema:
            $ref: "#/definitions/NullifyTrnsactionResponse"

definitions:
  SendTransactionRequest:
    type: "object"
    properties:
      apiKey:
        type: "string"
        description: "Commerce public ID. It's provided by Transbank with the Sharde Secret Key."
        example: "mUc0GxYGor6X8u-_oB3e-HWJulRG01WoC96-_tUA3Bg"
      appKey:
        type: "string"
        description: "Identify the version of API. It's always same and only change in diferent versions
          of SDK and that's the reason why its hidden of user interface."
        example: "04533c31-fe7e-43ed-bbc4-1c8ab1538af"
      externalUniqueNumber:
        type: "integer"
        format: "int64"
        description: "Unique id number to identify the shopping cart"
        example: 1530288106
      total:
        type: "integer"
        format: "int64"
        description: "Total amount of the order"
        example: 27500
      itemsQuantity:
        type: "integer"
        format: "int32"
        description: "Quantity of items in the shopping cart"
        example: 2
      issuedAt:
        type: "integer"
        format: "int64"
        description: "Date of transaction in seconds (Unix Time)"
        example: 1530288096
      items:
        type: "array"
        items:
          $ref: "#/definitions/Item"
      callbackUrl:
        type: "string"
        description: "Not really used becouse transbank never call this. But its necesary beacouse the sign
          use this in the hash. In the SDK this field is hidden to user interface and the SDK send a 
          FAKE_URL_CALLBACK"
        example: "http://your.host/your.callback.page"
      channel:
        type: "string"
        description: "Payment origen channel (WEB or MOBILE). By default the service asume the WEB channel. the
          SDK send alway WEB in this field and it's not present in the user interface"
        example: "WEB"
      signature:
        type: "string"
        description: "A hash made with some data of this object is encrypted with SHA256 using a shared secret between
          the comerce and transbank and then encoded to base64 to be transfered in this json"
        example: "2CJpn9togRYyy+MwEXaJiW1hySMGfLlgKLgARF+flJs\u003d"
      generateOttQrCode:
        type: "boolean"
        description: "Indicate if you want to receive a base64 QR to print in your web. This field was added
          later in the API and in order to be retrocompatible its optional and false by default.
          The SDK is to integrate the new Onepay using QR so the SDK send it always true."
        default: "true"
        example: "true"

  Item:
    type: "object"
    properties:
      description:
        type: "string"
        description: "Description or name of item"
        example: "Shoes"
      amount:
        type: "integer"
        format: "int64"
        description: "Price of item"
        example: 15000
      expire:
        type: "integer"
        format: "int64"
        description: "I really dont know what is this. I'm using always -1"
        example: -1
      additionalData:
        type: "string"
        description: "I dont know the use of this. Actually I'm not sending it for test cases"

  SendTransactionResponse:
    type: "object"
    properties:
      responseCode:
        type: "string"
        description: "Ok when all was fine or some error in another case"
        example: "OK"
      description:
        type: "string"
        description: "A Transbank generated message to describe the result of operation"
        example: "OK"
      result:
        type: "object"
        properties:
          occ:
            type: "string"
            description: "Buy order"
            example: "1807230859739430"
          ott:
            type: "integer"
            description: "Generated by Transbank it's related with the buy order. I have not discovered any use for this
              information till now"
            example: 45450003
          signature:
            type: "string"
            description: "A hash maked with some data of this object is encrypted with SHA256 using a shared secret between
              the comerce and transbank and then encoded to base64 to be transfered in this json"
            example: "Gn46q+aK7GEUQdmZjQ2O3N0uhy8yKYdQVoXD7uwTKvs="
          externalUniqueNumber:
            type: "integer"
            format: "int64"
            description: "Unique id number to identify the transaction. It's the same sent in the request"
            example: 1530288106
          issuedAt:
            type: "integer"
            format: "int64"
            description: "Date of transaction in seconds"
            example: 1531256717
          qrCodeAsBase64:
            type: "string"
            description: "QR in base64 format"

  GetTransactionNumberRequest:
    type: "object"
    properties:
      apiKey:
        type: "string"
        description: "A key provided by Transbank"
        example: "mUc0GxYGor6X8u-_oB3e-HWJulRG01WoC96-_tUA3Bg"
      appKey:
        type: "string"
        description: "A key provided by Transbank to identify the comerce"
        example: "04533c31-fe7e-43ed-bbc4-1c8ab1538af"
      externalUniqueNumber:
        type: "integer"
        format: "int64"
        description: "Unique id number to identify the transaction"
        example: 1530288106
      occ:
        type: "string"
        description: "Buy order"
        example: "1807230859739430"
      issuedAt:
        type: "integer"
        format: "int64"
        description: "Date of transaction in seconds"
        example: 1530288096
      signature:
        type: "string"
        description: "A hash maked with some data of this object is encrypted with SHA256 using a shared secret between
          the comerce and transbank and then encoded to base64 to be transfered in this json"
        example: "2CJpn9togRYyy+MwEXaJiW1hySMGfLlgKLgARF+flJs\u003d"

  GetTransactionNumberResponse:
    type: "object"
    properties:
      responseCode:
        type: "string"
        description: "Ok when all was fine or some error in another case"
        example: "OK"
      description:
        type: "string"
        description: "A Transbank generated message to describe the result of operation"
        example: "OK"
      result:
        type: "object"
        properties:
          occ:
            type: "string"
            description: "Buy order"
            example: "1807230859739430"
          authorizationCode:
            type: "string"
            description: "Self explanatory"
            example: "368575"
          issuedAt:
            type: "integer"
            format: "int64"
            description: "Date of transaction in seconds"
            example: 1530288096
          signature:
            type: "string"
            description: "A hash maked with some data of this object is encrypted with SHA256 using a shared secret between
              the comerce and transbank and then encoded to base64 to be transfered in this json"
            example: "Gn46q+aK7GEUQdmZjQ2O3N0uhy8yKYdQVoXD7uwTKvs="
          amount:
            type: "integer"
            format: "int64"
            description: "Amount charged on client card in this transaction"
            example: 52000
          transactionDesc:
            type: "string"
            description: "Transaction description"
            example: "Venta Normal: Sin cuotas"
          installmentsAmount:
            type: "integer"
            format: "int64"
            description: "Total amount charged on client card"
            example: 52000
          installmentsNumber:
            type: "integer"
            format: "int64"
            description: "Number of charges"
            example: 1
          buyOrder:
            type: "string"
            description: "Buy order. It's not the same of occ"
            example: "20180704152042696"

  NullifyTrnsactionRequest:
    type: "object"
    properties:
      apiKey:
        type: "string"
        description: "A key provided by Transbank"
        example: "mUc0GxYGor6X8u-_oB3e-HWJulRG01WoC96-_tUA3Bg"
      appKey:
        type: "string"
        description: "A key provided by Transbank to identify the comerce"
        example: "04533c31-fe7e-43ed-bbc4-1c8ab1538af"
      nullifyAmount:
        type: integer
        format: int64
        description: "Amount to reverse"
        example: 2490
      occ:
        type: "string"
        description: "Buy order"
        example: "1807230859739430"
      externalUniqueNumber:
        type: "integer"
        format: "int64"
        description: "Unique id number to identify the transaction"
        example: 1530288106
      authorizationCode:
        type: "string"
        description: "Self explanatory"
        example: "906637"
      issuedAt:
        type: "integer"
        format: "int64"
        description: "Date of transaction in seconds"
        example: 1530288096
      signature:
        type: "string"
        description: "A hash maked with some data of this object is encrypted with SHA256 using a shared secret between
          the comerce and transbank and then encoded to base64 to be transfered in this json"
        example: "2CJpn9togRYyy+MwEXaJiW1hySMGfLlgKLgARF+flJs\u003d"

  NullifyTrnsactionResponse:
    type: "object"
    properties:
      responseCode:
        type: "string"
        description: "Ok when all was fine or some error in another case"
        example: "OK"
      description:
        type: "string"
        description: "A Transbank generated message to describe the result of operation"
        example: "OK"