--- title: "Create payment" method: POST path: "/api/v1/payments" tags: ["payments"] --- # Create payment `POST /api/v1/payments` ## Request - Base URL: `https://demo.invoiceninja.com` - URL: `https://demo.invoiceninja.com/api/v1/payments` - Auth: none declared. Required headers: `X-API-TOKEN`, `X-Requested-With` - TypeScript: (a function with typed inputs; its response is checked against the schema) Adds an Payment to the system ## Query parameters - `include` string - `email_receipt` boolean ## Headers - `X-API-TOKEN` string, required - `X-Requested-With` string, required ## Request body - PaymentRequest - `client_id` string: The client hashed id - `client_contact_id` string: The client contact hashed id - `user_id` string: The user hashed id - `type_id` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '27' | '28' | '29' | '30' | '31' | '32' | '33': The payment type used to complete this payment - `date` string, date: The Payment date - `transaction_reference` string: The transaction reference as defined by the payment gateway - `assigned_user_id` string: The assigned user hashed id - `private_notes` string: The private notes of the payment - `amount` number: The amount of this payment - `invoices` InvoicePaymentable[] - `invoice_id` string: ______ - `amount` string: ______ - `credits` CreditPaymentable[] - `credit_id` string: The credit hashed id - `amount` string: The credit amount - `number` string: The payment number - is a unique alpha numeric number per payment per company ## Response `200` Returns the saved Payment object - Payment - `id` string: The payment hashed id - `client_id` string: The client hashed id - `invitation_id` string: The invitation hashed id - `client_contact_id` string: The client contact hashed id - `user_id` string: The user hashed id - `type_id` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '27' | '28' | '29' | '30' | '31' | '32' | '33': The payment type used to complete this payment - `date` string: The Payment date - `transaction_reference` string: The transaction reference as defined by the payment gateway - `assigned_user_id` string: The assigned user hashed id - `private_notes` string: The private notes of the payment - `is_manual` boolean: Flags whether the payment was made manually or processed via a gateway - `is_deleted` boolean: Defines if the payment has been deleted - `amount` number: The amount of this payment - `refunded` number: The refunded amount of this payment - `updated_at` number: Timestamp - `archived_at` number: Timestamp - `company_gateway_id` string: The company gateway id - `paymentables` Paymentable - `id` string: The paymentable hashed id - `invoice_id` string: The invoice hashed id - `credit_id` string: The credit hashed id - `refunded` number, float: The amount that has been refunded for this payment - `amount` number, float: The amount that has been applied to the payment - `updated_at` number: Timestamp - `created_at` number: Timestamp - `invoices` InvoicePaymentable[] - `invoice_id` string: ______ - `amount` string: ______ - `credits` CreditPaymentable[] - `credit_id` string: The credit hashed id - `amount` string: The credit amount - `number` string: The payment number - is a unique alpha numeric number per payment per company - `category_id` string: The unique identifier of the payment category - `custom_value1` string: Custom field for storing additional information - `custom_value2` string: Custom field for storing additional information - `custom_value3` string: Custom field for storing additional information - `custom_value4` string: Custom field for storing additional information - `exchange_currency_id` string: The unique identifier of the exchange currency - `exchange_rate` number, float: The exchange rate used for currency conversion - `idempotency_key` string: Unique key to ensure idempotent payment processing ## Other responses - `401`: Authentication error - `403`: Authorization error - `422`: Validation error - `429`: Rate Limit Exceeded - `5XX`: Server error - `default`: Unexpected Error ## Changes > 110 revisions in range; 1 not diffed. - **2026-04-20** `69a36036d334`: 2 info - the response optional property `id` became read-only for the status `200` - the response optional property `paymentables/id` became read-only for the status `200` - **2026-03-12** `6e30c707b405`: 1 breaking - the `date` request property format changed from no format to `date` - **2025-11-22** `00ad5cc89fad`: 8 info - added the optional property `category_id` to the response with the `200` status - added the optional property `custom_value1` to the response with the `200` status - added the optional property `custom_value2` to the response with the `200` status - added the optional property `custom_value3` to the response with the `200` status - …4 more - **2025-03-23** `889dafb290e3`: 3 breaking, 42 warning, 33 info - request property `type_id` was restricted to a list of enum values - the `type_id` request property type changed from `integer` to `string` - the `type_id` response's property type changed from `integer` to `string` for status `200` - removed the request property `archived_at` - …74 more - **2025-03-23** `bced1c13f44d`: 2 breaking - the `type_id` request property type changed from `string` to `integer` - the `type_id` response's property type changed from `string` to `integer` for status `200` [Operation history](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/changes/api/v1/payments/post.md) --- [API](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference.md) - [All operations](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/revisions/bcda1f823746?raw)