API Version
Product Catalog
Library
This resource represents the transaction event that has happened in your account.

Sample transaction [ JSON ]

{ "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" } }

API Index URL GET

https://{site}.chargebee.com/api/v1/transactions

Model Class

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
cardCardcashCashcheckCheckchargebackOnly 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.
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
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.
Show all values[+]
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
Show all values[+]
initiator_type
optional, enumerated string
Marker for on-session payments (3DS). null indicates ‘merchant’.
Possible values are
customerCustomer initiated 3DS paymentmerchantPayment initiated on stored payment method by the merchant
Show all values[+]
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.
payment_method_details
optional, string
Payment method details of the corresponding transaction
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_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.
id id
string, max chars=40
Uniquely identifies the transaction.
customer_id customer_id
optional, string, max chars=50
Identifier of the customer for which this transaction is made
subscription_id subscription_id
optional, string, max chars=50
Identifier of the subscription for which this transaction is made.
payment_method payment_method
enumerated string, default=card
The payment method of this transaction
reference_number reference_number
optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.
gateway gateway
enumerated string
Gateway through which this transaction was done. Applicable only for 'Card' Payment Method
type type
enumerated string
Type of the transaction.
date date
optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.
currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) for the transaction.
amount amount
optional, in cents, min=1
Amount for this transaction.
id_at_gateway id_at_gateway
optional, string, max chars=100
The id with which this transaction is referred in gateway.
status status
optional, enumerated string
The status of this transaction.
initiator_type initiator_type
optional, enumerated string
Marker for on-session payments (3DS). null indicates ‘merchant’.
three_d_secure 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 error_code
optional, string, max chars=100
Error code received from the payment gateway on failure.
error_text error_text
optional, string, max chars=65k
Error message received from the payment gateway on failure.
voided_at voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating when the payment was voided or authorization expired at gateway.
amount_unused 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 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 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 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 reversal_transaction_id
optional, string, max chars=40
Reversal transaction id. Applicable only for payment transactions.
payment_method_details payment_method_details
optional, string
Payment method details of the corresponding transaction
linked_invoices
optional, list of invoice_transaction
Applicable only for 'Payment' transactions. The list of invoices this 'payment' transaction is applied to.
linked_refunds
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.
Lists all the transactions.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

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

Method

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.
transaction transaction
always returned
Resource object representing transaction
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/transactions/123x
Retrieves the transactions for a customer sorted by the recent ones on top.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/customers/__test__5SK0bLNFRFuCFQeMZ/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

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

Method

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.
transaction transaction
always returned
Resource object representing transaction
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/transactions/123x
Retrieves the transactions for a subscription sorted by the recent ones on top.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__5SK0bLNFRFuCGAUMu/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

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

Method

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.
transaction transaction
always returned
Resource object representing transaction
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/transactions/123x
Retrieves the transactions for an invoice with the recent ones on top. This returns all the payment attempts(manual & automatic) made for this invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__5/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

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

Method

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.
transaction transaction
always returned
Resource object representing transaction
next_offset 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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/transactions/123x
Retrieve a transaction identified by its unique id.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/transactions/txn___test__5SK0bLNFRFuCF6tMV \
     -u {site_api_key}:
copy
Click to Copy

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}

Method

transaction transaction
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.

Notes

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
Click to Copy

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

Method

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
The payment method of this transaction.
Possible values are
cashCashcheckCheckbank_transferBank Transferdirect_debitDirect Debit
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.
transaction transaction
always returned
Resource object representing transaction
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

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