Transactions

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.

payment_method_details

optional, string, max chars=null
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 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 failuretimeoutTransaction 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 ]

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

transaction

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 ]

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

transaction

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 ]

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

transaction

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 ]

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

transaction

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 ]

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

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.

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 ]

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

cashCashcheckCheck

bank_transferBank Transferdirect_debitDirect DebitotherPayment 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.

transaction

always returned
Resource object representing transaction

invoice

always returned
Resource object representing invoice

Sample transaction [ JSON ]

API Index URL GET

Transaction attributes

List transactions¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

List transactions for a customer¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

List transactions for a subscription¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

List transactions for an invoice¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Retrieve a transaction¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Record Payment for an invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns