POST /invoices/{invoice-id}/record_payment

Records an offline payment for an invoice.

Use this API to record payments that you receive outside Chargebee, such as bank transfers or checks, so that you can reconcile them against invoices.

Prerequisites & Constraints

The invoice status must be payment_due, posted, or not_paid.

Impacts

Invoice

The amount_due on the invoice decreases by transaction[amount] when the transaction[status] is success.
The invoice status changes to paid if the amount_due on the invoice becomes zero because of this payment. Otherwise, the status remains unchanged.

Customer

If the recorded payment exceeds the invoice's amount_due, the excess is added to the customer's excess_payments balance.

Implementation Notes

Before calling this API, ensure the following:

The invoice status must be payment_due, posted, or not_paid.

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 Valid 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 Valid 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 Valid 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	A unique identifier for the custom payment method of this transaction. Prerequisite The `transaction[payment_method]` is `custom`.
`transaction.amount`	Integer	No	The payment transaction amount. Default value If not specified, the `amount_due` on the invoice is considered as the payment amount.
`transaction.error_code`	String	No	Error code for the transaction failure. This is typically set by the payment gateway when a transaction fails. Prerequisite The `transaction[status]` is `failure` or `late_failure`.
`transaction.status`	String	No	The status of this transaction. * failure - Transaction failed. Pass the `transaction[error_code]` and `transaction[error_text]` to identify the reason for failure. The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. * success - The transaction was successful. Impacts The `amount_due` on the invoice is decreased by the `transaction[amount]`. If the `transaction[amount]` is greater than the `amount_due`, the excess amount is added to the customer's `excess_payments` balance. * 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. The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. * timeout - Transaction failed because of Gateway not accepting the connection. The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. * voided - The transaction got voided or authorization expired at gateway. The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. * late_failure - Indicates that a previously successful payment transaction has failed due to a late failure notification from the payment gateway. Common reasons include insufficient funds or a closed bank account. Pass the `transaction[error_code]` and `transaction[error_text]` to identify the reason for failure. The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. * 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 The `amount_due` on the invoice or the customer's `excess_payments` balance is not affected when this status is set. Valid 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 * electronic_payment_standard - Electronic Payment Standard * online_banking_poland - Online Banking Poland * netbanking_emandates - netbanking_emandates * klarna_pay_now - Klarna Pay Now * payconiq_by_bancontact - Payconiq by Bancontact * pay_by_bank - Pay By Bank * kbc_payment_button - KBC Payment Button * paypal_express_checkout - Paypal Express Checkout * automated_bank_transfer - Automated Bank Transfer * venmo - Venmo * bancontact - Bancontact * custom - Custom payment method. Prerequisite Custom payment methods must be enabled in Chargebee Billing. * ideal - IDEAL * check - Check * upi - upi * sepa_instant_transfer - Sepa Instant Transfer * sepa_credit - SEPA Credit * ach_credit - ACH Credit * faster_payments - Faster Payments * trustly - Trustly * 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 * stablecoin - Stablecoin * pix - Pix Valid values: `"check"` `"other"` `"cash"` `"bank_transfer"` `"custom"`
`transaction.date`	Integer	No	Indicates when this transaction occurred.
`transaction.error_text`	String	No	Error message for transaction failure. This is typically set by the payment gateway when a transaction fails. Prerequisite The `transaction[status]` is `failure` or `late_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.