openapi: 3.0.3
info:
  license:
    name: Khipu Automatic Payment API
    url: https://khipu.com
  title: Automatic Payment API
  description: >-
    The Automatic Payment API (version 1.0) by Khipu allows merchants to set up
    recurring payment  subscriptions using bank debits (PAC). Through the POST
    /v1/automatic-payment/subscription  endpoint, merchants submit details such
    as the subscription name, customer email, maximum  amount, currency, and
    URLs for notification, return, or cancellation. Upon success, the API 
    returns a unique subscription_id and a redirect_url where the user can
    authorize the debit  mandate with their bank. Merchants can later query and
    manage the PAC status using additional  endpoints. Authentication is handled
    via the x-api-key header.
  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://payment-api.khipu.com
    description: Production
paths:
  /v1/automatic-payment/subscription:
    post:
      summary: Subscription creation
      description: This method creates a new subscription.
      operationId: createSubscription_1
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreationRequest'
        required: true
      responses:
        '200':
          description: >-
            Successful operation. Returns a JSON object with the subscription
            id  that can be used to ask the customer to sign the direct debit
            mandate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCreationResult'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized - Invalid or missing credentials
        '404':
          description: Not found - Resource not available
        '500':
          description: Remote service error :(
  /v1/automatic-payment/subscription/{id}:
    get:
      summary: Subscription status
      description: This method get the current state of a automatic payment subscription.
      operationId: fetchSubscriptionStatus_1
      parameters:
        - name: id
          in: path
          description: unique identifier of a subscription.
          required: true
          schema:
            type: string
            maxLength: 255
      responses:
        '200':
          description: >-
            Successful operation. Returns a JSON object with the subscription id
            information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized - Invalid or missing credentials
        '404':
          description: Not found - Resource not available
        '500':
          description: Remote service error :(
  /v1/automatic-payment/charge-intent:
    post:
      summary: Charge intent creation
      description: This method creates a new charge request for the specified subscription.
      operationId: createCharge_1
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeRequest'
        required: true
      responses:
        '200':
          description: >-
            Successful operation. Returns a JSON object with the charge intent
            id that can be used to trace the request of a direct debit charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResult'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized - Invalid or missing credentials
        '404':
          description: Not found - Resource not available
        '500':
          description: Remote service error :(
security:
  - Api-Key: []
components:
  securitySchemes:
    Api-Key:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    SubscriptionCreationRequest:
      type: object
      description: Object to post a request for a new Automatic Payment subscription.
      required:
        - name
        - email
        - max_amount
        - currency
        - notify_url
        - return_url
        - cancel_url
      properties:
        name:
          maxLength: 255
          type: string
          description: Name to identify the subscription.
          example: Service XYZ Id 11.222.333-0
        email:
          maxLength: 255
          type: string
          description: The customer e-mail.
          example: personal.email@gmail.com
        max_amount:
          maxLength: 255
          type: number
          description: max amount for every charge intent.
          example: 1000
        currency:
          maxLength: 4
          type: string
          description: the currency code in the ISO 4217.
          example: CLP
        notify_url:
          maxLength: 1024
          type: string
          description: >-
            URL that will be called when the customer complete the signing
            process with the bank. A JSON message will be sent via POST with the
            information of the subscription with the following structure
            (`status` can be __"enabled"__ or __"disabled"__):

            ```json
              {
                "subscription_id": string,
                "status": "enabled"
              }
            ```
          example: https://my-domain.biz/subscription-notify-api
        return_url:
          maxLength: 1024
          type: string
          description: >-
            URL to redirect the customer when the signing process has been
            completed.
          example: https://my-domain.biz/subscription-result
        cancel_url:
          maxLength: 1024
          type: string
          description: >-
            URL to redirect the customer if the signing process could not be
            completed.
          example: https://my-domain.biz/subscription-cancel
        service_reference:
          type: string
          description: >-
            Value to associate with the subscription. It can be useful when you
            don't want your client to be identified with a random unique string
            in the bank's mandate subscription form.
          example: 12345678K
        image_url:
          maxLength: 1024
          type: string
          description: URL of the image associated with the subscription.
          example: https://my-domain.biz/subscription-image.png
        description:
          type: string
          description: >-
            Detailed description of the PAC (Automatic Payment) subscription
            carried out at banks for products.
          example: PAC subscription for automatic payment of products at your bank.
    SubscriptionCreationResult:
      type: object
      description: >-
        Object with the result of a Automatic Payment subscription creation
        request.
      required:
        - subscription_id
        - redirect_url
      properties:
        subscription_id:
          maxLength: 255
          type: string
          description: >-
            Unique subscription identifier, to be associated with the service
            acquired by the customer. Subsequently, this value can be used to
            check the status of the subscription.
          example: 13a0f1aa-5e47-4894-aa8b-282dd19593ec
        redirect_url:
          maxLength: 1024
          type: string
          description: >-
            The url where the merchant must redirect the user so that they can
            sign the subscription with their personal bank. It uses the
            subscription id as a url parameter.
          example: https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec
    SubscriptionStatus:
      type: object
      description: Object with the status of a automatic payment subscription.
      required:
        - subscription_id
        - status
        - developer
        - customer_bank_code
        - service_reference
      properties:
        subscription_id:
          maxLength: 255
          type: string
          description: Unique subscription identifier.
          example: 13a0f1aa-5e47-4894-aa8b-282dd19593ec
        status:
          type: string
          enum:
            - DISABLED
            - SIGNED
            - ENABLED
          description: >-
            The current status of the subscription. A charge intent can only be
            made if the status is `ENABLED`.
          example: SIGNED
        developer:
          type: boolean
          description: >-
            Indicates if the subscription was created using the sandbox
            environment. A `false` value means that is a production
            subscription.
          example: false
        customer_bank_code:
          maxLength: 255
          type: string
          description: >-
            The bank used by the customer to sign the subscription. The possible
            values are the ones used in the Khipu Payment API, or `no-bank` if
            the subscription has not been signed.
          example: '8'
        service_reference:
          maxLength: 255
          type: string
          description: The alias used to identify the subscription.
          example: My Merchant name
    ChargeRequest:
      type: object
      description: >-
        Object to post a request for a new charge associated with a subscription
        id.
      required:
        - subscription_id
        - amount
        - subject
        - body
        - error_response_url
        - custom
        - transaction_id
        - notify_url
      properties:
        subscription_id:
          maxLength: 255
          type: string
          description: The subscription id that will be charged.
          example: 13a0f1aa-5e47-4894-aa8b-282dd19593ec
        amount:
          type: number
          format: float
          minimum: 1
          description: >-
            Amount that will be charged. Do not use thousands separator, and a
            maximum of 4 decimal places. It will assume the currency in which
            the merchant registered its account in Khipu.
          example: 10000
        subject:
          maxLength: 255
          type: string
          description: Subject to identify the charge.
          example: Charge Service XYZ Id 11.222.333-0
        body:
          maxLength: 5120
          type: string
          description: Charge description.
          example: 'Service XYZ - November 2022 - Amount: $10.000'
        error_response_url:
          maxLength: 1024
          type: string
          description: >-
            URL that will be called if an error occurs in the charge process. A
            JSON will be sent by POST with the following structure:

            ```json
              {
                "subscription_id": string,
                "transaction_id": string,
                "error_message": string
              }
            ```
          example: https://my-domain.biz/charge-error-api
        custom:
          maxLength: 1073741824
          type: string
          description: >-
            This field can be used to send custom information about the charge
            intent. It can be in text format or base64-encoded document.
          example: Custom information content.
        transaction_id:
          maxLength: 255
          type: string
          description: >-
            Merchant's unique identifier for this operation. For example, the
            invoice number.
          example: INVOICE-23ffcfbe1e4a4d1c9dc631fe70bddaa0
        notify_url:
          maxLength: 1024
          type: string
          description: >-
            URL that will be called once the charging process finishes and the
            payment is conciliated. A POST will be sent with parameters that
            allows fetch the payment details, using the same flow of a normal
            payment. See the
            [documentation](https://www.khipu.com/api/#14-notificacion) for
            details.
          example: https://my-domain.biz/charge-notify-api
        notify_api_version:
          maxLength: 255
          type: string
          description: >-
            API version for instant payment notification(same value as used for
            the payment API).
          example: '1.3'
    ChargeResult:
      type: object
      description: Object with the result of a charge intent creation request.
      required:
        - payment_id
      properties:
        payment_id:
          maxLength: 12
          type: string
          description: >-
            Unique charge identifier. Represents the automatic payment id that
            will be used to trace the request to charge the customer's account.
          example: v67prof2ugg3
