openapi: 3.0.0
info:
  description: "This API has Super Cow Powers!"
  version: "0.3.0-rc5"
  title: "Drakemall Payment Gateway"
  termsOfService: "https://dev.drakemall.com/terms/"
  contact:
    email: "vitaly.krivtsov@bets.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
  - url: https://dev.drakemall.com/api
  - url: https://drakemall.com/api

tags:
  - name: "payments"
    description: ""
    externalDocs:
      description: "Find out more"
      url: "https://github.com/skinholdings/drakemall-payment-gateway"
paths:
  /payment/voucherifyio/replenish:
    post:
      tags:
        - "payments"
      summary: "Replenish balance using gift cart"
      description: >
        I am as a customer i can use gift card from https://www.kinguin.net/ to replenish balance on my account.
        Usually it takes a several seconds to redeem a voucher.
        Please note, operation is async and will be completed later, success response does not mean that a voucher is redeemed

      operationId: "replenishBalanceViaGiftCart"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  description: "A gift card code, use fetchTestVoucher operation in order to get one"
                  type: "string"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  ok:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: >
                      Code 2HvR-FeqG-OfvE successfully redeemed.
                      Transaction $50.00 is in progress.
                      Please, check balance later.
                  amount:
                    type: number
                    example: 50.0
        400:
          description: "Bad Request"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/GiftCartAlreadyRedeemedError"
                  - $ref: "#/components/schemas/UnsupportedVoucherError"
                  - $ref: "#/components/schemas/VoucherDisabledError"
              examples:
                UnsupportedVoucherError:
                  value:
                    statusCode: 400
                    code: UNSUPPORTED_VOUCHER_ERROR
                    message: >
                      Unsupported type of voucher, should be a gift card. Please, use another voucher code
        429:
          description: "Too many requests"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VoucherifyTooManyRequestsError"

      security:
        - bearerAuth: []

  /payment/voucherifyio/fixtures:
    get:
      tags:
        - "payments"
      summary: "Get a voucher from SandBox environment for testing (voucherify.io)"
      description: ""
      operationId: "fetchTestVoucher"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Voucher"

  /payment/voucherifyio/fixtures/promo-code:
    get:
      tags:
        - "payments"
      summary: "Get a promo code from SandBox environment for testing (voucherify.io)"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Voucher"

  /payment/conf:
    get:
      tags:
        - "payments"
      summary: "Get payment config"
      description: ""
      operationId: "getConfig"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  preferred_payment_gateway:
                    type: string
                    example: "paymentiq"
                  allowed_payment_gateways:
                    type: array
                    items: string
                    example:
                      - paymentiq
                      - voucherifyio
                      - accent_pay
                  payment_providers:
                    type: "object"
                    properties:
                      name:
                        type: string
                      short_name:
                        type: string
                      amount_steps:
                        type: array
                        items: integer
                        uniqueItems: true
                        example:
                          - 20
                          - 50
                          - 100
                          - 250
                      min_amount:
                        type: "integer"
                        minimum: 5
                        example: 5
                      max_amount:
                        type: "integer"
                        example: 2000
                        maximum: 2000
                    required:
                      - name
                      - short_name
                required:
                  - preferred_payment_gateway
                  - allowed_payment_gateways
                  - payment_providers
  /payment/accent_pay/replenish:
    post:
      tags:
        - "payments"
      summary: "Get accent pay payment page link"
      description: ""
      operationId: "replenishBalanceViaAccentPay"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                amount:
                  description: "An amount to replenish"
                  type: "integer"
                  format: "int32"
                  example: 5
                redirectTo:
                  description: "A redirect link. Preferably valid url like: http://localhost:8000/profile or simle path like: /profile"
                  type: "string"
                  example: [ "/payment", "https://drakemall.com/profile" ]
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    example: "https://paymentpage.ecommpay.com/payment?customer_id=cj99tfbgi022d0o2kuag9ypg6&payment_currency=USD&payment_id=bdbb1e62-bea8-403c-b1e1-f606774841f1&project_id=418&redirect_fail_url=http%3A%2F%2Flocalhost%3A8000%2Fpayment%3Fuser_id%3Dcj99tfbgi022d0o2kuag9ypg6&redirect_success_url=http%3A%2F%2Flocalhost%3A8000%2Fpayment%3Fuser_id%3Dcj99tfbgi022d0o2kuag9ypg6&payment_amount=100&signature=7BXzSx%2FKZATQgK9O66CQBa5kZcnn8FxznygUsLZuLP%2F9bazmNapkVHSxX6gilmJKiIJxjwE70ZHYhkbMt4v8%2Fg%3D%3D"
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Something went wrong'
                  errorCode:
                    type: int
                    example: 400
                  errors:
                    type: array
                    example: ['error 1', 'error 2', 'error 3']
      security:
        - bearerAuth: []

  /payment/accent_pay/postback:
    post:
      tags:
        - "payments"
      summary: "Receive Accent Pay post back"
      description: "This API is always returning Status code 200 as the payment system demands"
      operationId: "apayPostBack"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /payment/cardpay/replenish:
    post:
      tags:
      - "payments"
      summary: "Get CardPay payment page link"
      description:
      operationId: "replenishBalanceViaCardPay"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                amount:
                  description: "An amount to replenish"
                  type: "integer"
                  format: "int32"
                  example: 5
  /payment/paymentiq/replenish:
    post:
      tags:
        - "payments"
      summary: "Get the PaymentIQ iframe page link"
      description: "During page link generation we create user `sessionId` and pair it to user for further usage"
      operationID: "replenishBalanceViaPaymentIQ"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    example: "https://cashier.paymentiq.io/#/merchant/100074002/user/cje0crukc00040lmyt5ih8j6k/method/deposit?&container=iframe&iframeWidth=400&iframeHeight=700&sessionid=5d99614e-e90d-44e7-bfab-129969227b23"
                  success:
                    type: bool
                    example: true
        400:
          description: "Bad request"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Something went wrong'
                  errorCode:
                    type: int
                    example: 400
                  errors:
                    type: array
                    example: ['error 1', 'error 2', 'error 3']
      security:
      - bearerAuth: []

  /payment/paymentiq/verifyuser:
    post:
      tags:
        - "payments"
      summary: "PaymentIQ verifies user info during user request on PaymentIQ cashier page"
      description: "While users cashier page is loading, PaymentIQ checks personal info of the user using `sessionId`"
      operationId: "paymentIQverifyUser"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                userId:
                  description: "User ID"
                  type: "string"
                  example: "cje0crukc00040lmyt5ih8j6k"
                sessionId:
                  description: "Users `sessionId` generated during `/replenish`"
                  type: "string"
                  format: "uuid"
                  example: "5d99614e-e90d-44e7-bfab-129969227b23"
      responses:
        200:
          description: "Verify user response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIQVerifyUserFullResponse"

  /payment/paymentiq/authorizeTransfer:
    post:
      tags:
        - "payments"
      summary: "PaymentIQ ensures we prepare the transaction for user"
      operationId: "paymentIQauthorizeTransfer"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                userId:
                  description: "User ID"
                  type: "string"
                  example: "cje0crukc00040lmyt5ih8j6k"
                txId:
                  description: "PaymentIQ unique transaction-id"
                  type: "string"
                  example: "50360964"
                txAmount:
                  description: "Deposit amount"
                  type: "string"
                  example: "100.50"
                txAmountCy:
                  description: "Amount currency"
                  type: "string"
                  example: "USD or EUR"
      responses:
        200:
          description: "Verify user response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIQAuthorizeFullResponse"

  /payment/paymentiq/transfer:
    post:
      tags:
        - "payments"
      summary: "PaymentIQ approves transaction and so do we"
      operationId: "paymentIQtransfer"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                txId:
                  description: "PaymentIQ unique transaction-id"
                  type: "string"
                  example: "50360964"
                txAmount:
                  description: "Deposit amount"
                  type: "string"
                  example: "100.50"
                txAmountCy:
                  description: "Amount currency"
                  type: "string"
                  example: "USD or EUR"
      responses:
        200:
          description: "Verify user response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIQTransferFullResponse"

  /payment/paymentiq/cancel:
    post:
      tags:
        - "payments"
      summary: "PaymentIQ declines the transaction and so do we"
      operationId: "paymentIQcancel"
      requestBody:
        content:
          application/json:
            schema:
              type: "object"
              properties:
                txId:
                  description: "PaymentIQ unique transaction-id"
                  type: "string"
                  example: "50360964"
                txAmountCy:
                  description: "Amount currency"
                  type: "string"
                  example: "USD or EUR"
      responses:
        200:
          description: "Verify user response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentIQCancelFullResponse"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    VoucherifyTooManyRequestsError:
      type: "object"
      properties:
        ok:
          type: bool
          example: false
        message:
          type: string
          example: >
            Gift Unable to redeem your gift card, please try again in an hour
        statusCode:
          type: integer
          example: 429
        retryAfter:
          type: integer
          example: 3600
    GiftCartAlreadyRedeemedError:
      type: "object"
      properties:
        ok:
          type: bool
          example: false
        message:
          type: string
          example: >
            Gift card is already redeemed, please try another code
        statusCode:
          type: integer
          example: 400
    VoucherDisabledError:
      type: "object"
      properties:
        ok:
          type: bool
          example: false
        message:
          type: string
          example: >
            Voucher is not active (disabled by company), please try another code
        statusCode:
          type: integer
          example: 400
    UnsupportedVoucherError:
      type: "object"
      properties:
        ok:
          type: bool
          example: false
        message:
          type: string
          example: >
            Unsupported type of voucher, should be a gift card. Please, use another voucher code
        statusCode:
          type: integer
          example: 400
    Voucher:
      type: "object"
      properties:
        id:
          type: "string"
        code:
          type: "string"
    ApiResponse:
      type: "object"
      properties:
        code:
          type: "integer"
          format: "int32"
        type:
          type: "string"
        message:
          type: "string"
    PaymentIQVerifyUserFullResponse:
      type: "object"
      oneOf:
        - $ref: "#/components/schemas/PaymentIQVerifyUserResponse"
        - $ref: "#/components/schemas/PaymentIQErrorResponse"
    PaymentIQVerifyUserResponse:
      type: "object"
      properties:
        userId:
          description: "User ID"
          type: "string"
          example: "cje0crukc00040lmyt5ih8j6k"
        success:
          description: "Operation status"
          type: "bool"
          example: true
        firstName:
          description: "Users first Name"
          type: "string"
          example: "John"
        lastName:
          description: "Users last Name"
          type: "string"
          example: "Snow"
        street:
          description: "Users living street"
          type: "string"
          example: "Highway to hell"
        city:
          description: "Users living city"
          type: "string"
          example: "Berlin"
        zip:
          description: "Users zip code"
          type: "string"
          example: "02315"
        email:
          description: "Users email"
          type: "string"
          example: "02315"
        country:
          description: "Users country code"
          type: "string"
          example: "UKR"
          format: "countryISOAlpha3"
        mobile:
          description: "Users phone number"
          type: "string"
          example: "+380500000000"
        dob:
          decription: "Users date of birth YYYY-MM-DD"
          type: "string"
          example: "1981-01-01"
        balance:
          description: "Users balance in USD or EUR"
          type: "string"
          example: "100.30"
        balanceCy:
          description: "Users currency"
          type: "string"
          example: "USD or EUR"
    PaymentIQAuthorizeFullResponse:
      type: "object"
      oneOf:
        - $ref: "#/components/schemas/PaymentIQAuthorizeResponse"
        - $ref: "#/components/schemas/PaymentIQErrorResponse"
    PaymentIQAuthorizeResponse:
      type: "object"
      properties:
        userId:
          description: "User ID"
          type: "string"
          example: "cje0crukc00040lmyt5ih8j6k"
        success:
          description: "Operation status"
          type: "bool"
          example: true
        merchantTxId:
          description: "Merchant's unique transaction-id (`TraceID`)"
          type: "string"
          format: "uuid"
        txId:
          description: "Deprecated field. The same as merchantTxId"
          type: "string"
          format: "uuid"
        authCode:
          description: "Unique authorization code"
          type: "string"
          format: "uuid"
    PaymentIQTransferFullResponse:
      type: "object"
      oneOf:
        - $ref: "#/components/schemas/PaymentIQTransferResponse"
        - $ref: "#/components/schemas/PaymentIQErrorResponse"
    PaymentIQTransferResponse:
      type: "object"
      properties:
        userId:
          description: "User ID"
          type: "string"
          example: "cje0crukc00040lmyt5ih8j6k"
        success:
          description: "Operation status"
          type: "bool"
          example: true
        merchantTxId:
          description: "Merchant's unique transaction-id (`TraceID`)"
          type: "string"
          format: "uuid"
        txId:
          description: "PaymentIQ unique transaction-id"
          type: "string"
          format: "uuid"
    PaymentIQCancelFullResponse:
      type: "object"
      oneOf:
        - $ref: "#/components/schemas/PaymentIQCancelResponse"
        - $ref: "#/components/schemas/PaymentIQErrorResponse"
    PaymentIQCancelResponse:
      type: "object"
      properties:
        userId:
          description: "User ID"
          type: "string"
          example: "cje0crukc00040lmyt5ih8j6k"
        success:
          description: "Operation status"
          type: "bool"
          example: true
    PaymentIQErrorResponse:
      type: "object"
      properties:
        success:
          type: "bool"
          description: "Operation status"
          example: false
        errCode:
          type: "string"
          description: "Custom error code"
          example: "E10003"
        errMsg:
          type: "string"
          description: "Custom error message"
          example: "Missing userTrx"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"