Phasio Payments API

openapi: 3.2.0
info:
  title: Phasio Payments API
  description: This is the API documentation for the Phasio application.
  version: '1.0'
servers:
- url: https://m-api.eu.phas.io
  description: Generated server url
security:
- Phasio API Bearer Token: []
tags:
- name: Payments
  description: Manage payments for orders
paths:
  /api/manufacturer/v1/order/{orderId}/payment/confirm:
    post:
      tags:
      - Payments
      summary: Accept an offline payment obligation
      description: Converts a quote to an accepted order without marking its payment as paid
      operationId: acceptOfflinePayment
      parameters:
      - name: orderId
        in: path
        description: ID of the order to confirm payment for
        required: true
        schema:
          type: integer
          format: int64
        example: 1
      - name: purchaseOrderNumber
        in: query
        description: Purchase order number
        required: false
        schema:
          type: string
      - name: message
        in: query
        description: Message
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Purchase order PDF file
      responses:
        '200':
          description: Offline payment obligation accepted
          content:
            text/plain: {}
        '400':
          description: Failed to confirm payment
          content:
            text/plain: {}
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/manufacturer/v1/order/{orderId}/payment/status:
    patch:
      tags:
      - Payments
      summary: Update payment status
      description: Modifies an order's payment status
      operationId: updatePaymentStatus
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentStatusDto'
        required: true
      responses:
        '200':
          description: Payment status successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDto'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: 'Order has not converted from quote state or is being moved to Externally Tracked; error codes: ORDER_NOT_FOUND, ORDER_WRONG_STATE, ORDER_EXTERNALLY_TRACKED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ParcelAllocationDto:
      type: object
      properties:
        requisitionId:
          type: integer
          format: int64
        quantity:
          type: integer
      required:
      - quantity
      - requisitionId
    CollectionShipmentDto:
      allOf:
      - $ref: '#/components/schemas/ShipmentDto'
      description: Collection shipment with no destination address or tracking
      required:
      - documents
      - fromAddress
      - parcels
      - type
    ShippingDto:
      type: object
      discriminator:
        propertyName: shippingMode
      properties:
        id:
          type: integer
          format: int64
        operatorId:
          type: integer
          format: int64
        shippingMode:
          type: string
          enum:
          - SELF_COLLECTION
          - FIXED_PRICE
          - CARRIER_ACCOUNT
          - CUSTOMER_ACCOUNT
        shippingMethodId:
          type: integer
          format: int64
        customerOrganisationId:
          type: integer
          format: int64
        rateId:
          type: string
        toAddressId:
          type: integer
          format: int64
        expectedDispatchDate:
          type: string
          format: date
        incoterm:
          type: string
          enum:
          - EXW
          - FCA
          - CPT
          - CIP
          - DAP
          - DPU
          - DDP
          - FAS
          - FOB
          - CFR
          - CIF
        dispatchDate:
          type: string
          format: date
          readOnly: true
      required:
      - operatorId
      - shippingMode
    ShipmentUserDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        displayName:
          type: string
      required:
      - firstName
      - id
      - lastName
    UpdatePaymentStatusDto:
      type: object
      properties:
        status:
          type: string
          enum:
          - UNPAID
          - PROCESSING
          - REFUNDED
          - PAID
          - EXTERNALLY_TRACKED
      required:
      - status
    ExpenseDto:
      type: object
      properties:
        expenseId:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        type:
          type: string
        accountingCategoryCode:
          type: string
      required:
      - expenseId
      - name
      - type
    FixedPriceShippingDto:
      allOf:
      - $ref: '#/components/schemas/ShippingDto'
      - type: object
        properties:
          rate:
            type: number
          manualRate:
            type: number
          toAddress:
            oneOf:
            - $ref: '#/components/schemas/CustomerOrganisationAddressDto'
            - $ref: '#/components/schemas/OperatorAddressDto'
          name:
            type: string
      required:
      - operatorId
      - shippingMode
    ApiError:
      type: object
      additionalProperties: true
      description: Stable error contract. `error` is a SCREAMING_SNAKE code that clients match on; `message` is a human-readable sentence. Some errors add extra string fields (for example organisationId).
      properties:
        error:
          type: string
          example: ORDER_NOT_FOUND
        message:
          type: string
          example: Order not found
      required:
      - error
      - message
    CustomerAccountShippingDto:
      allOf:
      - $ref: '#/components/schemas/ShippingDto'
      - type: object
        properties:
          accountNumber:
            type: string
          name:
            type: string
          toAddress:
            oneOf:
            - $ref: '#/components/schemas/CustomerOrganisationAddressDto'
            - $ref: '#/components/schemas/OperatorAddressDto'
      required:
      - operatorId
      - shippingMode
    AssemblyRequisitionDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        assemblyId:
          type: string
          format: uuid
        assemblyName:
          type: string
        quantity:
          type: integer
        assemblyPricePaid:
          type: number
        totalPricePaid:
          type: number
        partCount:
          type: integer
          format: int32
        createdAt:
          type: string
          format: date-time
      required:
      - assemblyId
      - assemblyName
      - assemblyPricePaid
      - id
      - partCount
      - quantity
      - totalPricePaid
    ShipmentDocumentDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        contentType:
          type: string
        size:
          type: integer
          format: int64
        uploadedBy:
          $ref: '#/components/schemas/ShipmentUserDto'
        createdAt:
          type: string
          format: date-time
      required:
      - contentType
      - createdAt
      - id
      - name
      - size
      - uploadedBy
    OrderWorkOrderDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workOrderNumber:
          type: integer
          format: int64
        partName:
          type: string
        quantity:
          type: integer
        startDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        stages:
          type: array
          items:
            $ref: '#/components/schemas/OrderWorkOrderStageDto'
      required:
      - id
      - quantity
      - stages
      - startDate
    OrderWorkOrderStageDto:
      type: object
      properties:
        operationId:
          type: string
          format: uuid
        name:
          type: string
        quantity:
          type: integer
      required:
      - name
      - operationId
      - quantity
    OperatorAddressDto:
      allOf:
      - $ref: '#/components/schemas/AddressDto'
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    CustomerOrganisationAddressDto:
      allOf:
      - $ref: '#/components/schemas/AddressDto'
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    ProductionProgressDto:
      type: object
      properties:
        volume:
          type: number
        quantity:
          type: number
      required:
      - quantity
      - volume
    AddressDto:
      type: object
      discriminator:
        propertyName: addressType
        mapping:
          OPERATOR: '#/components/schemas/OperatorAddressDto'
          CUSTOMER_ORGANISATION: '#/components/schemas/CustomerOrganisationAddressDto'
      properties:
        addressId:
          type: integer
          format: int64
        isBillingAddress:
          type: boolean
        isShippingAddress:
          type: boolean
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        countryAlpha2Code:
          type: string
        countryAlpha3Code:
          type: string
        jurisdictionIsoCode:
          type: string
        zip:
          type: string
        name:
          type: string
        company:
          type: string
        phone:
          type: string
        email:
          type: string
        residential:
          type: boolean
        addressType:
          type: string
        isDeleted:
          type: boolean
        taxId:
          type: string
      required:
      - addressId
      - addressType
      - city
      - company
      - country
      - countryAlpha2Code
      - countryAlpha3Code
      - email
      - isBillingAddress
      - isDeleted
      - isShippingAddress
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    HourlyExpenseDto:
      allOf:
      - $ref: '#/components/schemas/ExpenseDto'
      - type: object
        properties:
          hours:
            type: number
          rate:
            type: number
      required:
      - expenseId
      - hours
      - name
      - rate
      - type
    OrderTaxDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        components:
          type: array
          items:
            $ref: '#/components/schemas/OrderTaxComponentDto'
        totalPrice:
          type: number
        localTotalPrice:
          type: number
        isTaxAppliedToShipping:
          type: boolean
        isTaxExempted:
          type: boolean
        accountingSystemTaxId:
          type: string
        taxNumber:
          type: string
      required:
      - components
      - id
      - isTaxAppliedToShipping
      - isTaxExempted
      - localTotalPrice
      - totalPrice
    DiscountDto:
      type: object
      properties:
        discountId:
          type: integer
          format: int64
        discountType:
          type: string
        code:
          type: string
        percentage:
          type: number
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        customerId:
          type: integer
          format: int64
        customerEmail:
          type: string
        customerPhoneNumber:
          type: string
      required:
      - discountId
      - discountType
      - endTime
      - percentage
      - startTime
    OrderDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        customerOrganisationId:
          type: integer
          format: int64
        customerOrganisationName:
          type: string
        threadId:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        updateDt:
          type: string
          format: date-time
        isArchived:
          type: boolean
        isVoided:
          type: boolean
        isPurchaseOrder:
          type: boolean
        isInProject:
          type: boolean
        isSilent:
          type: boolean
        hasWorkOrders:
          type: boolean
        workOrders:
          type: array
          items:
            $ref: '#/components/schemas/OrderWorkOrderDto'
        source:
          type: string
        billingAddressId:
          type: integer
          format: int64
        currency:
          type: string
        localCurrency:
          type: string
        paymentStatus:
          type: string
        awaitingStatus:
          type: string
        kanbanColumnId:
          type: string
        quoteNumber:
          type: string
        orderNumber:
          type: string
        state:
          type: string
          enum:
          - QUOTE
          - ORDER
          - DRAFT
        accountingSystemEstimateId:
          type: string
        accountingSystemEstimateNumber:
          type: string
        accountingSystemConfirmationId:
          type: string
        accountingSystemConfirmationNumber:
          type: string
        accountingSystemInvoiceId:
          type: string
        accountingSystemInvoiceNumber:
          type: string
        affiliate:
          type: string
        createdBy:
          $ref: '#/components/schemas/OrderUserDto'
        owner:
          $ref: '#/components/schemas/OrderUserDto'
        actorType:
          type: string
        paymentDueDate:
          type: string
          format: date-time
        productionProgress:
          $ref: '#/components/schemas/ProductionProgressDto'
        requisitionIds:
          type: array
          items:
            type: integer
            format: int64
        assemblyRequisitions:
          type: array
          items:
            $ref: '#/components/schemas/AssemblyRequisitionDto'
        expenses:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FixedExpenseDto'
            - $ref: '#/components/schemas/HourlyExpenseDto'
        shipping:
          oneOf:
          - $ref: '#/components/schemas/CarrierAccountShippingDto'
          - $ref: '#/components/schemas/CustomerAccountShippingDto'
          - $ref: '#/components/schemas/FixedPriceShippingDto'
          - $ref: '#/components/schemas/SelfCollectionShippingDto'
        shipments:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/CollectionShipmentDto'
            - $ref: '#/components/schemas/CourierShipmentDto'
        discount:
          $ref: '#/components/schemas/DiscountDto'
        tax:
          $ref: '#/components/schemas/OrderTaxDto'
        price:
          type: number
        localPrice:
          type: number
        topUpPrice:
          type: number
        purchaseOrderNumber:
          type: string
        customerAcceptedTime:
          type: string
          format: date-time
        operatorNote:
          type: string
        customReference:
          type: string
        bypassPurchasabilityChecks:
          type: boolean
        subscribedCustomerIds:
          type: array
          items:
            type: integer
            format: int64
          uniqueItems: true
        isEditable:
          type: boolean
        shipment:
          oneOf:
          - $ref: '#/components/schemas/CarrierAccountShippingDto'
          - $ref: '#/components/schemas/CustomerAccountShippingDto'
          - $ref: '#/components/schemas/FixedPriceShippingDto'
          - $ref: '#/components/schemas/SelfCollectionShippingDto'
          readOnly: true
      required:
      - assemblyRequisitions
      - awaitingStatus
      - bypassPurchasabilityChecks
      - createdAt
      - currency
      - expenses
      - hasWorkOrders
      - id
      - isArchived
      - isEditable
      - isInProject
      - isPurchaseOrder
      - isSilent
      - isVoided
      - localCurrency
      - paymentStatus
      - requisitionIds
      - shipments
      - source
      - state
      - subscribedCustomerIds
      - threadId
      - updateDt
      - workOrders
    OrderUserDto:
      type: object
      properties:
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
      required:
      - email
      - firstName
      - lastName
    OrderTaxComponentDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        shortName:
          type: string
        longName:
          type: string
        percentage:
          type: number
        amount:
          type: number
        localAmount:
          type: number
      required:
      - amount
      - id
      - localAmount
      - longName
      - percentage
      - shortName
    ShipmentAddressDto:
      type: object
      description: Address snapshot stored on the shipment. Do not send an address-book ID.
      properties:
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        zip:
          type: string
        name:
          type: string
        company:
          type: string
        phone:
          type: string
        email:
          type: string
        jurisdictionIsoCode:
          type: string
        residential:
          type: boolean
        taxId:
          type: string
      required:
      - city
      - country
      - email
      - name
      - phone
      - residential
      - street1
      - street2
      - zip
    ShipmentDto:
      type: object
      description: A concrete shipment on an order. Discriminated by `type`.
      discriminator:
        propertyName: type
        mapping:
          COURIER: '#/components/schemas/CourierShipmentDto'
          COLLECTION: '#/components/schemas/CollectionShipmentDto'
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - COURIER
          - COLLECTION
        status:
          type: string
          enum:
          - PREPARED
          - RELEASED
          - FULFILLED
        incoterm:
          type: string
          enum:
          - EXW
          - FCA
          - CPT
          - CIP
          - DAP
          - DPU
          - DDP
          - FAS
          - FOB
          - CFR
          - CIF
        fromAddress:
          $ref: '#/components/schemas/ShipmentAddressDto'
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/ParcelDto'
        preparedAt:
          type: string
          format: date-time
        preparedBy:
          $ref: '#/components/schemas/ShipmentUserDto'
        releasedAt:
          type: string
          format: date-time
        releasedBy:
          $ref: '#/components/schemas/ShipmentUserDto'
        fulfilledAt:
          type: string
          format: date-time
        fulfilledBy:
          $ref: '#/components/schemas/ShipmentUserDto'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentDocumentDto'
      required:
      - documents
      - fromAddress
      - parcels
      - type
    CourierShipmentDto:
      allOf:
      - $ref: '#/components/schemas/ShipmentDto'
      description: Courier shipment with a destination address and optional tracking
      required:
      - documents
      - fromAddress
      - parcels
      - toAddress
      - type
    ParcelDto:
      type: object
      description: Physical parcel on a shipment. Weights are grams; dimensions are millimetres; value is required.
      properties:
        id:
          type: string
          format: uuid
        grossWeightGrams:
          type: integer
          format: int32
        netWeightGrams:
          type: integer
          format: int32
        value:
          type: number
        width:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        length:
          type: integer
          format: int32
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/ParcelAllocationDto'
      required:
      - allocations
      - grossWeightGrams
      - height
      - length
      - netWeightGrams
      - value
      - width
    FixedExpenseDto:
      allOf:
      - $ref: '#/components/schemas/ExpenseDto'
      - type: object
        properties:
          quantity:
            type: number
          unitPrice:
            type: number
          localUnitPrice:
            type: number
          price:
            type: number
          costForOperator:
            type: number
      required:
      - costForOperator
      - expenseId
      - localUnitPrice
      - name
      - price
      - quantity
      - type
      - unitPrice
    CarrierAccountShippingDto:
      allOf:
      - $ref: '#/components/schemas/ShippingDto'
      - type: object
        properties:
          toAddress:
            oneOf:
            - $ref: '#/components/schemas/CustomerOrganisationAddressDto'
            - $ref: '#/components/schemas/OperatorAddressDto'
          fromAddress:
            oneOf:
            - $ref: '#/components/schemas/CustomerOrganisationAddressDto'
            - $ref: '#/components/schemas/OperatorAddressDto'
          carrierAccountProvider:
            type: string
          carrierAccountServiceType:
            type: string
          carrierAccountServiceName:
            type: string
          estimatedRate:
            type: number
          finalRatePaid:
            type: number
      required:
      - operatorId
      - shippingMode
    SelfCollectionShippingDto:
      allOf:
      - $ref: '#/components/schemas/ShippingDto'
      - type: object
        properties:
          contactName:
            type: string
          contactPhoneNumber:
            type: string
          rate:
            type: number
          name:
            type: string
      required:
      - operatorId
      - shippingMode
  securitySchemes:
    Phasio_API_Bearer_Token:
      type: http
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: JWT