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-Keyheader
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:
{
"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"
}
]
}
Authorizations
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.
Headers
Unique key for idempotent request processing
Path Parameters
Business UUID
Body
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.
UUID of the vendor receiving the payment (must exist in business)
Total payment amount in cents (e.g., 450000 for £4,500.00)
x >= 1Payment currency (must match business base currency, defaults to GBP)
1 - 3Payment method: bank_transfer, ach, wire, check, credit_card, cash, or other
bank_transfer- bank_transferach- achwire- wirecheck- checkcredit_card- credit_cardcash- cashother- other
bank_transfer, ach, wire, check, credit_card, cash, other Date when payment was made (ISO date format: YYYY-MM-DD)
Your internal payment reference or transaction ID
100Check number (required if payment_method is check)
50Description of the payment
Additional notes or memo for the payment
Processing fee in cents (defaults to 0)
x >= 0Your unique identifier for idempotency (prevents duplicate payments)
255Custom key-value pairs for additional payment context
Array of bills to allocate this payment to
Response
Detailed response serializer for bill payment with all related data.
Returns payment details along with vendor info and allocations. All amounts in cents.
Unique bill payment identifier
Business this payment belongs to
Vendor receiving the payment
Vendor display name
Payment reference or transaction ID
Your external identifier for this payment
Payment processor transaction ID (e.g., Stripe ID)
Check number if payment method is check
Payment amount in cents
Payment currency (e.g., GBP, EUR, USD)
Processing fee in cents
Net amount after fees in cents
Allocated amount in cents
Unallocated amount in cents
Whether payment is fully allocated to bills
Payment method used (bank_transfer, check, wire, etc.)
Payment status (pending, processing, completed, failed, cancelled)
Date payment was made
Value date for accounting purposes
When payment was submitted for processing
When payment processing completed
When payment failed (if applicable)
Payment description
Additional notes or memo
Reason for failure (if status=failed)
Custom key-value pairs
Bill allocations for this payment
Vendor refund allocations linked to this payment
Bank transactions this payment is reconciled to
Payment creation timestamp
Last update timestamp