openapi: 3.0.3
info:
  license:
    name: API de Descriptor de operaciones de Khipu
    url: https://khipu.com
  title: API de Generación de Descriptores de Operaciones
  description: >-
    La **API Generadora de Descriptores de Operación** (versión 1.0) de Khipu
    permite  a los comercios crear un identificador único de operación junto con
    un descriptor  cifrado para iniciar transferencias bancarias. A través de un
    único  endpoint (`POST /v1/descriptor/payment`), se envía el ID del banco de
    origen y los  detalles de la transacción, como monto, moneda, datos del
    pagador y cuenta de destino.  Si la solicitud es exitosa, la API devuelve un
    objeto JSON con un `operation.id` (UUID)  y un `operation.description`, que
    es un descriptor cifrado en Base64, diseñado para ser  utilizado en flujos
    seguros de transferencia bancaria. La autenticación se realiza  mediante la
    cabecera `x-api-key`.
  version: v1.0
  x-logo:
    url: https://s3.amazonaws.com/static.khipu.com/2021/logo-transparent.png
    altText: Logo de Khipu
    href: https://khipu.com
servers:
  - url: https://api.khipu.com
    description: Production
security:
  - Api-Key: []
paths:
  /v1/descriptor/payment:
    post:
      summary: Crea un descriptor de operación para una nueva transferencia
      description: >-
        Éste método crea un nuevo identificador de operación y un descriptor de
        operación para una nueva transferencia.
      operationId: createPayment
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/paymentDescriptorRequest'
        required: true
      responses:
        '200':
          description: >-
            Operación exitosa. Retorna un objeto JSON con un nuevo identificador
            de operación y el descriptor encriptado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentDescriptorResult'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado - Credenciales inválidas o faltantes
        '404':
          description: No encontrado - Recurso no disponible
        '500':
          description: Error en el servicio remoto :(
components:
  securitySchemes:
    Api-Key:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    paymentDescriptorRequest:
      type: object
      description: Objeto para solicitar un nuevo Descriptor de Operación.
      required:
        - bank
        - params
      properties:
        bank:
          maxLength: 255
          type: string
          description: El ID del banco origen para esta operación.
          example: dSXgfesd
        params:
          type: object
          description: Parametros necesarios para crear un nuevo descriptor de operación.
          properties:
            subject:
              type: string
              description: Una descripción de la operación de transferencia.
              example: Ejemplo de transferencia
            amount:
              type: number
              description: Monto de la transferencia.
              example: 1000
            currency_code:
              type: string
              description: El código de moneda en el formato ISO 4217.
              example: CLP
            payer_email:
              type: string
              description: El correo electrónico del pagador.
              example: someone@example.com
            payer_name:
              type: string
              description: El nombre del pagador.
              example: Jane Doe
            target_account_bank:
              type: string
              description: El nombre del banco del destinatario de la transferencia.
              example: Awesome Bank
            target_account_alias:
              type: string
              description: >-
                Un alias para la nueva cuenta en caso de que sea la primera
                transferencia.
              example: My friend
            target_account_name:
              type: string
              description: El nombre del titular de la cuenta del destinatario.
              example: John Doe
            target_account_number:
              type: string
              description: En número de cuenta del destinatario.
              example: 123459876
            target_account_personal_identifier:
              type: string
              description: El identificador personal del destinatario, como un RUT o DNI.
              example: 12.345.678-9
    paymentDescriptorResult:
      type: object
      description: >-
        Objeto con el resultado de una solicitud de Descriptor de Operación de
        Pago.
      required:
        - operation
      properties:
        operation:
          type: object
          properties:
            id:
              type: string
              description: Identificador único de la operación.
              example: 13a0f1aa-5e47-4894-aa8b-282dd19593ec
            description:
              type: string
              description: El descriptor cifrado a enviar codificado en Base64.
              example: >-
                eyJtIjoicVlvQU92VllMWm5NVDg2UEovNjNJcGFtRnFQUUNDY
                lNDcHZBZ283OFNlM01VWVBJZU1sZk05a0NzSWVwRkJPcnZlbG
                FwSCtaS3pCRmd3YTBybkVKamtaV3gxYm1iTjd2ZzhhNGtuV1N
                FV3BwclhtVHBkcXRQRXlsVHlhSGtsdTdYTkRtVHZadzlGZlox
                NFgvRDI3dDFvVkFaVWdKN2JqcXdOQXdsYUM0ZmZSL2xmQzJiR
                C9kVElJcGtJc0NTVGxDS1YyTThsbDNYV1dUZFFwdXlzN0xiNU
                FvNVRvVW54NlB0V0Zzd2hxQkVEVmdUWXRhclFqdFBNbUFvRzQ
                1akdKdUk2cmhDU25taG9weEVFM0YwOVgzY0hHSDZzSzVsMl==
