openapi: 3.2.0
info:
  title: Assembly Fees API
  description: Assembly (formely PromisePay) is a powerful payments engine custom-built for platforms and marketplaces.
  version: '2.3'
  contact:
    email: support@assemblypayments.com
    url: http://docs.assemblypayments.com/
servers:
- url: https://test.api.promisepay.com
  description: Pre-live environment
- url: https://secure.api.promisepay.com
  description: Production environment
- url: https://au-0000.sandbox.auth.assemblypay.com
  description: Pre-Live (Sandbox) Auth issuing server and API
- url: https://au-0000.auth.assemblypay.com
  description: Production Auth issuing server and API
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/AssemblyPlatforms/assembly-api/2.3
security:
- oAuth2ClientCredentials: []
tags:
- name: Fees
paths:
  /fees:
    get:
      tags:
      - Fees
      summary: List Fees
      description: Retrieve an ordered and paginated list of existing **Fees**.
      operationId: listFees
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fees'
              examples:
                response:
                  value:
                    fees:
                    - id: 59826643-35d7-441f-bf44-978df61a80ae
                      created_at: '2020-05-03T11:32:01.092Z'
                      updated_at: '2020-05-03T11:32:01.092Z'
                      name: marketplace-bpay
                      fee_type_id: 1
                      amount: 150
                      cap: null
                      min: null
                      max: null
                      to: buyer
                      links:
                        self: /fees/59826643-35d7-441f-bf44-978df61a80ae
                    meta:
                      limit: 10
                      offset: 0
                      total: 1
                    links:
                      self: /fees
    post:
      tags:
      - Fees
      summary: Create fee
      description: 'Create a **Fee** to be associated with an **Item**. **Fees** will add or subtract from the **Item** amount based on the **User**, payment type or Disbursement account type. **Fees** can be `Fixed` or `Percentage` based. **Fees** can be capped, have a maximum amount and/or a minimum amount.

        '
      operationId: createFee
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fee_requestBody'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/single_fee'
              examples:
                response:
                  value:
                    fees:
                      id: 1e5e372a-df3a-4f77-af2f-ec294b1715ce
                      created_at: '2016-04-18T05:21:27.339Z'
                      updated_at: '2016-04-18T05:21:27.339Z'
                      name: Seller Success Fee
                      fee_type_id: 2
                      amount: 200
                      cap: null
                      min: null
                      max: null
                      to: seller
                      links:
                        self: /fees/1e5e372a-df3a-4f77-af2f-ec294b1715ce
  /fees/{id}:
    get:
      tags:
      - Fees
      summary: Show Fee
      description: 'Show details of a specific **Fee** using a given `:id`. If the `item_amount` is specified, the response also shows the `calculated_fee` based on a percentage of the `item_amount`.

        '
      operationId: showFee
      parameters:
      - name: id
        in: path
        description: Fee ID
        required: true
        style: simple
        explode: false
        schema:
          type: string
          default: 1e5e372a-df3a-4f77-af2f-ec294b1715ce
        example: 1e5e372a-df3a-4f77-af2f-ec294b1715ce
      - name: item_amount
        in: query
        description: The cost of the item in cents on which the calculated Fee is based
        required: true
        style: form
        explode: true
        schema:
          type: integer
          default: '200'
        example: '200'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/single_fee'
              examples:
                response:
                  value:
                    fees:
                      id: 1e5e372a-df3a-4f77-af2f-ec294b1715ce
                      created_at: '2016-04-18T05:21:27.339Z'
                      updated_at: '2016-04-18T05:21:27.339Z'
                      name: Seller Success Fee
                      fee_type_id: 2
                      amount: 200
                      cap: null
                      min: null
                      max: null
                      to: seller
                      calculated_fee: 10
                      links:
                        self: /fees/1e5e372a-df3a-4f77-af2f-ec294b1715ce
components:
  schemas:
    fee:
      type: object
      properties:
        id:
          type: string
          example: 36020976-f345-4d0f-b860-9c025ccce668
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        name:
          type: string
          example: Seller Success Fee
        fee_type_id:
          type: string
          example: 2
        amount:
          type: string
          example: 200
        cap:
          type: string
          example: null
        min:
          type: string
          example: null
        max:
          type: string
          example: null
        to:
          type: string
          example: seller
        calculated_fee:
          type: integer
          description: This field is only shown in case an item amount is passed
          readOnly: true
          example: 400
        links:
          type: object
          properties:
            self:
              type: string
    single_fee:
      properties:
        fees:
          $ref: '#/components/schemas/fee'
    fees:
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/fee'
        meta:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            total:
              type: integer
        links:
          type: object
          properties:
            self:
              type: string
    fee_requestBody:
      type: object
      required:
      - name
      - fee_type_id
      - amount
      properties:
        name:
          description: Name
          type: string
          example: Seller Success Fee
          default: Seller Success Fee
        fee_type_id:
          description: "Fee type:\n  1. Fixed\n  2. Percentage\n  3. Percentage with Cap\n  4. Percentage with Min\n"
          type: string
          enum:
          - '1'
          - '2'
          - '3'
          - '4'
          example: '2'
          default: '2'
        amount:
          description: Amount in cents; if the fee type is percentage, then this shows the percentage in hundredths (For example, an amount of 5 refers to 0.05% in fees.)
          type: integer
          example: 200
          default: 200
        cap:
          description: Cap the Fee
          type: string
          example: ''
        min:
          description: Minimum Fee
          type: integer
          example: ''
        max:
          description: Maximum Fee
          type: integer
          example: ''
        to:
          description: Who pays the Fee. Allowed values are (buyer or seller). If this field has a value of buyer, then the buyer will have to pay the fee on top of the actual payment (example for an item of 100 and a fee of 2, then the buyer would have to pay 102) If this field has a value of seller, then the seller will end up receiving the amount - the fee (example for an item of 100 and a fee of 2, then the seller would end up receiving 98)
          type: string
          enum:
          - buyer
          - seller
          - cc
          - int_wire
          example: seller
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of records to offset. Required for pagination.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    limitParam:
      name: limit
      in: query
      description: Number of records to retrieve. Up to 200.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 10
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: Please refer to Authentication section within https://developer.assemblypayments.com/reference#authentication
      flows:
        clientCredentials:
          tokenUrl: https://au-0000.sandbox.auth.assemblypay.com/tokens
          scopes: {}
x-explorer-enabled: false
x-samples-languages:
- curl
- ruby
- php
- javascript
- csharp
- go
x-proxy-enabled: true
x-samples-enabled: true