THthredfi
Bill Payments

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"
        }
      ]
    }
    ```
post/v1/platform/businesses/{business_id}/bills/payments/

Request

  • Base URL
    https://docs.thredfi.com (the document declares no server; this is the origin it was published from)
  • Auth
    • HTTP bearer
    • or HTTP bearer
    • or HTTP basic
    • or HTTP bearer
    • or HTTP bearer

Path parameters

business_idstring uuid required

Business UUID

Headers

Idempotency-Keystring

Unique key for idempotent request processing

Request body

vendor_idstring uuid required

UUID of the vendor receiving the payment (must exist in business)

amount_centsinteger required

Total payment amount in cents (e.g., 450000 for £4,500.00)

currencystring

Payment currency (must match business base currency, defaults to GBP)

payment_method'bank_transfer' | 'ach' | 'wire' | 'check' | 'credit_card' | 'cash' | 'other'

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_datestring date

Date when payment was made (ISO date format: YYYY-MM-DD)

payment_referencestring

Your internal payment reference or transaction ID

check_numberstring

Check number (required if payment_method is check)

descriptionstring

Description of the payment

memostring

Additional notes or memo for the payment

processing_fee_centsinteger

Processing fee in cents (defaults to 0)

external_idstring

Your unique identifier for idempotency (prevents duplicate payments)

metadataunknown

Response

idstring uuid required

Unique bill payment identifier

business_idstring uuid required

Business this payment belongs to

vendor_idstring uuid required

Vendor receiving the payment

vendor_namestring required

Vendor display name

payment_referencestring required

Payment reference or transaction ID

external_idstring required

Your external identifier for this payment

processor_payment_idstring required

Payment processor transaction ID (e.g., Stripe ID)

check_numberstring required

Check number if payment method is check

amount_centsinteger required

Payment amount in cents

currencystring required

Payment currency (e.g., GBP, EUR, USD)

processing_fee_centsinteger required

Processing fee in cents

net_amount_centsinteger required

Net amount after fees in cents

allocated_amount_centsinteger required

Allocated amount in cents

unallocated_amount_centsinteger required

Unallocated amount in cents

is_fully_allocatedboolean required

Whether payment is fully allocated to bills

payment_methodstring required

Payment method used (bank_transfer, check, wire, etc.)

statusstring required

Payment status (pending, processing, completed, failed, cancelled)

payment_datestring date required

Date payment was made

value_datestring date required

Value date for accounting purposes

submitted_atstring date-time required

When payment was submitted for processing

completed_atstring date-time required

When payment processing completed

failed_atstring date-time required

When payment failed (if applicable)

descriptionstring required

Payment description

memostring required

Additional notes or memo

failure_reasonstring required

Reason for failure (if status=failed)

metadataunknown required
created_atstring date-time required

Payment creation timestamp

updated_atstring date-time required

Last update timestamp

Changes

No recorded changes to this operation across all 1 revision of this API.