Transactions

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

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

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

type

enumerated string

Type of the transaction.

Possible values are

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=0

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

initiator_type

optional, enumerated string

Marker for on-session payments (3DS). null indicates 'merchant'.

Possible values are

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

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

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

type

enumerated string

Type of the transaction.

Possible values are

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=0

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

initiator_type

optional, enumerated string

Marker for on-session payments (3DS). null indicates 'merchant'.

Possible values are

three_d_secure

optional, boolean

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

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.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

Click to Copy

200:

STATUS

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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

Only for Java

copy full code

Click to Copy

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

200:

STATUS

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

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/transactions/txn___test__5SK0bLNFRFuCF6tMV \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

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

Only for Java

copy full code

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

copy

Click to Copy

200:

STATUS

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

The payment method of this transaction.

Possible values are

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.

invoice

always returned
Resource object representing invoice

transaction

always returned
Resource object representing transaction

Sample transaction [ JSON ]

API Index URL

Model Class

Transaction attributes

Consent Fields for Transaction

Custom Fields for Transaction

List transactions ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List transactions for a customer ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List transactions for a subscription ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List transactions for an invoice ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a transaction ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Record Payment for an invoice ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL