> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thredfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create bill payment with allocations

> 
        Create a bill payment with embedded allocations in a single atomic operation.

        This endpoint follows the same pattern as invoice payments and vendor refund payments,
        where allocations are embedded in the payment creation request.

        **Key Features:**
        - Atomic operation - all or nothing
        - Comprehensive validation
        - Support for multiple bill allocations
        - Idempotency support via `Idempotency-Key` header

        **Idempotency:**
        Include an `Idempotency-Key` header to ensure the same request isn't processed twice.
        If the same key is used again, the original response will be returned.

        **Example Request:**
        ```json
        {
          "vendor_id": "uuid",
          "amount_cents": 100000,
          "payment_method": "bank_transfer",
          "payment_date": "2025-01-15",
          "allocations": [
            {
              "bill_id": "uuid",
              "amount_cents": 60000,
              "description": "Partial payment for Bill #123"
            },
            {
              "bill_id": "uuid",
              "amount_cents": 40000,
              "description": "Full payment for Bill #124"
            }
          ]
        }
        ```
        



## OpenAPI

````yaml POST /v1/platform/businesses/{business_id}/bills/payments/
openapi: 3.0.3
info:
  title: Thredfi Accounting Platform API
  version: 1.0.0
  description: >-
    Comprehensive API for accounting, invoice management, open banking, and
    intelligence services.
servers: []
security: []
paths:
  /v1/platform/businesses/{business_id}/bills/payments/:
    post:
      tags:
        - Bill Payments
      summary: Create bill payment with allocations
      description: |2-

                Create a bill payment with embedded allocations in a single atomic operation.

                This endpoint follows the same pattern as invoice payments and vendor refund payments,
                where allocations are embedded in the payment creation request.

                **Key Features:**
                - Atomic operation - all or nothing
                - Comprehensive validation
                - Support for multiple bill allocations
                - Idempotency support via `Idempotency-Key` header

                **Idempotency:**
                Include an `Idempotency-Key` header to ensure the same request isn't processed twice.
                If the same key is used again, the original response will be returned.

                **Example Request:**
                ```json
                {
                  "vendor_id": "uuid",
                  "amount_cents": 100000,
                  "payment_method": "bank_transfer",
                  "payment_date": "2025-01-15",
                  "allocations": [
                    {
                      "bill_id": "uuid",
                      "amount_cents": 60000,
                      "description": "Partial payment for Bill #123"
                    },
                    {
                      "bill_id": "uuid",
                      "amount_cents": 40000,
                      "description": "Full payment for Bill #124"
                    }
                  ]
                }
                ```
                
      operationId: create_bill_payment_allocation
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
          description: Unique key for idempotent request processing
        - in: path
          name: business_id
          schema:
            type: string
            format: uuid
          description: Business UUID
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillPaymentCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BillPaymentCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BillPaymentCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPaymentResponse'
          description: ''
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPaymentResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: Validation errors in request data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication required - missing or invalid API key
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Permission denied - insufficient privileges
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict - resource already exists or invalid state transition
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable entity - business logic validation failed
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
        - BusinessScopedJWT: []
        - PartnerJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    BillPaymentCreateRequest:
      type: object
      description: >-
        Serializer for creating bill payments with allocations.


        This follows the same pattern as vendor refund payments and invoice
        payments,

        where allocations are embedded in the payment creation request.
      properties:
        vendor_id:
          type: string
          format: uuid
          description: UUID of the vendor receiving the payment (must exist in business)
        amount_cents:
          type: integer
          minimum: 1
          description: Total payment amount in cents (e.g., 450000 for £4,500.00)
        currency:
          type: string
          minLength: 1
          default: GBP
          description: >-
            Payment currency (must match business base currency, defaults to
            GBP)
          maxLength: 3
        payment_method:
          enum:
            - bank_transfer
            - ach
            - wire
            - check
            - credit_card
            - cash
            - other
          type: string
          x-spec-enum-id: e41885a675157233
          default: bank_transfer
          description: >-
            Payment method: bank_transfer, ach, wire, check, credit_card, cash,
            or other


            * `bank_transfer` - bank_transfer

            * `ach` - ach

            * `wire` - wire

            * `check` - check

            * `credit_card` - credit_card

            * `cash` - cash

            * `other` - other
        payment_date:
          type: string
          format: date
          description: 'Date when payment was made (ISO date format: YYYY-MM-DD)'
        payment_reference:
          type: string
          description: Your internal payment reference or transaction ID
          maxLength: 100
        check_number:
          type: string
          description: Check number (required if payment_method is check)
          maxLength: 50
        description:
          type: string
          description: Description of the payment
        memo:
          type: string
          description: Additional notes or memo for the payment
        processing_fee_cents:
          type: integer
          minimum: 0
          default: 0
          description: Processing fee in cents (defaults to 0)
        external_id:
          type: string
          description: Your unique identifier for idempotency (prevents duplicate payments)
          maxLength: 255
        metadata:
          description: Custom key-value pairs for additional payment context
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentAllocationCreateRequest'
          description: Array of bills to allocate this payment to
      required:
        - amount_cents
        - vendor_id
    BillPaymentResponse:
      type: object
      description: |-
        Detailed response serializer for bill payment with all related data.

        Returns payment details along with vendor info and allocations.
        All amounts in cents.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique bill payment identifier
        business_id:
          type: string
          format: uuid
          readOnly: true
          description: Business this payment belongs to
        vendor_id:
          type: string
          format: uuid
          readOnly: true
          description: Vendor receiving the payment
        vendor_name:
          type: string
          readOnly: true
          description: Vendor display name
        payment_reference:
          type: string
          readOnly: true
          description: Payment reference or transaction ID
        external_id:
          type: string
          readOnly: true
          description: Your external identifier for this payment
        processor_payment_id:
          type: string
          readOnly: true
          description: Payment processor transaction ID (e.g., Stripe ID)
        check_number:
          type: string
          readOnly: true
          description: Check number if payment method is check
        amount_cents:
          type: integer
          readOnly: true
          description: Payment amount in cents
        currency:
          type: string
          readOnly: true
          description: Payment currency (e.g., GBP, EUR, USD)
        processing_fee_cents:
          type: integer
          readOnly: true
          description: Processing fee in cents
        net_amount_cents:
          type: integer
          readOnly: true
          description: Net amount after fees in cents
        allocated_amount_cents:
          type: integer
          readOnly: true
          description: Allocated amount in cents
        unallocated_amount_cents:
          type: integer
          readOnly: true
          description: Unallocated amount in cents
        is_fully_allocated:
          type: boolean
          readOnly: true
          description: Whether payment is fully allocated to bills
        payment_method:
          type: string
          readOnly: true
          description: Payment method used (bank_transfer, check, wire, etc.)
        status:
          type: string
          readOnly: true
          description: Payment status (pending, processing, completed, failed, cancelled)
        payment_date:
          type: string
          format: date
          readOnly: true
          description: Date payment was made
        value_date:
          type: string
          format: date
          readOnly: true
          description: Value date for accounting purposes
        submitted_at:
          type: string
          format: date-time
          readOnly: true
          description: When payment was submitted for processing
        completed_at:
          type: string
          format: date-time
          readOnly: true
          description: When payment processing completed
        failed_at:
          type: string
          format: date-time
          readOnly: true
          description: When payment failed (if applicable)
        description:
          type: string
          readOnly: true
          description: Payment description
        memo:
          type: string
          readOnly: true
          description: Additional notes or memo
        failure_reason:
          type: string
          readOnly: true
          description: Reason for failure (if status=failed)
        metadata:
          readOnly: true
          description: Custom key-value pairs
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentAllocation'
          readOnly: true
          description: Bill allocations for this payment
        vendor_refund_allocations:
          type: array
          items:
            $ref: '#/components/schemas/BillPaymentVendorRefundAllocationSummary'
          readOnly: true
          description: Vendor refund allocations linked to this payment
        reconciled_bank_transactions:
          type: array
          items:
            $ref: '#/components/schemas/EntityReconciliationDetail'
          readOnly: true
          description: Bank transactions this payment is reconciled to
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Payment creation timestamp
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Last update timestamp
      required:
        - allocated_amount_cents
        - allocations
        - amount_cents
        - business_id
        - check_number
        - completed_at
        - created_at
        - currency
        - description
        - external_id
        - failed_at
        - failure_reason
        - id
        - is_fully_allocated
        - memo
        - metadata
        - net_amount_cents
        - payment_date
        - payment_method
        - payment_reference
        - processing_fee_cents
        - processor_payment_id
        - reconciled_bank_transactions
        - status
        - submitted_at
        - unallocated_amount_cents
        - updated_at
        - value_date
        - vendor_id
        - vendor_name
        - vendor_refund_allocations
    ValidationErrorResponse:
      type: object
      description: Validation error response with field-specific errors
      properties:
        error_code:
          type: string
          description: Error code (e.g., 'validation_error')
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Contains field_errors and additional context
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - detail
        - error_code
        - message
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error_code:
          type: string
          description: Error code for programmatic handling
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Additional error details including field_errors and debug info
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - error_code
        - message
    BillPaymentAllocationCreateRequest:
      type: object
      description: Serializer for creating bill payment allocations
      properties:
        bill_id:
          type: string
          format: uuid
          description: UUID of the bill to allocate payment to
        amount_cents:
          type: integer
          minimum: 1
          description: >-
            Amount to allocate to this bill in cents (cannot exceed bill
            outstanding balance)
        description:
          type: string
          description: Optional description for this allocation
          maxLength: 500
      required:
        - amount_cents
        - bill_id
    BillPaymentAllocation:
      type: object
      description: Serializer for bill payment allocation details. All amounts in cents.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique allocation identifier
        bill_id:
          type: string
          format: uuid
          description: Bill this allocation applies to
        bill_number:
          type: string
          readOnly: true
          description: Bill number
        vendor_bill_number:
          type: string
          readOnly: true
          description: Vendor's bill number
        bill_status:
          type: string
          description: Current bill status
          readOnly: true
        amount_cents:
          type: integer
          description: Allocation amount in cents
        description:
          type: string
          description: Allocation description
        allocation_date:
          type: string
          format: date-time
          readOnly: true
          description: When allocation was created
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Creation timestamp
      required:
        - allocation_date
        - amount_cents
        - bill_id
        - bill_number
        - bill_status
        - created_at
        - id
        - vendor_bill_number
    BillPaymentVendorRefundAllocationSummary:
      type: object
      description: >-
        Vendor refund allocation summary for bill payment detail view - shows
        vendor refunds that used this payment.
      properties:
        vendor_refund_id:
          type: string
          format: uuid
        reference_number:
          type: string
        amount_cents:
          type: integer
        allocated_at:
          type: string
          format: date-time
      required:
        - allocated_at
        - amount_cents
        - vendor_refund_id
    EntityReconciliationDetail:
      type: object
      description: >-
        Which bank transaction an entity (invoice/bill payment) is reconciled
        to.
      properties:
        payment_type:
          type: string
        bank_transaction_id:
          type: string
          format: uuid
        bank_transaction_date:
          type: string
          format: date-time
        bank_transaction_amount_cents:
          type: integer
        bank_transaction_direction:
          type: string
        reconciled_amount_cents:
          type: integer
        reconciliation_link_id:
          type: string
          format: uuid
        reconciled_at:
          type: string
          format: date-time
        currency:
          type: string
        bank_account_name:
          type: string
        notes:
          type: string
      required:
        - bank_transaction_amount_cents
        - bank_transaction_date
        - bank_transaction_direction
        - bank_transaction_id
        - currency
        - reconciled_amount_cents
        - reconciled_at
        - reconciliation_link_id
  securitySchemes:
    BusinessScopedJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT token. Token payload includes `business_id` to
        automatically scope requests. Format: `Bearer <your-jwt-token>`


        **Use this for**: Business-specific operations where the business
        context is embedded in the token.
    PartnerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner-level JWT token (unscoped). Token payload includes `partner_id`.
        Business access is validated via partner ownership. Format: `Bearer
        <your-jwt-token>`


        **Use this for**: Multi-business operations where the business_id is
        specified in the URL and partner has access to multiple businesses.
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key
        as username:password. Example: Authorization: Basic
        base64(partner_uuid:api_key)
    BearerUnscoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner (unscoped) JWT Bearer token. Obtain via POST
        /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use
        header: Authorization: Bearer {access_token}
    BearerBusinessScoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT Bearer token. Obtain via POST
        /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token.
        Only valid for endpoints whose URL contains that business_id.

````