Skip to main content
POST
/
v1
/
platform
/
businesses
/
{business_id}
/
invoices
/
payments
Create invoice payment
curl --request POST \
  --url https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/invoices/payments/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "total_amount_cents": 2,
  "allocations": [
    {
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount_cents": 2
    }
  ],
  "payment_date": "2023-12-25",
  "currency": "<string>",
  "payment_method": "bank_transfer",
  "payment_reference": "<string>",
  "external_id": "<string>",
  "note": "<string>",
  "notes": "<string>",
  "metadata": {},
  "references": {},
  "processing_fee_cents": 0,
  "payment_processor": "<string>"
}
'
{
  "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
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Partner-level JWT token (unscoped). Token payload includes partner_id. Business access is validated via partner ownership. Format: Bearer <your-jwt-token>

Use this for: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses.

Path Parameters

​
business_id
string<uuid>
required

Business UUID provided by Thred (unique identifier for the business)

Body

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)

Required range: x >= 1
​
allocations
object[]

List of invoice allocations - how this payment should be applied to invoices

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

Required string length: 1 - 3
​
payment_method
enum<string>

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
Available options:
bank_transfer,
credit_card,
debit_card,
ach,
check,
cash,
paypal,
stripe,
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
default:0

Processing fee charged by payment processor (Stripe, PayPal, etc.) in cents

Required range: x >= 0
​
payment_processor
string

Payment processor name (e.g., Stripe, PayPal)

Maximum string length: 100

Response

Response serializer for create invoice payment endpoint

​
payment
object
required

Detailed payment information in response - all amounts in cents