openapi: 3.0.0
info:
  title: Payments API
  version: 1.1.1
  description: >
    API to make payments via premiumpay

    ## Introduction

    This API is documented in **OpenAPI format** and is used to make payments
    via premiumpay.

    ## Authentication

    This API uses **Bearer Token** for authentication. You need to pass the
    **APIKEY** in the header as Authorization.


    To get the APIKEY, you need to register on premiumpay.pro (or betandeal.com)
    and ask admin to be authorized to use the API.

    ## Callback format

    When the payment is done by the user, the callback url provided in
    /makepayment will be called with the following format (example):

    ```json

    {
      "clientOrderId": "12345ORD6789",
      "paymentId": 123456,
      "amount": 10.01,
      "currency": "EUR",
      "status": "ok",
      "message": "Payment successful",
      "paymentMethod": "stripe2",
      "token": "29e15f05b8225b18358239c306621d52"
    }

    ```
servers:
  - url: http://localhost:8088/api/{basePath}
    variables:
      basePath:
        default: v1
    description: Local development server
  - url: https://pre.api.premiumpay.pro/api/{basePath}
    variables:
      basePath:
        default: v1
    description: Pre-production server
  - url: https://api.premiumpay.pro/api/{basePath}
    variables:
      basePath:
        default: v1
    description: Production server
paths:
  /version:
    get:
      operationId: api.getVersion
      summary: Get current version
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    $ref: '#/components/schemas/Response'
                  version:
                    $ref: '#/components/schemas/Version'
  /status:
    get:
      operationId: api.getStatus
      summary: Get status of API, up and running or down
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    $ref: '#/components/schemas/Response'
                  apistatus:
                    $ref: '#/components/schemas/Status'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/BadJson'
  /makepayment:
    post:
      operationId: api.makePayment
      summary: Make payment
      description: Request a new payment link to premiumpay
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Paymentrequest'
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    $ref: '#/components/schemas/Response'
                  payment:
                    $ref: '#/components/schemas/Paymentresponse'
                  error:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/BadJson'
components:
  responses:
    PaymentResponse:
      description: Payment request response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Paymentresponse'
    BadRequest:
      description: Invalid parameters received
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    BadJson:
      description: Invalid JSON received
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
      description: If invalid token
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Forbidden'
      description: If insufficient user permissions
  schemas:
    Paymentrequest:
      type: object
      required:
        - amount
        - currency
        - productDescription
        - productName
        - clientOrderId
        - clientIP
        - clientEmail
        - okurl
        - kourl
        - callbackurl
      properties:
        amount:
          type: number
          format: double
          description: Amount to pay
          example: 10.01
        currency:
          type: string
          description: Currency to pay in
          example: EUR
        productDescription:
          type: string
          description: Product description
          example: Product description
        productName:
          type: string
          description: Product name
          example: Product name
        clientOrderId:
          type: string
          description: Client order id
          example: 12345ORD6789
        clientIP:
          type: string
          description: Client IP
          example: 154.36.22.12
        clientEmail:
          type: string
          description: Client email
          example: email@demo.com
        okurl:
          type: string
          description: URL to redirect to on success
          example: https://demo.com/success
        kourl:
          type: string
          description: URL to redirect to on failure
          example: https://demo.com/failure
        cancelurl:
          type: string
          description: URL to redirect to on cancel
          example: https://demo.com/cancel
        callbackurl:
          type: string
          description: URL to call on payment status change
          example: https://demo.com/callback
        paymentMethods:
          type: array
          items:
            type: string
          description: Payment methods to use
          example:
            - stripe2
            - bizum
        tokenizer:
          type: boolean
          description: Whether to tokenize card or not
          example: true
        token:
          type: string
          description: Token to use for payment
          example: 29e15f05b8225b18358239c306621d52
        expiry:
          type: number
          description: Number of minutes until payment link expires
          example: 30
        headers:
          type: boolean
          description: Whether to show premiumpay headers and footers or not
          example: true
    Paymentresponse:
      type: object
      required:
        - paymentid
        - redirecturl
      properties:
        paymentid:
          type: string
          description: Payment id
          example: '123456'
        paymenturl:
          type: string
          description: Payment URL to redirect to
          example: https://premiumpay.pro/apistep2/be823469zjkid45306abf
    Forbidden:
      type: object
      properties:
        status:
          type: string
          enum:
            - ko
            - ok
          example: ko
        error:
          type: string
          example: error reason
    Unauthorized:
      type: object
      properties:
        status:
          type: string
          enum:
            - ko
            - ok
          example: ko
        error:
          type: string
          example: error reason
    BadRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - ko
            - ok
          example: ko
        error:
          type: string
          example: error reason
    Response:
      type: string
      enum:
        - ok
        - ko
      example: ok
    Version:
      type: string
      description: Current API version
      example: 1.0.0
    Status:
      type: string
      enum:
        - ok
        - ko
    CallbackResponse:
      type: object
      properties:
        clientOrderId:
          type: string
          description: Client order id
        paymentId:
          type: number
          description: Payment id
        amount:
          type: number
          description: Amount paid
        currency:
          type: string
          description: Currency paid in
        status:
          type: string
          description: Payment status
        message:
          type: string
          description: Payment message
        paymentMethod:
          type: string
          description: Payment method used
        token:
          type: string
          description: Token for recurring payments
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKEY
