---
openapi: 3.0.3
servers:
- url: https://pay.cashbill.pl/ws/rest
  description: PROD API
- url: https://pay.cashbill.pl/testws/rest
  description: TEST API
info:
  title: CashBill Payments API
  version: 1.0.0
  description: "To use REST API payment point should be configured as “Web Service”\
    .\n\nREST service is available at:\n```\n  https://pay.cashbill.pl/ws/rest/\n\
    ```\n\nTesting can be performed using:\n```\n  https://pay.cashbill.pl/testws/rest/\n\
    ```\n\n\nOn every successful request service returns **application/json** with\
    \ **HTTP 200**. In case of error, reply consists of HTTP status code with details\
    \ in response body.\n\n# Digital Signature (Authentication)\n\nDigital signature\
    \ can be generated by concatenation of request data with secret key, obtainable\
    \ in CashBill Control Panel.\n\nUsed crypto hash function is **SHA1**, with result\
    \ presented as hexadecimal lowercase string.\n\n# Error Response\n\nEvery error\
    \ response returns **application/json** with http status of error. JSON response\
    \ contains `errorMessage` key with more informations about error reason.\n\nex.\
    \ \n\n```\n\n  # HTTP 401 Unauthorized\n  {\n    \"errorMessage\" : \"Illegal\
    \ signature\"\n  }\n\n```\n```\n\n  # HTTP 400 Bad Request\n  {\n    \"errorMessage\"\
    \ : \"sign is required field\"\n  }\n\n```\n\n# Notification Service\n\nIf payment\
    \ point is configured as Web Service, CashBill Online Payments will communicate\
    \ with shop using notification service. URL for notification service must be configured\
    \ in CashBill Control Panel. Notification service can use HTTP or HTTPS protocol.\
    \ Notification request consist no sensitive data, and consists of:\n- name of\
    \ notification\n- attribute of notification\n- digital signature\n\n\nEach notification\
    \ is sent as GET request with following variables:\n\n|Variable|Description|\n\
    |--------|-----------|\n|cmd|name of notification|\n|args|comma (“,”) separated\
    \ attributes (for ex. orderId)|\n|sign|digital signature|\n\n### Digital Signature\n\
    ```\n\n  sign = md5(cmd + args + secretKey)\n\n```\nMD5 is crypto hash function,\
    \ with result presented as hexadecimal lowercase string.\n\n## Available Notification\
    \ Requests\n|Name of request|Description|\n|--------|-----------|\n|transactionStatusChanged|Status\
    \ of transaction has changed. Attribute: ID of the transaction in question|\n\n\
    \n## Response To Notification\n\nReception of request is confirmed by HTTP/200\
    \ OK status code, with body consisting of two bytes `OK`. \n\nAny other reply\
    \ will be treated as error, and request will be repeated.\n\n## Example Notification\n\
    \n```\n\n  https://shop_url.com/?cmd=transactionStatusChanged&args=asd34sf&sign=c8143d45bf2f76fd38a6a9d77feb1a79\n\
    \n```\nCustom notification URL for each shop can be settled in CashBill Control\
    \ Panel.\n\n# Available Transaction Statuses\n\n|Status|Description|\n|--------|-----------|\n\
    |PreStart|Payment has been started. Customer has not yet choosen payment channel.|\n\
    |Start|Payment has been started. Customer has not yet paid.|\n|NegativeAuthorization|Payment\
    \ Channel has refused payment (ie. insufficient funds).|\n|Abort|Customer has\
    \ aborted the payment.|\n|Fraud|Payment Channel has refused payment and classified\
    \ is as fraudant. This is a final status and cannot change.|\n|PositiveAuthorization|Payment\
    \ Channel has accepted transaction for processing.|\n|PositiveFinish|Payment Channel\
    \ has confirmed transfer of funds. This is a final status and cannot change.|\n"
  url: https://cashbill.pl
paths:
  /payment/{shopId}:
    post:
      description: |
        You can put information about landing page for exist transaction.
        >
        Generate digital signature using:
        >
        ```
        SHA1(title + amount.value + amount.currencyCode + returnUrl + description + negativeReturnUrl + additionalData + paymentChannel + languageCode + referer + personalData.firstName + personalData.surname + personalData.email + personalData.country + personalData.city + personalData.postcode + personalData.street + personalData.house + personalData.flat + personalData.ip + optionsKeyValueList + secretKey)
        ```
        >
        optionsKeyValueList is combination of key and value pair
        >
        ```
        optionsKeyValueList = key1 + value1 + ... + keyN + valueN
        ```
      summary: Creating new transaction
      parameters:
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - title
              - amount.value
              - amount.currencyCode
              - sign
              type: object
              properties:
                title:
                  minLength: 1
                  type: string
                amount.value:
                  minLength: 1
                  type: string
                amount.currencyCode:
                  minLength: 1
                  type: string
                returnUrl:
                  default: ""
                  type: string
                description:
                  default: ""
                  type: string
                negativeReturnUrl:
                  default: ""
                  type: string
                additionalData:
                  default: ""
                  type: string
                paymentChannel:
                  default: ""
                  type: string
                languageCode:
                  default: ""
                  type: string
                referer:
                  default: ""
                  type: string
                personalData.firstName:
                  default: ""
                  type: string
                personalData.surname:
                  default: ""
                  type: string
                personalData.email:
                  default: ""
                  type: string
                personalData.country:
                  default: ""
                  type: string
                personalData.city:
                  default: ""
                  type: string
                personalData.postcode:
                  default: ""
                  type: string
                personalData.street:
                  default: ""
                  type: string
                personalData.house:
                  default: ""
                  type: string
                personalData.flat:
                  default: ""
                  type: string
                personalData.ip:
                  default: ""
                  type: string
                options:
                  default: ""
                  type: string
                sign:
                  minLength: 1
                  type: string
          application/json:
            schema:
              $ref: "#/components/schemas/APINewPayment"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APINewPaymentData"
        "400":
          description: Bad Request
      tags:
      - Payment Resource
  /payment/{shopId}/{orderId}:
    put:
      description: |
        You can put information about landing page for exist transaction.
        >
        Generate digital signature using:
        >

        ```
        SHA1(orderId + returnUrl + negativeReturnUrl + secretKey)
        ```
      summary: Putting landing page URL for exist transaction
      parameters:
      - description: Order ID
        name: orderId
        in: path
        required: true
        schema:
          type: string
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - returnUrl
              - sign
              type: object
              properties:
                returnUrl:
                  minLength: 1
                  type: string
                negativeReturnUrl:
                  type: string
                sign:
                  minLength: 1
                  type: string
          application/json:
            schema:
              $ref: "#/components/schemas/APIReturnURL"
        required: true
      responses:
        "204":
          description: The return urls has been successfully updated.
        "400":
          description: Bad Request
      tags:
      - Payment Resource
    get:
      description: |
        You can request detailed information about transaction.
        >
        Generate digital signature using:
        >
        ```
        SHA1(orderId + secretKey)
        ```
      summary: Requesting details of transaction
      parameters:
      - description: Order ID
        name: orderId
        in: path
        required: true
        schema:
          type: string
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      - description: Digital signarute
        name: sign
        in: query
        schema:
          minLength: 1
          type: string
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIPayment"
      tags:
      - Payment Resource
  /paymentchannels/{shopId}/{languageCode}:
    get:
      summary: Requesting available payment channels
      description: You can obtain list of available payment channels from paymentchannels
        resource.
      parameters:
      - description: "Language code (PL, EN)"
        name: languageCode
        in: path
        required: true
        schema:
          default: PL
          pattern: "(([a-zA-Z]{2})?)"
          type: string
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/APIPaymentChannel"
      tags:
      - Payment Channels Resource
  /paymentchannels/{shopId}:
    get:
      summary: Requesting available payment channels
      description: You can obtain list of available payment channels from paymentchannels
        resource.
      parameters:
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/APIPaymentChannel"
      tags:
      - Payment Channels Resource
  /additionaldata/{shopId}/{orderId}:
    get:
      summary: Retrieve additional transaction data
      description: |
        You can retrieve additional information for a transaction, such as BLIK alias details.
        >
        Generate digital signature using:
        >
        ```
        SHA1(orderId + secretKey)
        ```
      parameters:
      - description: Order ID
        name: orderId
        in: path
        required: true
        schema:
          type: string
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      - name: sign
        in: query
        schema:
          minLength: 1
          type: string
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIAdditionalData"
      tags:
      - Additional Data Resource
  /blik/alias/{shopId}/{orderId}/unregister:
    post:
      summary: Unregister BLIK alias
      description: |-
        You can unregister the BLIK alias associated with a transaction.
        >
        Generate digital signature using:
        >
        ```
        SHA1(orderId + secretKey)
        ```
      parameters:
      - description: Order ID
        name: orderId
        in: path
        required: true
        schema:
          type: string
      - description: Payment Point ID
        name: shopId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - sign
              type: object
              properties:
                sign:
                  minLength: 1
                  type: string
          application/json:
            schema:
              $ref: "#/components/schemas/APISign"
        required: true
      responses:
        "201":
          description: Created
        "204":
          description: The alias was successfully unregistered
        "400":
          description: Bad Request
      tags:
      - Blik Alias Resource
components:
  schemas:
    APIAdditionalData:
      type: object
      properties:
        alias:
          $ref: "#/components/schemas/APIAlias"
        paramAliasList:
          $ref: "#/components/schemas/APIParamAliasList"
    APIAlias:
      type: object
      properties:
        scope:
          $ref: "#/components/schemas/APIScope"
        value:
          type: string
        valueType:
          type: string
        usage:
          type: string
    APIAmount:
      required:
      - value
      - currencyCode
      type: object
      properties:
        value:
          description: Amount of transaction. Use dot “.” as decimal separator.
          multipleOf: 0.01
          minimum: 0.0
          exclusiveMinimum: true
          type: number
        currencyCode:
          description: ISO 4217 currency code
          minLength: 1
          type: string
    APIDetails:
      type: object
      properties:
        bankId:
          description: "The internal bank id, if provided."
          type: string
    APINewPayment:
      required:
      - title
      - amount
      - sign
      type: object
      properties:
        title:
          description: Title of the transaction
          minLength: 1
          type: string
        amount:
          description: Amount with currency code of transaction
          type: object
          allOf:
          - $ref: "#/components/schemas/APIAmount"
        description:
          description: Description of the transaction
          type: string
        additionalData:
          description: "Additional transaction data, hidden from customer"
          type: string
        returnUrl:
          description: URL of landing page after successful transaction
          type: string
        negativeReturnUrl:
          description: "URL of landing page after unsuccessfull transaction. If ommited,\
            \ customer will be redirected to returnUrl"
          type: string
        paymentChannel:
          description: "ID of payment channel obtained from GET paymentchannels, request.\
            \ If ommited, customer will be prompted with default CashBill payment\
            \ channel selection screen."
          type: string
        languageCode:
          description: "Language code. Available: PL, EN"
          type: string
        personalData:
          description: Client personal data
          type: object
          allOf:
          - $ref: "#/components/schemas/APIPersonalData"
        referer:
          description: Shopping platform identifier
          type: string
        options:
          description: List of additional options for transaction
          type: array
          items:
            $ref: "#/components/schemas/APIOption"
        sign:
          description: Digital signature
          minLength: 1
          type: string
    APINewPaymentData:
      type: object
      properties:
        id:
          description: Payment Id
          type: string
        redirectUrl:
          description: The address to which the browser should redirect customer to
            start payment
          type: string
        additional:
          type: object
          additionalProperties:
            type: string
    APIOption:
      type: object
      properties:
        name:
          description: Name of the additional option
          type: string
        value:
          description: Value of the additional option
          type: string
    APIParamAliasItem:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    APIParamAliasList:
      type: object
      properties:
        paramAlias:
          type: array
          items:
            $ref: "#/components/schemas/APIParamAliasItem"
    APIPayment:
      type: object
      properties:
        id:
          type: string
        paymentChannel:
          type: string
        amount:
          $ref: "#/components/schemas/APIAmount"
        requestedAmount:
          $ref: "#/components/schemas/APIAmount"
        title:
          type: string
        description:
          type: string
        personalData:
          $ref: "#/components/schemas/APIPersonalData"
        additionalData:
          type: string
        status:
          type: string
        details:
          $ref: "#/components/schemas/APIDetails"
    APIPaymentChannel:
      type: object
      properties:
        id:
          description: Payment Channel ID
          type: string
        availableCurrencies:
          description: List of available currencies
          type: array
          items:
            type: string
        name:
          description: Name
          type: string
        description:
          description: Description
          type: string
        logoUrl:
          description: URL of image
          type: string
    APIPersonalData:
      type: object
      properties:
        firstName:
          description: First name
          type: string
        surname:
          description: Surname
          type: string
        email:
          description: E-mail
          type: string
        country:
          description: Country
          type: string
        city:
          description: City
          type: string
        postcode:
          description: Post code
          type: string
        street:
          description: Street
          type: string
        house:
          description: Building no
          type: string
        flat:
          description: Flat no
          type: string
        ip:
          description: IP in IPv4 format
          type: string
    APIReturnURL:
      required:
      - returnUrl
      - sign
      type: object
      properties:
        returnUrl:
          description: URL of landing page after successful transaction
          minLength: 1
          type: string
        negativeReturnUrl:
          description: "URL of landing page after unsuccessfull transaction. If ommited,\
            \ customer will be redirected to returnUrl"
          type: string
        sign:
          description: Digital signature
          minLength: 1
          type: string
    APIScope:
      type: object
      properties:
        acqId:
          format: int32
          type: integer
        merchId:
          type: string
    APISign:
      required:
      - sign
      type: object
      properties:
        sign:
          description: Digital signature
          minLength: 1
          type: string