POST /invoices/{invoice-id}/record_payment

Use this API to record an offline payment for the invoice. If the payment covers the full outstanding amount, the invoice status changes to Paid.

If no transaction amount is specified, the system will automatically use the invoice's due amount as the transaction amount.
If the payment exceeds the invoice's outstanding balance, the excess amount is added to the customer's Excess Payments balance. This balance can be applied to future invoices.

Implications of the operation {#ImplicationsOfTheOperation}

PAID Invoices
When the entire due amount is recorded as a payment, the invoice status is updated to Paid. However, if only a partial amount is recorded as an offline payment, the due amount is reduced, but the invoice status does not change.
PAYMENT_DUE, NOT_PAID & POSTED INVOICES
When the full due amount is recorded as payment, then the invoice status will change to Paid. If a partial amount is recorded as an offline payment, the due amount will be reduced while the invoice status remains unchanged.

FAQs {#Faqs}

What happens if I try to record a payment that exceeds the invoice amount? {#FaqTitle}

The system does not allow recording a payment amount greater than the invoice's outstanding balance.

Troubleshooting {#Troubleshooting}

Here are some commonly encountered errors when using this API, along with their resolutions

The idempotency key provided has already been used for a different request. Use a new idempotency key or ensure the endpoint matches the original request signature. 422 - unable_to_process_request
This API is idempotent. To ensure idempotent behavior, include a custom header named chargebee-idempotency-key with the POST request. If this key is not unique, the Chargebee API returns this error.
Steps to resolve:

Provide a unique idempotency key with the request options to perform an idempotent request.
Operation not supported as the invoice is in Paid, Pending, or Voided state. 409 - invalid_invoice_state
Payments can only be recorded if the invoice has an outstanding due amount. This API cannot be used for invoices with statuses of Paid, Voided, or Pending (Draft Invoice).
Steps to resolve:

For a paid invoice, remove the payment associated with the invoice before proceeding.
For a draft invoice, close it to generate the actual invoice and then record the payment against the invoice.
Operation not supported as the collectable amount for this invoice is zero. 409 - record_payment_not_supported
Payments can only be accepted if the invoice amount is greater than zero. Attempting to record a payment against an invoice with zero value results in this error.
Steps to resolve:

Use this API with an invoice that has an amount greater than zero.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`invoice-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`comment`	String	No	Remarks, if any, on the payment.
`transaction`	Object	No	Parameters for transaction
`transaction.id_at_gateway`	String	No	The id with which this transaction is referred in gateway.
`transaction.reference_number`	String	No	The reference number for this transaction. e.g check number in case of 'check' payments.
`transaction.custom_payment_method_id`	String	No	Identifier of the custom payment method of this transaction.
`transaction.amount`	Integer	No	The payment transaction amount. If not specified, this value will be the invoice's due amount.
`transaction.error_code`	String	No	Error code received from the payment gateway on failure.
`transaction.status`	String	No	The status of this transaction. * failure - Transaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure * success - The transaction is successful. * in_progress - Transaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method. * timeout - Transaction failed because of Gateway not accepting the connection. * voided - The transaction got voided or authorization expired at gateway. * late_failure - Indicates that a successful payment transaction has failed now due to a late failure notification from the payment gateway, typically caused by issues like insufficient funds or a closed bank account. * needs_attention - When connection with the Gateway gets terminated abruptly. For `needs_attention` status Chargebee automatically reconcile the transaction for few gateways, for rest of the gateways you have to use the Reconcile transaction API. You can use this API to update the `id_at_gateway` (Gateway Transaction ID) and `status` for a `needs_attention` transaction to be reconciled at par with the gateway. Learn more about `needs_attention` transaction status Possible values: `"success"` `"failure"` `"late_failure"`
`transaction.payment_method`	String	Yes	The payment method of this transaction * cash - Cash * alipay - Alipay * sofort - Sofort * direct_debit - Direct Debit * online_banking_poland - Online Banking Poland * netbanking_emandates - netbanking_emandates * klarna_pay_now - Klarna Pay Now * paypal_express_checkout - Paypal Express Checkout * automated_bank_transfer - Automated Bank Transfer * venmo - Venmo * bancontact - Bancontact * custom - Custom * ideal - IDEAL * check - Check * upi - upi * sepa_instant_transfer - Sepa Instant Transfer * sepa_credit - SEPA Credit * ach_credit - ACH Credit * faster_payments - Faster Payments * bank_transfer - Bank Transfer * chargeback - Only applicable for a transaction of type = `refund`. This value is set by Chargebee when an automated chargeback occurs. You can also set this explicitly when recording a refund. * unionpay - Unionpay * apple_pay - Apple Pay * dotpay - Dotpay * amazon_payments - Amazon Payments * wechat_pay - WeChat Pay * google_pay - Google Pay * card - Card * other - Payment Methods other than the above types * boleto - boleto * giropay - giropay * pay_to - PayTo Possible values: `"check"` `"other"` `"cash"` `"bank_transfer"` `"custom"`
`transaction.date`	Integer	No	Indicates when this transaction occurred.
`transaction.error_text`	String	No	Error message received from the payment gateway on failure.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.