swagger: '2.0'
schemes:
  - "https"
host: 'api.multicaja.cl'
consumes:
  - application/json
produces:
  - application/json
info:
  title: API Pagos con tarjeta
  version: '0.2'
  description: |

    ## Limitaciones
    - Sólo tarjetas de crédito Mastercard
    - Con cuotas emisor
    - Sin captura diferida
    - Todos los montos deben estar en pesos chilenos (ISO 4217 = CLP)
    - La API no soporta CORS
    - No está soportada la devolución ni reversa parcial.

    ## Reglas de la API
    - El campo `consumer_transaction_id` **debe** ser único (incluso en días y transacciones distintas).
    - Todos los requerimientos deben ser realizados sobre *HTTPS*. Los requerimientos sobre *HTTP* fallarán.
    - Los campos del nodo `card`deben ser encriptados utilizando el algoritmo AES-256. El procedimiento para compartir la llave se acordará en otro documento.
    - Todos los requerimientos son autenticados. Debe incluir el encabezado `Api-Key: <key>`.

    ## Idempotencia
    La API soporta *idempotencia*, por lo tanto puedes reintentar un requerimiento sin peligro de que el recurso se cree dos veces. Para esto debes incluir el encabezado `Idempotency-Key: <key>`, donde `key` es un identificador único de tu sistema o UUID. La clave tiene una validez de 24 horas.

    - NOTA: Si envías dos requerimientos con igual `consumer_transaction_id` y distinto `Idempotency-Key`, se entendrán como dos requerimientos **diferentes** y uno de ellos fallará dado que el campo `consumer_transaction_id` debe ser único.

    ## Gestión de llaves
    Los campos del nodo `card` se deben enviar encriptados por una llave simétrica utilizando el algoritmo AES-256. Para establecer la llave simétrica, el comsumidor de la API debe generar y enviar a Multicaja un componente de la llave con sus respectivos dígitos de chequeo. Multicaja generará y enviará otro componenente. Luego, ambos actores deberán cargar los componentes en sus HSMs, generando la llave final y verificando que los digitos de chequeo coincidan. Esta llave debe ser cambiada cada 3 años.
  x-logo:
    url: 'https://www.flow.cl/images/logos/mc-sf.svg'
    altText: Multicaja logo

basePath: /card-payments/v0.2/
paths:

  /charges:
    post:
      summary: Venta con tarjeta
      description: |
        Realiza un cargo en una tarjeta de crédito.
      parameters:
        - in: body
          name: charge_req
          description: Venta con tarjeta
          required: true
          schema:
            $ref: '#/definitions/charge_req'
      responses:
        200:
          description: |
            OK - Venta exitosa
          schema:
            $ref: '#/definitions/charge_res'
        400:
          description: "Alguno de los campos requeridos no viene o es inválido"
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "MISSING_PARAMETER"
              message: "The parameter 'amount' is missing "
        401:
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "UNAUTHORIZED"
              message: "No valid API key provided."
        402:
          description: Transacción se intentó, pero falló.
          schema:
            $ref: '#/definitions/error_obj'
        500:
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "BAD_GATEWAY"
              message: "Cannot connect to a service endpoint"
    get:
      summary: Consulta de un cargo
      description: |
        Obtiene el objeto cargo
      parameters:
        - in: query
          name: consumer_transaction_id
          description: Consulta de un cargo dado el consumer_transaction_id
          required: true
          type: string
      responses:

        200:
          description: |
            OK - Venta exitosa
          schema:
            $ref: '#/definitions/charge_all'
        400:
          description: "Alguno de los campos requeridos no viene o es inválido"
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "MISSING_PARAMETER"
              message: "The parameter 'amount' is missing "
        401:
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "UNAUTHORIZED"
              message: "No valid API key provided."
        404:
          description: El recurso requerido no existe.
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "NOT_FOUND"
              message: "The requested resource doesn't exist."
        500:
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "BAD_GATEWAY"
              message: "Cannot connect to a service endpoint"
  /charges/reversal:
    post:
      summary: Reversa de una venta
      description: |
        Reversa en línea de una venta
      parameters:
        - in: body
          name: reversal_new
          description: Reversa de venta con tarjeta
          required: true
          schema:
            $ref: '#/definitions/reversal_req'
      responses:
        '200':
          description: |
            OK - Reversa exitosa
          schema:
            $ref: '#/definitions/reversal_res'
        '400':
          description: Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado
          schema:
            $ref: '#/definitions/error_obj'
        '401':
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
        '500':
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'

  /charges/{id}:
    get:
      summary: Consulta de un cargo (NOT IMPLEMENTED)
      description: |
        Obtiene el objeto cargo
      parameters:
        - in: path
          name: id
          description: Consulta de un cargo
          required: true
          type: integer
      responses:
        200:
          description: |
            OK - Venta exitosa
          schema:
            $ref: '#/definitions/charge_all'
        400:
          description: "Alguno de los campos requeridos no viene o es inválido"
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "MISSING_PARAMETER"
              message: "The parameter 'amount' is missing "
        401:
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "UNAUTHORIZED"
              message: "No valid API key provided."
        404:
          description: El recurso requerido no existe.
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "NOT_FOUND"
              message: "The requested resource doesn't exist."
        500:
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "BAD_GATEWAY"
              message: "Cannot connect to a service endpoint"



  /refunds:
    post:
      summary: Devolución de un cargo realizado a una tarjeta (NOT IMPLEMENTED)
      description: |
        Devuelve total o parcialmante un cargo realizado a una tarjeta de crédito.

        ## Devolución total
        - El objeto `amount` es opcional. En caso que se envíe, el campo `value` debe corresponder al monto total del cargo.

        ## Devolución parcial
        - El objeto `amount` corresponde al monto que se quiere devolver. Debe ser mayor que cero y menor o igual al monto no devuelto de la venta.
        - Puedes realizar hasta **10 devoluciones parciales** asociadas a la misma venta.


      parameters:
        - in: body
          name: refund_req
          description: Devolución de cargo
          schema:
            $ref: '#/definitions/refund_req'
      responses:
        '200':
          description: |
            OK - devolución exitosa
          schema:
            $ref: '#/definitions/refund'
        '400':
          description: Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado
          schema:
            $ref: '#/definitions/error_obj'
        '401':
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
        '500':
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
    get:
      summary: Consulta de una devolución (NOT IMPLEMENTED)
      description: |
        Obtiene el objeto devolución
      parameters:
        - in: query
          name: consumer_transaction_id
          description: Consulta de una devolución dado el consumer_transaction_id
          required: true
          type: string
      responses:

        200:
          description: OK
          schema:
            $ref: '#/definitions/refund'
        400:
          description: "Alguno de los campos requeridos no viene o es inválido"
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "MISSING_PARAMETER"
              message: "The parameter 'amount' is missing "
        401:
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "UNAUTHORIZED"
              message: "No valid API key provided."
        404:
          description: El recurso requerido no existe.
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "NOT_FOUND"
              message: "The requested resource doesn't exist."
        500:
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "BAD_GATEWAY"
              message: "Cannot connect to a service endpoint"

  /refunds/reversal:
    post:
      summary: Reversa de una devolución (NOT IMPLEMENTED)
      description: |
        Reversa en línea de una devolución
      parameters:
        - in: body
          name: reversal_new
          description: Reversa de devolución
          required: true
          schema:
            $ref: '#/definitions/reversal_req'
      responses:
        '200':
          description: |
            OK - Reversa exitosa
          schema:
            $ref: '#/definitions/reversal_res'
        '400':
          description: Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado
          schema:
            $ref: '#/definitions/error_obj'
        '401':
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
        '500':
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
  /refunds/{id}:
    get:
      summary: Consulta de una devolución (NOT IMPLEMENTED)
      description: |
        Obtiene el objeto cargo
      parameters:
        - in: path
          name: id
          description: Consulta de una devolución
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/refund'
        400:
          description: "Alguno de los campos requeridos no viene o es inválido"
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "MISSING_PARAMETER"
              message: "The parameter 'amount' is missing "
        401:
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "UNAUTHORIZED"
              message: "No valid API key provided."
        404:
          description: El recurso requerido no existe.
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "NOT_FOUND"
              message: "The requested resource doesn't exist."
        500:
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
          examples:
            application/json:
              code: "BAD_GATEWAY"
              message: "Cannot connect to a service endpoint"
  /batch-refund:
    post:
      summary: Devolución batch de un cargo realizado a una tarjeta
      description: |
        Devuelve total o parcialmante un cargo realizado a una tarjeta de crédito.

        ## Devolución total
        - El objeto `amount` es opcional. En caso que se envíe, el campo `value` debe corresponder al monto total del cargo.

        ## Devolución parcial (NOT IMPLEMENTED)
        - El objeto `amount` corresponde al monto que se quiere devolver. Debe ser mayor que cero y menor o igual al monto no devuelto de la venta.
        - Puedes realizar hasta **10 devoluciones parciales** asociadas a la misma venta.

      parameters:
        - in: body
          name: refund_req
          description: Devolución de cargo
          schema:
            $ref: '#/definitions/refund_req'
      responses:
        '200':
          description: |
            OK - devolución exitosa
          schema:
            $ref: '#/definitions/refund_batch_res'
        '400':
          description: Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado
          schema:
            $ref: '#/definitions/error_obj'
        '401':
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
        '500':
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'
  /batch-refund/reversal:
    post:
      summary: Reversa de una devolución batch
      description: |
        Reversa de una devolución
      parameters:
        - in: body
          name: reversal_batch
          description: Reversa de devolución
          required: true
          schema:
            $ref: '#/definitions/reversal_refund_batch_req'
      responses:
        '200':
          description: |
            OK - Reversa exitosa
          schema:
            $ref: '#/definitions/reversal_refund_batch_res'
        '400':
          description: Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado
          schema:
            $ref: '#/definitions/error_obj'
        '401':
          description: API Key no autorizada
          schema:
            $ref: '#/definitions/error_obj'
        '500':
          description: Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema
          schema:
            $ref: '#/definitions/error_obj'

definitions:
  reversal_refund_batch_req:
    type: object
    description: |
      Solicitud de devolución batch de una transacción **(Request)**
    allOf:
      - $ref: "#/definitions/reversal_req"
      - type: object
        required:
          - status
          - id
          - amount
        properties:
          amount:
            $ref: '#/definitions/amount_and_currency'

  reversal_refund_batch_res:
    type: object
    description: |
      Respuesta a devolucion batch de una transacción **(Response)**
    allOf:
      - $ref: "#/definitions/reversal_res"
      - type: object
        required:
          - status
          - id
          - timestamps
          - external_authorization_code
        properties:
          external_authorization_code:
            type: integer
            description: Identificador único de la transacción en el switch de la bandera
            example: 1231232



  refund_batch_res:
    type: object
    description: Solucitud de devolución batch **(Response)**
    required:
      - consumer_transaction_id
      - status
      - id
      - external_authorization_code
      - timestamps
    properties:
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción generado por el consumidor de la API
        example: "xhGXSPKviU83lln_xc9lc"
      status:
        type: string
        description: Estado de la solicitud. Al ser un procesamiento batch, la respuesta exitosa es ´pending´.
        example: "pending"
      id:
        type: integer
        description: Identificador único de la solicitud generado por Multicaja
        example: 7654320
      external_authorization_code:
        type: integer
        description: Identificador único de la transacción en el switch de la bandera
        example: 1231232
      timestamps:
        $ref: '#/definitions/timestamps'

  refund_req:
    type: object
    description: |
      Solicitud de devolución **(Request)**
    required:
      - original_consumer_transaction_id
      - consumer_transaction_id
      - amount
      - additional_data
      - merchant
    properties:
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción generado por el consumidor de la API
        example: "xhGXSPKviU83lln_xc9lc"
      original_consumer_transaction_id:
        type: string
        description: Identificador de la venta original, sobre la que se realizará la devolución.
        example: "crlfUYEBK14zotCTykezJkfg"
      amount:
        $ref: "#/definitions/amount_and_currency"
      additional_data:
        $ref: "#/definitions/addtitional_data"
      merchant:
        $ref: "#/definitions/merchant_base"

  refund:
    type: object
    description: |
      Solicitud de devolución **(Response)**
    required:
      - consumer_transaction_id
      - amount
      - id
      - external_authorization_code
      - timestamps
    properties:
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción generado por el consumidor de la API
        example: "xhGXSPKviU83lln_xc9lc"
      amount:
        $ref: '#/definitions/amount_and_currency'
      id:
        type: integer
        description: Identificador único de la devolución generado por Multicaja
        example: 7654320
      external_authorization_code:
        type: integer
        description: Identificador único de la transacción en el switch de la bandera
        example: 1231232
      timestamps:
        $ref: '#/definitions/timestamps'

  reversal_base:
    type: object
    description: |
      Solicitud de reversa de una transacción **(Request)**
    required:
      - consumer_transaction_id
    properties:
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción que se quiere reversar.
        example: "crlfUYEBK14zotCTykezJkfg"

  reversal_req:
    type: object
    description: |
      Solicitud de reversa de una transacción **(Request)**
    allOf:
      - $ref: "#/definitions/reversal_base"
      - type: object
        required:
          - consumer_transaction_id
          - merchant
        properties:
          merchant:
            $ref: '#/definitions/merchant_base'

  reversal_res:
    type: object
    description: |
      Respuesta a solicitud de reversa de una transacción **(Response)**
    allOf:
      - $ref: "#/definitions/reversal_base"
      - type: object
        required:
          - status
          - id
          - timestamps
        properties:
          id:
            type: integer
            description: Código identificador de la compra en los sistemas de Multicaja
            example: 7783834
          status:
            type: string
            description: Estado de la reversa.
            example: "approved"
          timestamps:
            $ref: '#/definitions/timestamps'

  charge_req:
    type: object
    description: |
      Solicitud de venta **(Request)**
    required:
      - card
      - additional_data
      - amount
      - consumer_transaction_id
      - installments
      - charge_type
      - merchant
    properties:
      card:
        type: string
        description: Datos de tarjeta encriptados
        example: "mOoT6vkSI7z0ahhF7kN32cXAshL26UYHw0yzEef0KnFDbhtQRv6b1hoMkmdOCQsg"
      additional_data:
        $ref: "#/definitions/addtitional_data"
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción generado por el consumidor de la API
        example: "crlfUYEBK14zotCTykezJkfg"
      amount:
        $ref: '#/definitions/amount_and_currency'
      installments:
        type: integer
        description: cantidad de cuotas (cuotas emisor)
        example: null
      charge_type:
        $ref: '#/definitions/charge_type'
      merchant:
        $ref: '#/definitions/merchant'


  charge_res:
    type: object
    description: |
      Respuesta a solicitud de venta **(Response)**
    required:
      - amount
      - consumer_transaction_id
      - external_authorization_code
      - id
      - timestamps
    properties:
      amount:
        $ref: '#/definitions/amount_and_currency'
      consumer_transaction_id:
        type: string
        description: Identificador único de la transacción generado por el consumidor de la API
        example: "crlfUYEBK14zotCTykezJkfg"
      external_authorization_code:
        type: integer
        description: Identificador único de la transacción en el switch de la bandera
        example: 1231232
      id:
        type: integer
        description: Código identificador de la compra en los sistemas de Multicaja
        example: 7783834
      timestamps:
        $ref: '#/definitions/timestamps'

  charge_all:
    type: object
    description: |
      Respuesta a solicitud de venta **(Response)**
    allOf:
    - $ref: "#/definitions/charge_res"
    - type: object
      required:
        - status
        - failure_code
        - failure_message
        - amount_refunded
        - refunds
        - installments
        - charge_type
        - merchant
      properties:
        status:
          type: string
          description: Estado del cargo
          example: "refunded"
        failure_code:
          type: string
          description: Código de error
          example: null
        failure_message:
          type: string
          description: Mensaje de error
          example: null
        amount_refunded:
          $ref: '#/definitions/amount_and_currency'
        refunds:
          type: array
          items:
            $ref: "#/definitions/refund"
        installments:
          type: integer
          description: cantidad de cuotas (cuotas emisor)
          example: null
        charge_type:
          $ref: '#/definitions/charge_type'
        merchant:
          $ref: '#/definitions/merchant'


  timestamps:
    type: object
    description: |
      Fecha de creación y de última modificación **(Response)**
    required:
      - created_at
      - updated_at
    properties:
      created_at:
        type: string
        format: date-time
        example: "2018-01-14T15:27:42.669Z"
      updated_at:
        type: string
        format: date-time
        example: "2018-03-02T10:03:12.123Z"

  amount_and_currency:
    type: object
    description: Monto en una moneda específica
    required:
      - currency_code
      - value
    properties:
      value:
        type: number
        description: Monto en formato decimal
        example: "1000.00"
      currency_code:
        type: string
        description: Código ISO 4217 de la moneda
        example: "CLP"

  merchant:
    type: object
    description: |
      Datos del comercio que origina el cargo
    allOf:
      - $ref: "#/definitions/merchant_base"
      - type: object
        required:
          - merchant_code
          - local_tax_number
          - mcc
          - name
          - city
          - country_code
        properties:
          local_tax_number:
            type: string
            description: Rol Único Tributario (RUT) del comercio
            example: "96675670-5"
          mcc:
            type: string
            description: Código ISO 18245 asignado por la bandera al comercio
            example: "5999"
          name:
            type: string
            description: Nombre del comercio que aparece en extracto bancario
            example: "Store 1"
          city:
            type: string
            description: Ciudad en la que está ubicado el comercio
            example: "Iquique"
          country_code:
            type: string
            description: Código ISO 3166 del país. En conjunto con `name` y `city`, se uutilizan para formar el *soft descriptor*
            example: "152"

  merchant_base:
    type: object
    description: |
      Datos del comercio que origina el cargo
    required:
      - merchant_code
    properties:
      merchant_code:
        type: string
        description: Código de comercio
        example: "0023434"

  charge_type:
    type: object
    description: |
      Tipo de cargo que se realiza. Indica si el pago es recurrente o no y si los datos de la tarjeta fueron digitados por el tarjetahabiente o es card on file.
    required:
      - card_on_file
      - recurring
    properties:
      card_on_file:
        type: boolean
        description: Indica si card on file
        example: false
      recurring:
        type: boolean
        description: Indica si el cargo es recurrente
        example: false


  addtitional_data:
    type: object
    description: |
      Objeto JSON con atributos adicionales para la transacción.

  error_obj:
    type: object
    description: "Error"
    required:
      - code
      - message
    properties:
      code:
        type: string
        example: "INSUFFICIENT_FUNDS"
        description: Código que representa el error.
      message:
        type: string
        example: "La tarjeta no tiene saldo"
        description: Descripción corta del error