---
title: "Create invoice payment"
method: POST
path: "/v1/platform/businesses/{business_id}/invoices/payments/"
tags: ["Invoice Payments"]
---

# Create invoice payment

`POST /v1/platform/businesses/{business_id}/invoices/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}/invoices/payments/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

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.

## Path parameters

- `business_id` string, uuid, required

## Request body

- InvoiceRecordPaymentRequestRequest: Request serializer for recording invoice payments
  - `customer_id` string, uuid, required: UUID of the customer making the payment (must exist in business)
  - `total_amount_cents` integer, required: Total payment amount in cents (e.g., 450000 for £4,500.00)
  - `allocations` PaymentAllocationItemRequest[]: List of invoice allocations - how this payment should be applied to invoices
    - `invoice_id` string, uuid, required: UUID of the invoice to allocate payment to
    - `amount_cents` integer, required: Amount in cents to allocate to this invoice (cannot exceed invoice outstanding balance)
  - `payment_date` string, date: Date when payment was received (ISO date format: YYYY-MM-DD)
  - `currency` string: Payment currency (must match business base currency, e.g., GBP, EUR)
  - `payment_method` 'bank_transfer' | 'credit_card' | 'debit_card' | 'ach' | 'check' | 'cash' | 'paypal' | 'stripe' | 'other': 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` string: Your internal payment reference or receipt number
  - `external_id` string: Your unique identifier for this payment (used for idempotency)
  - `note` string: Internal note or description for the payment
  - `notes` string: Legacy field for notes (use 'note' instead)
  - `metadata` object: Custom key-value pairs for additional payment context
  - `references` object: Payment references (bank_reference, end_to_end_id, payment_reference)
  - `processing_fee_cents` integer: Processing fee charged by payment processor (Stripe, PayPal, etc.) in cents
  - `payment_processor` string: Payment processor name (e.g., Stripe, PayPal)

## Response `201`

- PaymentCreateResponse: Response serializer for create invoice payment endpoint
  - `payment` PaymentDetail, required: Detailed payment information in response - all amounts in cents
    - `id` string, uuid, required: Unique payment identifier
    - `business_id` string, uuid, required: Business this payment belongs to
    - `customer_id` string, uuid, required: Customer who made the payment
    - `total_amount_cents` integer, required: Total payment amount in cents
    - `applied_amount_cents` integer, required: Amount applied to invoices in cents
    - `allocated_amount_cents` integer, required: Amount allocated to invoices in cents
    - `unapplied_amount_cents` integer, required: Unapplied amount remaining in cents
    - `remaining_amount_cents` integer, required: Remaining unallocated amount in cents
    - `currency` string, required: Payment currency (e.g., GBP, EUR, USD)
    - `status` string, required: Payment status (pending, processing, completed, failed, cancelled, refunded)
    - `payment_method` string, required: Payment method (bank_transfer, card, etc.)
    - `payment_reference` string: Your internal payment reference
    - `external_id` string: Your unique external identifier
    - `note` string: Internal note or description
    - `notes` string: Legacy notes field
    - `bank_reference` string: Bank transaction reference
    - `metadata` object: Custom key-value pairs
    - `idempotency_key` string: Idempotency key if provided
    - `created_at` string, date-time, required: Payment creation timestamp
    - `updated_at` string, date-time, required: Last update timestamp
    - `payouts` object[]: Payout information if applicable
    - `applied_invoices` PaymentInvoiceDetail[], required: Invoices this payment was applied to
      - `id` string, uuid, required: Invoice UUID
      - `invoice_number` string: Invoice number (e.g., INV-0042)
      - `applied_amount_cents` integer, required: Amount applied to this invoice in cents
      - `status` string, required: Invoice status after payment (sent, paid, overdue, etc.)
      - `outstanding_amount_cents` integer, required: Remaining outstanding balance on invoice in cents

## Other responses

- `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)