> ## 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 invoice payment > Record a payment for one or more customer invoices. The payment is recorded and invoices are updated, ready to be matched during reconciliation later. Supports idempotency via Idempotency-Key header. ## OpenAPI ````yaml POST /v1/platform/businesses/{business_id}/invoices/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}/invoices/payments/: post: tags: - Invoice Payments summary: Create invoice payment description: >- Record a payment for one or more customer invoices. The payment is recorded and invoices are updated, ready to be matched during reconciliation later. Supports idempotency via Idempotency-Key header. operationId: create_invoice_payment parameters: - in: path name: business_id schema: type: string format: uuid description: Business UUID provided by Thred (unique identifier for the business) required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/InvoiceRecordPaymentRequestRequest' examples: SimpleSingleInvoicePayment(UKPub): value: customer_id: 4d90c3cc-1e55-5c61-9999-9ee36847163b total_amount_cents: 450000 currency: GBP payment_date: '2024-03-20' payment_method: bank_transfer payment_reference: PAY-2024-0042 references: bank_reference: FPS-20240320-123456 note: Payment for INV-0042 - monthly beer supply allocations: - invoice_id: 5e90c3cc-2f66-6d72-aaaa-aff47958274c amount_cents: 450000 summary: Simple Single Invoice Payment (UK Pub) Multi-InvoicePaymentWithPartialAllocation: value: customer_id: 4d90c3cc-1e55-5c61-9999-9ee36847163b total_amount_cents: 600000 currency: GBP payment_date: '2024-03-22' payment_method: card payment_reference: PAY-2024-0043 references: payment_reference: ch_3P1234567890AbCd external_id: ext-payment-001 note: Payment for multiple outstanding invoices metadata: payment_source: online_portal customer_ip: 192.0.2.1 allocations: - invoice_id: 5e90c3cc-2f66-6d72-aaaa-aff47958274c amount_cents: 450000 - invoice_id: 6f90c3cc-3f77-7e83-bbbb-bff58069385d amount_cents: 150000 summary: Multi-Invoice Payment with Partial Allocation application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/InvoiceRecordPaymentRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/InvoiceRecordPaymentRequestRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PaymentCreateResponse' examples: CreatePaymentResponse(UKPub): value: payment: id: 7a80c3cc-4g88-8f94-cccc-cgg69180496e business_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a customer_id: 4d90c3cc-1e55-5c61-9999-9ee36847163b total_amount_cents: 450000 applied_amount_cents: 450000 allocated_amount_cents: 450000 unapplied_amount_cents: 0 remaining_amount_cents: 0 currency: GBP status: completed payment_method: bank_transfer payment_reference: PAY-2024-0042 external_id: ext-payment-001 note: Payment for INV-0042 - monthly beer supply bank_reference: FPS-20240320-123456 metadata: {} idempotency_key: null created_at: '2024-03-20T09:30:00Z' updated_at: '2024-03-20T09:30:00Z' applied_invoices: - id: 5e90c3cc-2f66-6d72-aaaa-aff47958274c invoice_number: INV-0042 applied_amount_cents: 450000 status: paid outstanding_amount_cents: 0 summary: Create Payment Response (UK Pub) 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: - PartnerJWT: [] - BusinessScopedJWT: [] - BasicAuth: [] - BearerUnscoped: [] - BearerBusinessScoped: [] components: schemas: InvoiceRecordPaymentRequestRequest: type: object description: Request serializer for recording invoice payments properties: customer_id: type: string format: uuid description: UUID of the customer making the payment (must exist in business) total_amount_cents: type: integer minimum: 1 description: Total payment amount in cents (e.g., 450000 for £4,500.00) allocations: type: array items: $ref: '#/components/schemas/PaymentAllocationItemRequest' description: >- List of invoice allocations - how this payment should be applied to invoices payment_date: type: string format: date description: 'Date when payment was received (ISO date format: YYYY-MM-DD)' currency: type: string minLength: 1 description: Payment currency (must match business base currency, e.g., GBP, EUR) maxLength: 3 payment_method: enum: - bank_transfer - credit_card - debit_card - ach - check - cash - paypal - stripe - other type: string x-spec-enum-id: 1a9252035ec0bc4a description: >- Method of payment (e.g., bank_transfer, card, cash, cheque, direct_debit) * `bank_transfer` - bank_transfer * `credit_card` - credit_card * `debit_card` - debit_card * `ach` - ach * `check` - check * `cash` - cash * `paypal` - paypal * `stripe` - stripe * `other` - other payment_reference: type: string description: Your internal payment reference or receipt number external_id: type: string description: Your unique identifier for this payment (used for idempotency) note: type: string description: Internal note or description for the payment notes: type: string description: Legacy field for notes (use 'note' instead) metadata: type: object additionalProperties: {} description: Custom key-value pairs for additional payment context references: type: object additionalProperties: type: string description: >- Payment references (bank_reference, end_to_end_id, payment_reference) processing_fee_cents: type: integer minimum: 0 default: 0 description: >- Processing fee charged by payment processor (Stripe, PayPal, etc.) in cents payment_processor: type: string description: Payment processor name (e.g., Stripe, PayPal) maxLength: 100 required: - customer_id - total_amount_cents PaymentCreateResponse: type: object description: Response serializer for create invoice payment endpoint properties: payment: $ref: '#/components/schemas/PaymentDetail' required: - payment 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 PaymentAllocationItemRequest: type: object description: Nested serializer for payment allocation items properties: invoice_id: type: string format: uuid description: UUID of the invoice to allocate payment to amount_cents: type: integer minimum: 1 description: >- Amount in cents to allocate to this invoice (cannot exceed invoice outstanding balance) required: - amount_cents - invoice_id PaymentDetail: type: object description: Detailed payment information in response - all amounts in cents properties: id: type: string format: uuid description: Unique payment identifier business_id: type: string format: uuid description: Business this payment belongs to customer_id: type: string format: uuid description: Customer who made the payment total_amount_cents: type: integer description: Total payment amount in cents applied_amount_cents: type: integer description: Amount applied to invoices in cents allocated_amount_cents: type: integer description: Amount allocated to invoices in cents unapplied_amount_cents: type: integer description: Unapplied amount remaining in cents remaining_amount_cents: type: integer description: Remaining unallocated amount in cents currency: type: string description: Payment currency (e.g., GBP, EUR, USD) status: type: string description: >- Payment status (pending, processing, completed, failed, cancelled, refunded) payment_method: type: string description: Payment method (bank_transfer, card, etc.) payment_reference: type: string description: Your internal payment reference external_id: type: string description: Your unique external identifier note: type: string description: Internal note or description notes: type: string description: Legacy notes field bank_reference: type: string description: Bank transaction reference metadata: type: object additionalProperties: {} description: Custom key-value pairs idempotency_key: type: string description: Idempotency key if provided created_at: type: string format: date-time description: Payment creation timestamp updated_at: type: string format: date-time description: Last update timestamp payouts: type: array items: type: object additionalProperties: {} description: Payout information if applicable applied_invoices: type: array items: $ref: '#/components/schemas/PaymentInvoiceDetail' description: Invoices this payment was applied to required: - allocated_amount_cents - applied_amount_cents - applied_invoices - business_id - created_at - currency - customer_id - id - payment_method - remaining_amount_cents - status - total_amount_cents - unapplied_amount_cents - updated_at PaymentInvoiceDetail: type: object description: Invoice details in payment response - all amounts in cents properties: id: type: string format: uuid description: Invoice UUID invoice_number: type: string description: Invoice number (e.g., INV-0042) applied_amount_cents: type: integer description: Amount applied to this invoice in cents status: type: string description: Invoice status after payment (sent, paid, overdue, etc.) outstanding_amount_cents: type: integer description: Remaining outstanding balance on invoice in cents required: - applied_amount_cents - id - outstanding_amount_cents - status securitySchemes: 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 ` **Use this for**: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses. BusinessScopedJWT: type: http scheme: bearer bearerFormat: JWT description: >- Business-scoped JWT token. Token payload includes `business_id` to automatically scope requests. Format: `Bearer ` **Use this for**: Business-specific operations where the business context is embedded in the token. 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. ````