createPayment
createPaymentRecord a successful manual or offline payment or tax-withheld amount. Link the payment to invoices to reduce the amount due and mark invoices as paid.
Instructions
Record a successful manual/offline payment or tax-withheld amount, equivalent to the frontend Add Payment flow. Link to invoices via payment_parts array. Use type='payment' with payment_method='bank_transfer', 'check', 'cash', or 'card'. Use type='tax_withheld' without payment_method. Always use status='success'. Do not use status='created' for manually recorded payments; created payments are unrealized and will not reduce invoice amount_due or mark invoices paid. The backend assigns the payment timestamp when the payment is recorded. Refunds, authorizations, reversals, payment links, and gateway charge attempts are outside this tool's scope.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | No | UUID of the customer making the payment. | |
| amount | Yes | Total payment amount in the smallest currency unit (e.g. cents). | |
| currency_code | Yes | Three-letter ISO 4217 currency code (e.g. USD). | |
| payment_parts | No | Array of invoice allocations. Each element: {invoice_id: 'UUID', amount: 10000}. Links the payment to one or more invoices. | |
| payment_method | No | Manual payment method. Required when type='payment'; omit for type='tax_withheld'. Supported values match the frontend Add Payment flow. | |
| type | No | Frontend Add Payment type. Use 'payment' for a manual/offline payment, or 'tax_withheld' for a tax withheld amount. Refunds, payment reversals, and authorizations are outside this tool's scope. | payment |
| status | No | Payment status for this recorded payment. Use 'success' for manually recorded/offline payments so linked invoices are marked paid when payment_parts cover the amount due. | success |
| external_id | No | External reference ID for this payment. | |
| __userContext | No | Internal user context for multi-tenant authentication and approval workflow |