--- title: "Create bill payment with allocations" method: POST path: "/v1/platform/businesses/{business_id}/bills/payments/" tags: ["Bill Payments"] --- # Create bill payment with allocations `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) - URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/bills/payments/` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP basic - HTTP bearer - HTTP bearer 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" } ] } ``` ## Path parameters - `business_id` string, uuid, required ## Headers - `Idempotency-Key` string ## Request body - BillPaymentCreateRequest: 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. - `vendor_id` string, uuid, required: UUID of the vendor receiving the payment (must exist in business) - `amount_cents` integer, required: Total payment amount in cents (e.g., 450000 for £4,500.00) - `currency` string: 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_date` string, date: Date when payment was made (ISO date format: YYYY-MM-DD) - `payment_reference` string: Your internal payment reference or transaction ID - `check_number` string: Check number (required if payment_method is check) - `description` string: Description of the payment - `memo` string: Additional notes or memo for the payment - `processing_fee_cents` integer: Processing fee in cents (defaults to 0) - `external_id` string: Your unique identifier for idempotency (prevents duplicate payments) - `metadata` unknown - `allocations` BillPaymentAllocationCreateRequest[]: Array of bills to allocate this payment to - `bill_id` string, uuid, required: UUID of the bill to allocate payment to - `amount_cents` integer, required: Amount to allocate to this bill in cents (cannot exceed bill outstanding balance) - `description` string: Optional description for this allocation ## Response `200` - BillPaymentResponse: Detailed response serializer for bill payment with all related data. Returns payment details along with vendor info and allocations. All amounts in cents. - `id` string, uuid, required: Unique bill payment identifier - `business_id` string, uuid, required: Business this payment belongs to - `vendor_id` string, uuid, required: Vendor receiving the payment - `vendor_name` string, required: Vendor display name - `payment_reference` string, required: Payment reference or transaction ID - `external_id` string, required: Your external identifier for this payment - `processor_payment_id` string, required: Payment processor transaction ID (e.g., Stripe ID) - `check_number` string, required: Check number if payment method is check - `amount_cents` integer, required: Payment amount in cents - `currency` string, required: Payment currency (e.g., GBP, EUR, USD) - `processing_fee_cents` integer, required: Processing fee in cents - `net_amount_cents` integer, required: Net amount after fees in cents - `allocated_amount_cents` integer, required: Allocated amount in cents - `unallocated_amount_cents` integer, required: Unallocated amount in cents - `is_fully_allocated` boolean, required: Whether payment is fully allocated to bills - `payment_method` string, required: Payment method used (bank_transfer, check, wire, etc.) - `status` string, required: Payment status (pending, processing, completed, failed, cancelled) - `payment_date` string, date, required: Date payment was made - `value_date` string, date, required: Value date for accounting purposes - `submitted_at` string, date-time, required: When payment was submitted for processing - `completed_at` string, date-time, required: When payment processing completed - `failed_at` string, date-time, required: When payment failed (if applicable) - `description` string, required: Payment description - `memo` string, required: Additional notes or memo - `failure_reason` string, required: Reason for failure (if status=failed) - `metadata` unknown, required - `allocations` BillPaymentAllocation[], required: Bill allocations for this payment - `id` string, uuid, required: Unique allocation identifier - `bill_id` string, uuid, required: Bill this allocation applies to - `bill_number` string, required: Bill number - `vendor_bill_number` string, required: Vendor's bill number - `bill_status` string, required: Current bill status - `amount_cents` integer, required: Allocation amount in cents - `description` string: Allocation description - `allocation_date` string, date-time, required: When allocation was created - `created_at` string, date-time, required: Creation timestamp - `vendor_refund_allocations` BillPaymentVendorRefundAllocationSummary[], required: Vendor refund allocations linked to this payment - `vendor_refund_id` string, uuid, required - `reference_number` string - `amount_cents` integer, required - `allocated_at` string, date-time, required - `reconciled_bank_transactions` EntityReconciliationDetail[], required: Bank transactions this payment is reconciled to - `payment_type` string - `bank_transaction_id` string, uuid, required - `bank_transaction_date` string, date-time, required - `bank_transaction_amount_cents` integer, required - `bank_transaction_direction` string, required - `reconciled_amount_cents` integer, required - `reconciliation_link_id` string, uuid, required - `reconciled_at` string, date-time, required - `currency` string, required - `bank_account_name` string - `notes` string - `created_at` string, date-time, required: Payment creation timestamp - `updated_at` string, date-time, required: Last update timestamp ## Other responses - `201` - `400`: Validation errors in request data - `401`: Authentication required - missing or invalid API key - `403`: Permission denied - insufficient privileges - `404`: Resource not found - `409`: Conflict - resource already exists or invalid state transition - `422`: Unprocessable entity - business logic validation failed - `500`: Internal server error --- [API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)