ESTO OpenAPI spec to create hire-purchase (loan) requests for their clients

esto.yaml

swagger: "2.0"
info:
  description: "
  Via this API a merchant partnered with ESTO can create hire-purchase (loan) requests for their clients.
  For available official ecommerce integrations, please refer to developer's guide (You need to be signed in as a merchant to view this page)."
  version: "1.0.0"
  title: "ESTO API"
  contact:
    email: "markus.karileet@codehouse.ee"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "private-anon-67713c6bf5-esto.apiary-mock.com"
#host: "api.esto.ee"
basePath: "/v2"
tags:
  - name: "Purchase Request"
    description: "
  To create a new purchase/lease application, send a request to the API and a purchase_url will be returned. Customer should be redirected to this URL to start the application process in ESTO's environment.
  Requires authentication!"
  - name: "Calculate"
    description: "
  These requests do not require Basic Authentication and return a response without data or mac! These requests can be made using GET or POST.
  It's recommended to cache these queries for at least 10 minutes in order to reduce queries to the server!"
schemes:
  - "https"
paths:
  /purchase/redirect:
    post:
      tags:
        - "Purchase Request"
      summary: "New purchase with redirect to ESTO (recommended)"
      description: "
      To create a new purchase/lease application, send a request to the API and a purchase_url will be returned. Customer should be redirected to this URL to start the application process in ESTO's environment.
      Requires authentication!"
      operationId: "purchaseRequestRedirect"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/PurchaseRequestRedirect"
      responses:
        "200":
          description: Success
          schema:
            $ref: '#/definitions/PurchaseResponseRedirect'
      security:
        - basicAuth: []
  /purchase/local:
    post:
      tags:
        - "Purchase Request"
      summary: "New application without redirect"
      description: "
      You can use this endpoint, if you want the customer to fill out the whole application without leaving your site. This way we will return a positive, negative or pending answer.
      In case of a positive or pending answer the customer can be redirected to ESTO's page to complete the application process and sign the contract.
      Only use this endpoint, if the user can provide all of their details, including PIN, and wants to receive a positive or negative answer without leaving your site.
      Requires authentication!"
      operationId: "newApplicationWithoutRedirect"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/PurchaseRequest"
      responses:
        "200":
          description: Success
          schema:
            $ref: '#/definitions/PurchaseResponse'
      security:
        - basicAuth: []
  /purchase/payment-methods:
    get:
      tags:
        - "Purchase Request"
      summary: "Available payment methods"
      description: "
      Get a list of payment methods (e.g banks, credit cards, loans) available to use.
      This endpoint should be used to refresh the endpoints that are displayed to the customer in the checkout. Note that the available methods for ESTO Pay can change often since some banks are not working sometimes and have to be disabled.
      It's recommended to cache this query for at least 10 minutes in order to reduce queries to the server!
      Requires authentication!"
      operationId: "availablePaymentMethods"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: country_code
          required: true
          type: string
        - in: "query"
          name: test_mode
          required: false
          type: boolean
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/AvailablePaymentMethod'
      security:
        - basicAuth: []
  /calculate/all-payments:
    get:
      tags:
        - "Calculate"
      summary: "Calculate Payments"
      description: "Calculate payments for all periods available for the given amount. The monthly payments are only an approximation!"
      operationId: "calculatePayments"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: amount
          type: number
          required: true
        - in: "query"
          name: down_payment
          type: number
          default: 0
        - in: "query"
          name: shop_id
          type: string
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/CalculatedPaymentPeriod'
  /calculate/periods:
    get:
      tags:
        - "Calculate"
      summary: "Get Allowed Periods"
      description: "Calculate the periods (months) that are allowed for the specified purchase amount."
      operationId: "getAllowedPeriods"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: amount
          type: number
          required: true
        - in: "query"
          name: shop_id
          type: string
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/AllowedPeriods'
  /calculate/payment:
    get:
      tags:
        - "Calculate"
      summary: "Calculate payment for period"
      description: "Calculate the periods (months) that are allowed for the specified purchase amount."
      operationId: "calculatePaymentForPeriod"
      produces:
        - "application/json"
      parameters:
        - in: "query"
          name: amount
          type: number
          required: true
        - in: "query"
          name: down_payment
          type: number
          default: 0
        - in: "query"
          name: period_months
          type: number
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/PaymentForPeriod'

securityDefinitions:
  basicAuth:
    type: basic
definitions:
  Period:
    type: object
    properties:
      period:
        type: number
        example: 3
      monthly_payment:
        type: number
        example: 163.27
  CalculatedPaymentPeriod:
    type: object
    properties:
      periods:
        type: array
        items:
          $ref: '#/definitions/Period'
  AllowedPeriods:
    type: object
    properties:
      periods:
        type: array
        items:
          type: number
  PaymentForPeriod:
    type: object
    properties:
      monthly_payment:
        type: number
        example: 52.69
      period_months:
        type: number
        example: 9
      total_credit:
        type: number
        example: 474.25
  AvailablePaymentMethod:
    type: object
    properties:
      key:
        type: string
        example: ESTO_HIRE_PURCHASE_LOAN
      name:
        type: string
        example: ESTO Regular hire purchase
      country_code:
        type: string
        example: EE
      schedule_type:
        type: string
        example: REGULAR
      type:
        type: string
        example: LOAN
      logo_url:
        type: string
        example: https://api.esto.ee/images/esto-logo-black.png
      is_test:
        type: boolean
        example: false
  ApplicationTerms:
    type: object
    properties:
      amount:
        type: number
        example: 150
      down_payment:
        type: number
        example: 20
      period_months:
        type: number
        example: 12
      monthly_payment:
        type: number
        example: 15.50
      total_credit:
        type: number
        example: 206
      annual_interest:
        type: number
        example: 9.9
      contract_fee:
        type: number
        example: 4.9
      apr:
        type: number
        example: 35.0
  PurchaseResponse:
    type: object
    properties:
      data:
        $ref: '#/definitions/ApplicationData'
      errors:
        type: array
  PurchaseResponseRedirect:
    type: object
    properties:
      data:
        $ref: '#/definitions/ApplicationDataRedirect'
      errors:
        type: array
  CustomerRedirect:
    type: object
    properties:
      first_name:
        type: string
        example: BoJack
      last_name:
        type: string
        example: Horseman
      email:
        type: string
        example: email@address.com
      phone:
        type: string
        example: 567891234
      address:
        type: string
        example: Hollywoo Blvd. 42
      city:
        type: string
        example: Los Angeles
      post_code:
        type: string
        example: 12345
  Customer:
    type: object
    properties:
      pin:
        type: string
        example: 11412090004
      document_nr:
        type: string
        example: A12345678
      document_type:
        type: string
        example: ID_CODE
      is_verified:
        type: boolean
        example: true
      first_name:
        type: string
        example: BoJack
      last_name:
        type: string
        example: Horseman
      email:
        type: string
        example: email@address.com
      phone:
        type: string
        example: 567891234
      address:
        type: string
        example: Hollywoo Blvd. 42
      city:
        type: string
        example: Los Angeles
      post_code:
        type: string
        example: 12345
      occupation_category:
        type: string
        example: STUDENT
      allow_pension_query:
        type: boolean
        example: true
      is_politically_exposed:
        type: string
        example: false
  PurchaseItem:
    type: object
    properties:
      name:
        type: string
        example: Bitcoin 101
      unit_price:
        type: number
        example: 30.3
      quantity:
        type: number
        example: 3
  PurchaseRequest:
    type: object
    properties:
      amount:
        type: number
        example: 150
      down_payment:
        type: number
        example: 20
      period_months:
        type: number
        example: 12
      reference:
        type: string
        example: fwejigjwe8g32g3jg
      connection_mode:
        type: number
        example: live
      items:
        type: array
        items:
          $ref: '#/definitions/PurchaseItem'
      customer:
        $ref: '#/definitions/Customer'
  PurchaseRequestRedirect:
    type: object
    required:
      - amount
      - reference
    properties:
      amount:
        type: string
        example: 91.80
      reference:
        type: string
        example: fwejigjwe8g32g3jg
      return_url:
        type: string
        example: https://your-site.com/return
      notification_url:
        type: string
        example: https://your-site.com/notification
      messege:
        type: string
        example: bla
      schedule_type:
        type: string
        enum:
          - REGULAR
          - ESTO_X
          - PAY_LATER
          - ESTO_PAY
      allowed_customer_types:
        type: array
        items:
          type: string
          example: NATURAL_PERSON
      payment_method_key:
        type: string
        example: bla
      cancel_url:
        type: string
        example: https://your-site.com/cancel
      connection_mode:
        type: string
        enum:
          - live
          - test
        example: live
      items:
        type: array
        items:
          $ref: '#/definitions/PurchaseItem'
      customer:
        $ref: '#/definitions/CustomerRedirect'
  ApplicationDataRedirect:
    type: object
    properties:
      id:
        type: string
        example: "vgks90vmd3mg09r0scakk"
      status:
        type: string
        example: "CREATED"
      purchase_url:
        type: string
        example: "https://esto.ee/purchase/vgks90vmd3mg09r0scakk"
      merchant_reference:
        type: string
        example: "gwjke9gdsf"
      amount:
        type: number
        example: 91.89
      currency:
        type: string
        example: "EUR"
      is_test:
        type: boolean
        example: false
      return_url:
        type: string
        example: "https://your-site.com/return"
      notification_url:
        type: string
        example: "https://your-site.com/notification"
  ApplicationData:
    type: object
    properties:
      id:
        type: string
        example: "vgks90vmd3mg09r0scakk"
      status:
        type: string
        example: "POSITIVE"
      redirect_url:
        type: string
        example: "https://esto.ee/p/LWYRUP?target=signing&logout=1"
      merchant_reference:
        type: string
        example: "gwjke9gdsf"
      currency:
        type: string
        example: "EUR"
      is_test:
        type: boolean
        example: false
      return_url:
        type: string
        example: "https://your-site.com/return"
      notification_url:
        type: string
        example: "https://your-site.com/notification"
      terms:
        type: object
        $ref: '#/definitions/ApplicationTerms'