You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
This resource represents the transaction event that has happened in your account.

Sample transaction [ JSON ]

{ "amount": 1395, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuCEDDLg", "date": 1517506742, "gateway": "chargebee", "id": "txn___test__5SK0bLNFRFuCEEELm", "id_at_gateway": "cb___test__5SK0bLNFRFuCEEJLn", "linked_invoices": [{ "applied_amount": 1395, "applied_at": 1517506742, "invoice_amount": 1395, "invoice_date": 1517506742, "invoice_id": "__demo_inv__1" }], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__5SK0bLNFRFuCEDDLg", "type": "payment" }

API Index URL GET

https://{site}.chargebee.com/api/v1/transactions
id
string, max chars=40
Uniquely identifies the transaction.
customer_id
optional, string, max chars=50
Identifier of the customer for which this transaction is made.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this transaction is made.
payment_method
enumerated string, default=card
The payment method of this transaction.
Possible values are
cardCard.cashCash.checkCheck.chargebackOnly 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.
bank_transferBank Transfer.amazon_paymentsAmazon Payments.paypal_express_checkoutPaypal Express Checkout.direct_debitDirect Debit.otherPayment Methods other than the above types.
Show all values[+]
reference_number
optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.
gateway
enumerated string
Gateway through which this transaction was done. Applicable only for 'Card' Payment Method.
Possible values are
chargebeeChargebee test gateway.stripeStripe is a payment gateway.braintreeBraintree is a payment gateway.
authorize_netAuthorize.net is a payment gateway.paypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gateway.ewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gateway.balanced_paymentsBalanced is a payment gateway.beanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
type
enumerated string
Type of the transaction.
Possible values are
authorizationThe transaction represents an authorization for capturing the amount from the customer’s payment_source.paymentThe transaction represents capture of amount from the customer’s payment_source.refundThe transaction represents a refund of amount to the customer’s payment_source.payment_reversalIndicates a reversal transaction.
date
optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.
currency_code
string, max chars=3
The currency code (ISO 4217 format) for the transaction.
amount
optional, in cents, min=1
Amount for this transaction.
id_at_gateway
optional, string, max chars=100
The id with which this transaction is referred in gateway.
status
optional, enumerated string
The status of this transaction.
Possible values are
in_progressTransaction 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.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.timeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually.
initiator_type
optional, enumerated string
Marker for on-session payments (3DS). null indicates ‘merchant’.
Possible values are
customerCustomer initiated 3DS payment.merchantPayment initiated on stored payment method by the merchant.
three_d_secure
optional, boolean
Indicates whether this transaction has gone through 3DS. Applicable only for ‘on-session’ payments & verifications.If 3DS is not enforced by the gateway/bank or if the customers’ card is not enrolled, this will be false.
error_code
optional, string, max chars=100
Error code received from the payment gateway on failure.
error_text
optional, string, max chars=65k
Error message received from the payment gateway on failure.
voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating when the payment was voided or authorization expired at gateway.
amount_unused
optional, in cents, min=0
This is the part of the amount which has not been invoiced yet and is therefore added to excess_payments for the customer. Applicable only for a transaction of type = payment.
masked_card_number
optional, string, max chars=20
The masked card number used for this transaction. Applicable only for 'Card' Payment Method.
reference_transaction_id
optional, string, max chars=40
This is the id of the offline transaction that is being refunded or reversed. Applicable only for transaction of type = refund or payment_reversal.
refunded_txn_id
optional, string, max chars=40
This is the id of the transaction (always of type = payment) being refunded. Applicable only for transaction of type = refund.
reversal_transaction_id
optional, string, max chars=40
Reversal transaction id. Applicable only for payment transactions.
linked_invoices
Show attributes[+]
optional, list of invoice_transaction
Applicable only for 'Payment' transactions. The list of invoices this 'payment' transaction is applied to.
Linked invoice attributes
invoice_id
string, max chars=50
Identifier for the invoice.
applied_amount
in cents, min=0
The transaction amount applied to this invoice.
applied_at
timestamp(UTC) in seconds
Timestamp at which the transaction is applied.
invoice_date
optional, timestamp(UTC) in seconds
The date this invoice is issued.
invoice_amount
optional, in cents, min=0
Total amount of the invoice.
linked_refunds
Show attributes[+]
optional, list of txn_refunds_and_reversal
Applicable only for Payment transactions. It only returns values when the transaction is not associated with an invoice, and that there is a refund for the transaction.
Linked refund attributes
txn_id
string, max chars=40
Uniquely identifies the transaction.
txn_status
enumerated string
The status of this transaction.
Possible values are
in_progressTransaction 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.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.timeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually.
txn_date
timestamp(UTC) in seconds
Indicates when this refund occured.
txn_amount
in cents, min=1
Amount of this refund transaction.
Lists all the transactions.
Sample Request
curl  https://{site}.chargebee.com/api/v1/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"transaction": { "amount": 1395, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuCEDDLg", "date": 1517506742, "gateway": "chargebee", "id": "txn___test__5SK0bLNFRFuCEEELm", "id_at_gateway": "cb___test__5SK0bLNFRFuCEEJLn", "linked_invoices": [ { "applied_amount": 1395, "applied_at": 1517506742, "invoice_amount": 1395, "invoice_date": 1517506742, "invoice_id": "__demo_inv__1" }, {..} ], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__5SK0bLNFRFuCEDDLg", "type": "payment" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v1/transactions
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
always returned
Resource object representing transaction.
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Retrieves the transactions for a customer sorted by the recent ones on top.
Sample Request
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuCFQeMZ/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuCFQeMZ/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"transaction": { "amount": 100, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuCFQeMZ", "date": 1548178748, "gateway": "stripe", "id": "txn___test__5SK0bLNFRFuCFhQMl", "id_at_gateway": "ch_1DvTDMJv9j0DyntJ8ST8mmGb", "linked_invoices": [ { "applied_amount": 100, "applied_at": 1517506749, "invoice_amount": 1095, "invoice_date": 1517506748, "invoice_id": "__demo_inv__4" }, {..} ], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__5SK0bLNFRFuCFfNMe", "type": "payment" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v1/customers/{customer_id}/transactions
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
always returned
Resource object representing transaction.
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Retrieves the transactions for a subscription sorted by the recent ones on top.
Sample Request
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuCGAUMu/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuCGAUMu/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"transaction": { "amount": 100, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuCFxzMp", "date": 1548178750, "gateway": "stripe", "id": "txn___test__5SK0bLNFRFuCGCaN1", "id_at_gateway": "ch_1DvTDOJv9j0DyntJHrlqpU2Y", "linked_invoices": [ { "applied_amount": 100, "applied_at": 1517506751, "invoice_amount": 1095, "invoice_date": 1517506750, "invoice_id": "__demo_inv__5" }, {..} ], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__5SK0bLNFRFuCGAUMu", "type": "payment" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id}/transactions
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
always returned
Resource object representing transaction.
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Retrieves the transactions for an invoice with the recent ones on top. This returns all the payment attempts(manual & automatic) made for this invoice.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__5/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__5/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"transaction": { "amount": 1395, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__3Nl9RLTRcPqBFy4y", "date": 1517479653, "gateway": "chargebee", "id": "txn___test__3Nl9RLTRcPqBIC58", "id_at_gateway": "cb___test__3Nl9RLTRcPqBIH59", "linked_invoices": [ { "applied_amount": 1395, "applied_at": 1517479653, "invoice_amount": 1395, "invoice_date": 1517479653, "invoice_id": "__demo_inv__5" }, {..} ], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__3Nl9RLTRcPqBGy54", "type": "payment" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/transactions
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
always returned
Resource object representing transaction.
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Retrieve a transaction identified by its unique id.
Sample Request
curl  https://{site}.chargebee.com/api/v1/transactions/txn___test__5SK0bLNFRFuCF6tMV \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/transactions/txn___test__5SK0bLNFRFuCF6tMV \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"transaction": { "amount": 100, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__5SK0bLNFRFuCErEMJ", "date": 1548178746, "gateway": "stripe", "id": "txn___test__5SK0bLNFRFuCF6tMV", "id_at_gateway": "ch_1DvTDKJv9j0DyntJljN5is2h", "linked_invoices": [ { "applied_amount": 100, "applied_at": 1517506747, "invoice_amount": 1095, "invoice_date": 1517506745, "invoice_id": "__demo_inv__3" }, {..} ], "linked_refunds": [], "masked_card_number": "************1111", "object": "transaction", "payment_method": "card", "status": "success", "subscription_id": "__test__5SK0bLNFRFuCF4lMO", "type": "payment" }}

URL Format GET

https://{site}.chargebee.com/api/v1/transactions/{transaction_id}
always returned
Resource object representing transaction.

Sample admin console URL

https://{site}.chargebee.com/admin-console/transactions/123x

To record offline payments (Cash,Check etc) for 'payment_due' or 'not_paid' invoices.

The invoice status will be marked as 'paid' when the amount that is due is recorded.

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__7/record_payment \
     -u {site_api_key}:\
     -d payment_method="bank_transfer" \
     -d paid_at=1568639254
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__7/record_payment \
     -u {site_api_key}:\
     -d payment_method="bank_transfer" \
     -d paid_at=1568639254

Sample Response [ JSON ]

Show more...
{ "invoice": { "amount": 895, "amount_adjusted": 0, "amount_due": 0, "amount_paid": 895, "billing_address": { "first_name": "Rachel", "last_name": "Green", "object": "billing_address" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__3Nl9RIYRcPqBKpX", "dunning_status": "stopped", "end_date": 1568549253, "first_invoice": false, "id": "__demo_inv__7", "line_items": [ { "amount": 895, "date_from": 1568549253, "date_to": 1571141253, "description": "No Trial", "entity_id": "no_trial", "entity_type": "plan", "is_taxed": false, "object": "line_item", "quantity": 1, "tax": 0, "type": "charge", "unit_amount": 895 }, {..} ], "linked_orders": [], "linked_transactions": [ { "applied_amount": 895, "applied_at": 1568549254, "txn_amount": 895, "txn_date": 1568549254, "txn_id": "txn___test__3Nl9RIYRcPqBeZ14", "txn_status": "failure", "txn_type": "payment" }, {..} ], "object": "invoice", "paid_on": 1568639254, "price_type": "tax_exclusive", "recurring": true, "start_date": 1568455653, "status": "paid", "sub_total": 895, "subscription_id": "__test__3Nl9RIYRcPqBKpX", "tax": 0 }, "transaction": { "amount": 895, "amount_unused": 0, "currency_code": "USD", "customer_id": "__test__3Nl9RIYRcPqBKpX", "date": 1568639254, "gateway": "not_applicable", "id": "txn___test__3Nl9RLTRcPqBn05E", "linked_invoices": [ { "applied_amount": 895, "applied_at": 1517479655, "invoice_amount": 895, "invoice_date": 1568549253, "invoice_id": "__demo_inv__7" }, {..} ], "linked_refunds": [], "object": "transaction", "payment_method": "bank_transfer", "status": "success", "subscription_id": "__test__3Nl9RIYRcPqBKpX", "type": "payment" } }

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/record_payment
amount
optional, in cents, min=1
Amount paid. If this parameter is not passed then the entire invoice due amount will be recorded.
payment_method
required, enumerated string, default=card
The payment method of this transaction.
Possible values are
cashCash.checkCheck.
bank_transferBank Transfer.direct_debitDirect Debit.otherPayment Methods other than the above types.
Show all values[+]
paid_at
required, timestamp(UTC) in seconds
Indicates when this transaction occurred.
reference_number
optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.
memo
optional, string, max chars=300
A short description or note regarding the payment received. This will be the description in the transaction created.
always returned
Resource object representing transaction.
always returned
Resource object representing invoice.