Transactions

API Version

Product Catalog

Library

This resource represents the transaction event that has happened in your account.

Sample transaction [ JSON ]

{
    "amount": 1000,
    "amount_capturable": 1000,
    "authorization_reason": "blocking_funds",
    "base_currency_code": "USD",
    "currency_code": "USD",
    "customer_id": "__test__KyVnHhSBWltgF2p6",
    "date": 1600968316,
    "deleted": false,
    "exchange_rate": 1,
    "fraud_reason": "Payment complete.",
    "gateway": "stripe",
    "gateway_account_id": "gw___test__KyVnGlSBWltbL2AB",
    "id": "txn___test__KyVnHhSBWltv42pB",
    "id_at_gateway": "ch_1HUyC0Jv9j0DyntJiR6W37yv",
    "linked_payments": [],
    "masked_card_number": "************1111",
    "object": "transaction",
    "payment_method": "card",
    "payment_source_id": "pm___test__KyVnHhSBWltu42p7",
    "resource_version": 1517505917000,
    "status": "success",
    "type": "authorization",
    "updated_at": 1517505917
}

API Index URL GET

https://{site}.chargebee.com/api/v2/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.

gateway_account_id

optional, string, max chars=50
The gateway account used for this transaction

payment_source_id

optional, string, max chars=40
Identifier of the payment source 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.

settled_at

optional, timestamp(UTC) in seconds
Indicates the time at which the final status of the transaction has been marked.

exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999
Exchange rate used for base currency conversion

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

fraud_flag

optional, enumerated string
Indicates whether or not the transaction has been identified as fraudulent.

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.

authorization_reason

optional, enumerated string
Type of authorization transaction.

Possible values are

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.

resource_version

optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this transaction was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

fraud_reason

optional, string, max chars=250
Short description why the transaction was marked as fraud/suspicious

custom_payment_method_id

optional, string, max chars=50
Identifier of the custom payment method of this transaction.

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.

reference_authorization_id

optional, string, max chars=40
This is the id of the transaction (always of type = authorization) which authorizes the payment being captured. Applicable only for transaction of type = payment.

amount_capturable

optional, in cents, min=0
This is the part of the authorized amount that is yet to be captured. The payment capture is recorded as a transaction of of type = payment. Applicable only for a transaction of type = authorization.

reversal_transaction_id

optional, string, max chars=40
Reversal transaction id. Applicable only for payment transactions.

deleted

boolean
Indicates that this resource has been deleted.

iin

optional, string, min chars=4, max chars=6
First 6 digits of the card payment method.

last4

optional, string, min chars=4, max chars=4
Last 4 digits of the card payment method.

merchant_reference_id

optional, string, max chars=500
A unique id used to track this transaction across various systems you integrate with. This id is passed to the payment gateway when the transaction is initiated. Supported only for the Exact payment gateway.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this transaction. This is always the same as the business entity of the customer.

payment_method_details

optional, string
Payment method details of the corresponding transaction

custom_payment_method_name

optional, string, max chars=100
Name of the custom payment method of this 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_credit_notes
Show attributes [+]

optional, list of credit_note_transaction
Applicable only for 'Refund' transactions. The list of Credit Notes this 'refund' transaction is associated with.

Linked credit note attributes

cn_id

string, max chars=50
Identifier for the credit-notes.

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.

cn_reason_code

optional, enumerated string
Credit note reason code. Deprecated use the cn_create_reason_code parameter instead

Possible values are

cn_create_reason_code

optional, string, max chars=100
Credit note reason code

cn_date

optional, timestamp(UTC) in seconds
The date this credit note is created.

cn_total

optional, in cents, default=0, min=0
Total amount of the credit note

cn_status

enumerated string
The status of this Credit Note.

Possible values are

cn_reference_invoice_id

optional, string, max chars=50
The invoice number. Acts as a identifier for invoice and typically generated sequentially.

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_payments
Show attributes [+]

optional, list of linked_payment
The list of payments captured for this authorization transaction.

error_detail
Show attributes [+]

optional, gateway_error_detail
Comprehensive information regarding the error experienced during an unsuccessful or declined transaction. Learn more about gateway error references

Error detail attributes

request_id

optional, string, max chars=100
This is a unique identifier assigned by the payment gateway. It is used to track the request at the payment gateway

error_category

optional, string, max chars=100
This parameter categorizes the type of error that occurred for the request. It helps in understanding whether the error is due to API error, validation, processing, network issues, and more

error_code

optional, string, max chars=100
A gateway-specific code that corresponds to the particular error encountered for the request. This code can be used for identifying the error in a standardized manner across the gateway's services

error_message

optional, string, max chars=65k
A message provided by the gateway that describes the nature of the error encountered

decline_code

optional, string, max chars=100
When a transaction is declined, this code is provided by the gateway to specify the reason for the decline

decline_message

optional, string, max chars=65k
This message gives a descriptive explanation of the reason for the transaction's decline

network_error_code

optional, string, max chars=100
This code represents errors that originate from the payment network (such as Visa, MasterCard, and more). It is different from the gateway error code and is specific to the network's error-handling system

network_error_message

optional, string, max chars=65k
This the network related error message from the gateway, this is a detailed message provided by the payment network explaining the nature of the network error encountered

error_field

optional, string, max chars=100
This parameter indicates which specific data field or attribute in the request caused the error

recommendation_code

optional, string, max chars=100
After an error has occurred, the gateway or payment network may provide a recommendation code. This code suggests a course of action or remedy that you can follow to resolve the issue

recommendation_message

optional, string, max chars=65k
This message is intended to provide guidance or suggestions on action or remedy that you can follow to resolve the issue

processor_error_code

optional, string, max chars=100
This code is provided by the payment processor (the entity that handles the transaction between the bank accounts and the payment networks) and indicates errors that occur at this stage of the payment process

processor_error_message

optional, string, max chars=65k
This message describes the specific error that the payment processor encountered

error_cause_id

optional, string, max chars=150
A Chargebee-defined code that corresponds to the specific error encountered during the request. This code helps in identifying and standardizing the error across different gateway services for consistent error handling.

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.

gateway_account_id

optional, string, max chars=50
The gateway account used for this transaction

payment_source_id

optional, string, max chars=40
Identifier of the payment source 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.

settled_at

optional, timestamp(UTC) in seconds
Indicates the time at which the final status of the transaction has been marked.

exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999
Exchange rate used for base currency conversion

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

fraud_flag

optional, enumerated string
Indicates whether or not the transaction has been identified as fraudulent.

Possible values are

initiator_type

optional, enumerated string
Marker for on-session payments (3DS). null indicates ‘merchant’.

Possible values are

three_d_secure

authorization_reason

optional, enumerated string
Type of authorization transaction.

Possible values are

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.

resource_version

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this transaction was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

fraud_reason

optional, string, max chars=250
Short description why the transaction was marked as fraud/suspicious

custom_payment_method_id

optional, string, max chars=50
Identifier of the custom payment method of this transaction.

amount_unused

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.

reference_authorization_id

amount_capturable

reversal_transaction_id

optional, string, max chars=40
Reversal transaction id. Applicable only for payment transactions.

deleted

boolean
Indicates that this resource has been deleted.

iin

optional, string, min chars=4, max chars=6
First 6 digits of the card payment method.

last4

optional, string, min chars=4, max chars=4
Last 4 digits of the card payment method.

merchant_reference_id

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this transaction. This is always the same as the business entity of the customer.

payment_method_details

optional, string
Payment method details of the corresponding transaction

custom_payment_method_name

optional, string, max chars=100
Name of the custom payment method of this transaction.

linked_invoices

optional, list of invoice_transaction
Applicable only for 'Payment' transactions. The list of invoices this 'payment' transaction is applied to.

linked_credit_notes

optional, list of credit_note_transaction
Applicable only for 'Refund' transactions. The list of Credit Notes this 'refund' transaction is associated with.

linked_refunds

linked_payments

optional, list of linked_payment
The list of payments captured for this authorization transaction.

error_detail

optional, gateway_error_detail
Comprehensive information regarding the error experienced during an unsuccessful or declined transaction. Learn more about gateway error references

Authorizes a specific amount in customer's Credit card, which can be collected within a span of time. Read more on authorization and capture here.

Notes

Supported only for Card payments.
Currently supported only for Stripe.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/create_authorization \
     -u {site_api_key}:\
     -d customer_id="__test__KyVnHhSBWltgF2p6" \
     -d amount=1000

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 1000,
        "amount_capturable": 1000,
        "authorization_reason": "blocking_funds",
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWltgF2p6",
        "date": 1600968316,
        "deleted": false,
        "exchange_rate": 1,
        "fraud_reason": "Payment complete.",
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWltbL2AB",
        "id": "txn___test__KyVnHhSBWltv42pB",
        "id_at_gateway": "ch_1HUyC0Jv9j0DyntJiR6W37yv",
        "linked_payments": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWltu42p7",
        "resource_version": 1517505917000,
        "status": "success",
        "type": "authorization",
        "updated_at": 1517505917
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/create_authorization

customer_id[]

required, string, max chars=50
Identifier of the customer.

payment_source_id[]

optional, string, max chars=40
Payment source to be used for authorizing the transaction.

currency_code[]

required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the transaction amount.

amount[]

required, in cents, min=1
The amount to be blocked.

transaction

always returned
Resource object representing transaction

This API voids the specific authorization transaction in order to release the blocked funds from the customer’s card. Voiding an already captured or voided transaction is not possible.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/txn___test__KyVnHhSBWlzMQ2rA/void \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 1000,
        "amount_capturable": 0,
        "authorization_reason": "blocking_funds",
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWlzC52r5",
        "date": 1600968337,
        "deleted": false,
        "exchange_rate": 1,
        "fraud_reason": "Payment complete.",
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWltbL2AB",
        "id": "txn___test__KyVnHhSBWlzMQ2rA",
        "id_at_gateway": "ch_1HUyCLJv9j0DyntJDiqqG6XL",
        "linked_payments": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWlzLf2r6",
        "resource_version": 1517505939000,
        "status": "voided",
        "type": "authorization",
        "updated_at": 1517505939,
        "voided_at": 1600968339
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}/void

transaction

always returned
Resource object representing transaction

Records a refund made offline. Applicable only for transactions of type = payment.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/txn___test__KyVnHhSBWlwT42q7/record_refund \
     -u {site_api_key}:\
     -d date=1601054726 \
     -d amount=1000 \
     -d payment_method="CHARGEBACK" \
     -d reference_number="5266787652" \
     -d comment="payment disputed"

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWlwHl2q0",
        "date": 1601054726,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__KyVnHhSBWlwhi2qE",
        "linked_credit_notes": [],
        "object": "transaction",
        "payment_method": "chargeback",
        "reference_number": "5266787652",
        "reference_transaction_id": "txn___test__KyVnHhSBWlwT42q7",
        "resource_version": 1517505927000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517505927
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}/record_refund

amount[]

optional, in cents, min=1
The amount to be recorded as refunded. Must not exceed amount_unused. If not passed then all of amount_unused is recorded as refunded.

payment_method[]

required, enumerated string
The payment method used to make the refund.

Possible values are

date[]

required, timestamp(UTC) in seconds
The date when the refund was made.

reference_number[]

optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.

custom_payment_method_id[]

optional, string, max chars=50
Identifier of the custom payment method of this transaction.

comment[]

optional, string, max chars=300
Remarks, if any, on the refund.

transaction

always returned
Resource object representing transaction

Update selected attributes of the transaction resource: status, id_at_gateway, and customer_id. Use this API for reconciliation purposes where the status of a transaction is in needs_attention that can be updated to either success or failure status.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/txn___test__KyVnHhSBWlwT42q7/reconcile \
     -u {site_api_key}:\
     -d id_at_gateway="cb___test__KyVnHhSBWlv4q2pU" \
     -d customer_id="__test__KyVnHhSBWlv242pN" \
     -d status="SUCCESS"

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 1395,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWlv242pN",
        "date": 1517505921,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWltEk29Z",
        "id": "txn___test__KyVnHhSBWlwT42q7",
        "id_at_gateway": "cb___test__KyVnHhSBWlv4q2pU",
        "linked_invoices": [
            {
                "applied_amount": 1395,
                "applied_at": 1517505921,
                "invoice_date": 1517505920,
                "invoice_id": "__demo_inv__3",
                "invoice_status": "paid",
                "invoice_total": 1395
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWlv2z2pP",
        "resource_version": 1517505921000,
        "status": "success",
        "subscription_id": "__test__KyVnHhSBWlv242pN",
        "type": "payment",
        "updated_at": 1517505921
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}/reconcile

id_at_gateway[]

optional, string, max chars=100
The identifier with which this transaction is referred in gateway. The id_at_gateway can only be updated when the transaction status is in needs_attention.

Note:

It is mandatory to pass this parameter value for updating the transaction status from needs_attention to success. It is recommended to pass this value if available in the gateway.
An error occurs when the provided id_at_gateway value does not match the id_at_gateway value stored against the transaction in Chargebee.

customer_id[]

optional, string, max chars=50
Unique identifier of the customer for which this transaction is made. This is needed only when the transaction is successful but not associated with any customer.

Note:
An error occurs when the provided customer_id value does not match the customer_id value stored against the transaction in Chargebee.

status[]

optional, enumerated string
The status of this transaction. The status can only be updated when the transaction status is in needs_attention state.

Possible values are

transaction

always returned
Resource object representing transaction

Refunds an online payment. Applicable only for transactions of type = payment. You can only refund a transaction whose status is success.

Notes

Not supported for ach_credit, sepa_credit, cash, check, bank_transfer, other.
Contact support@chargebee.com to enable this endpoint.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/txn___test__KyVnpGSCut0cY8/refund \
     -u {site_api_key}:\
     -d comment="Refunding a transaction"

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnpGSCuszos1",
        "date": 1517482377,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnw0SCuszXd2I",
        "id": "txn___test__KyVnpGSCut11oF",
        "id_at_gateway": "re_1HaJDZJv9j0DyntJA2VZNft4",
        "linked_credit_notes": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnpGSCut0FD2",
        "reference_transaction_id": "txn___test__KyVnpGSCut0cY8",
        "refunded_txn_id": "txn___test__KyVnpGSCut0cY8",
        "resource_version": 1517482378000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517482378
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}/refund

amount[]

optional, in cents, min=1
The amount to be refunded. Must not exceed amount_unused. If not passed then all of amount_unused is refunded.

comment[]

optional, string, max chars=300
Remarks, if any, on the refund.

transaction

always returned
Resource object representing transaction

Lists all the transactions.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode "status[is]"="success" \
     --data-urlencode "sort_by[asc]"=date

copy

Click to Copy

Sample Response [ JSON ]

{
    "list": [
        {
            "transaction": {
                "amount": 1395,
                "amount_unused": 0,
                "base_currency_code": "USD",
                "currency_code": "USD",
                "customer_id": "__test__KyVnHhSBWlv242pN",
                "date": 1517505921,
                "deleted": false,
                "exchange_rate": 1,
                "gateway": "chargebee",
                "gateway_account_id": "gw___test__KyVnGlSBWltEk29Z",
                "id": "txn___test__KyVnHhSBWlv4j2pT",
                "id_at_gateway": "cb___test__KyVnHhSBWlv4q2pU",
                "linked_invoices": [
                    {
                        "applied_amount": 1395,
                        "applied_at": 1517505921,
                        "invoice_date": 1517505920,
                        "invoice_id": "__demo_inv__3",
                        "invoice_status": "paid",
                        "invoice_total": 1395
                    },
                    {..}
                ],
                "linked_refunds": [],
                "masked_card_number": "************1111",
                "object": "transaction",
                "payment_method": "card",
                "payment_source_id": "pm___test__KyVnHhSBWlv2z2pP",
                "resource_version": 1517505921000,
                "status": "success",
                "subscription_id": "__test__KyVnHhSBWlv242pN",
                "type": "payment",
                "updated_at": 1517505921
            }
        },
        {..}
    ],
    "next_offset": "[\"1600622718000\",\"266000001127\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v2/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.

include_deleted[]

optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : date, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter
Uniquely identifies the transaction.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "txn_88ybdbsnvf2"

customer_id[<operator>]

optional, string filter
Identifier of the customer for which this transaction is made.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → customer_id[is] = "5hjdk8nOpd"

subscription_id[<operator>]

optional, string filter
Identifier of the subscription for which this transaction is made.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → subscription_id[is] = "5hjdk8nOpd"

payment_source_id[<operator>]

optional, string filter
To filter based on Transaction payment source id.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → payment_source_id[is] = "pm_3Nl8XXUQUXDVFa2"

payment_method[<operator>]

optional, enumerated string filter
The payment method of this transaction. Possible values are : card, cash, check, chargeback, bank_transfer, amazon_payments, paypal_express_checkout, direct_debit, alipay, unionpay, apple_pay, wechat_pay, ach_credit, sepa_credit, ideal, google_pay, sofort, bancontact, giropay, dotpay, other, upi, netbanking_emandates, custom, boleto, venmo, pay_to, faster_payments, sepa_instant_transfer, automated_bank_transfer, klarna_pay_now, online_banking_poland, payconiq_by_bancontact
Supported operators : is, is_not, in, not_in

Example → payment_method[is] = "card"

gateway[<operator>]

optional, enumerated string filter
Gateway through which this transaction was done. Applicable only for 'Card' Payment Method. Possible values are : chargebee, chargebee_payments, adyen, stripe, wepay, braintree, authorize_net, paypal_pro, pin, eway, eway_rapid, worldpay, balanced_payments, beanstream, bluepay, elavon, first_data_global, hdfc, migs, nmi, ogone, paymill, paypal_payflow_pro, sage_pay, tco, wirecard, amazon_payments, paypal_express_checkout, gocardless, orbital, moneris_us, moneris, bluesnap, cybersource, vantiv, checkout_com, paypal, ingenico_direct, exact, mollie, quickbooks, razorpay, global_payments, bank_of_america, ecentric, metrics_global, windcave, pay_com, ebanx, dlocal, nuvei, solidgate, paystack, jp_morgan, not_applicable
Supported operators : is, is_not, in, not_in

Example → gateway[is] = "stripe"

gateway_account_id[<operator>]

optional, string filter
The gateway account used for this transaction.
Supported operators : is, is_not, starts_with, in, not_in

Example → gateway_account_id[is] = "gw_3Nl9BNeQ7438Ks1"

id_at_gateway[<operator>]

optional, string filter
The id with which this transaction is referred in gateway.
Supported operators : is, is_not, starts_with

Example → id_at_gateway[is] = "txn_5678HJS89900"

reference_number[<operator>]

optional, string filter
The reference number for this transaction. For example, the check number when payment_method = check.
Supported operators : is, is_not, starts_with, is_present

Example → reference_number[is] = "cus_u239732"

type[<operator>]

optional, enumerated string filter
Type of the transaction. Possible values are : authorization, payment, refund, payment_reversal
Supported operators : is, is_not, in, not_in

Example → type[is] = "payment"

date[<operator>]

optional, timestamp(UTC) in seconds filter
Indicates when this transaction occurred.
Supported operators : after, before, on, between

Example → date[after] = "1435054328"

amount[<operator>]

optional, number filter
Amount for this transaction.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount[is] = "1200"

amount_capturable[<operator>]

optional, number filter
To filter based on transaction’s unused authorized/blocked amount.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_capturable[is] = "1200"

status[<operator>]

optional, enumerated string filter
The status of this transaction. Possible values are : in_progress, success, voided, failure, timeout, needs_attention, late_failure
Supported operators : is, is_not, in, not_in

Example → status[is] = "success"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
To filter based on updated_at. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response.
Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

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 payments for an invoice with the recent ones on top. This returns all the payment attempts(manual & automatic) made for this invoice.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/payments \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1

copy

Click to Copy

Sample Response [ JSON ]

{
    "list": [
        {
            "transaction": {
                "amount": 100,
                "amount_unused": 0,
                "base_currency_code": "USD",
                "currency_code": "USD",
                "customer_id": "__test__KyVnHhSBWlvSM2pk",
                "date": 1600968323,
                "deleted": false,
                "exchange_rate": 1,
                "fraud_reason": "Payment complete.",
                "gateway": "stripe",
                "gateway_account_id": "gw___test__KyVnGlSBWltbL2AB",
                "id": "txn___test__KyVnHhSBWlvlh2pw",
                "id_at_gateway": "ch_1HUyC7Jv9j0DyntJJ6FrzqKp",
                "linked_invoices": [
                    {
                        "applied_amount": 100,
                        "applied_at": 1517505924,
                        "invoice_date": 1517505923,
                        "invoice_id": "__demo_inv__4",
                        "invoice_status": "payment_due",
                        "invoice_total": 1095
                    },
                    {..}
                ],
                "linked_refunds": [],
                "masked_card_number": "************1111",
                "object": "transaction",
                "payment_method": "card",
                "payment_source_id": "pm___test__KyVnHhSBWlvgw2pl",
                "resource_version": 1517505924000,
                "status": "success",
                "subscription_id": "__test__KyVnHhSBWlvi12pp",
                "type": "payment",
                "updated_at": 1517505924
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/payments

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 100,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWlwxY2qJ",
        "date": 1600968329,
        "deleted": false,
        "exchange_rate": 1,
        "fraud_reason": "Payment complete.",
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGlSBWltbL2AB",
        "id": "txn___test__KyVnHhSBWlxBX2qV",
        "id_at_gateway": "ch_1HUyCDJv9j0DyntJaAcmSVfG",
        "linked_invoices": [
            {
                "applied_amount": 100,
                "applied_at": 1517505929,
                "invoice_date": 1517505928,
                "invoice_id": "__demo_inv__6",
                "invoice_status": "payment_due",
                "invoice_total": 1095
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWlx6v2qK",
        "resource_version": 1517505929000,
        "status": "success",
        "subscription_id": "__test__KyVnHhSBWlx8C2qO",
        "type": "payment",
        "updated_at": 1517505929
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}

transaction

always returned
Resource object representing transaction

Sample admin console URL

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

This API deletes an offline transaction. However, to delete an offline transaction all payment allocations associated with the transaction must be removed.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/transactions/txn___test__KyVnHhSBWluhp2pD/delete_offline_transaction \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

{
    "transaction": {
        "amount": 895,
        "amount_unused": 895,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnGlSBWluMI2AM",
        "date": 1517505919,
        "deleted": true,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__KyVnHhSBWluhp2pD",
        "linked_invoices": [],
        "linked_refunds": [],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517505919000,
        "status": "success",
        "type": "payment",
        "updated_at": 1517505919
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/transactions/{transaction-id}/delete_offline_transaction

comment[]

optional, string, max chars=300
Reason for deleting this transaction. This comment will be added to the associated entity.

transaction

always returned
Resource object representing transaction

Sample transaction [ JSON ]

API Index URL GET

Model Class

Transaction attributes

Consent Fields for Transaction

Custom Fields for Transaction

Create an authorization payment ¶

Notes

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

Void an authorization transaction ¶

Notes

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

Record an offline refund ¶

Notes

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

Reconcile transaction ¶

Notes

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

Refund a payment ¶

Notes

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

List transactions ¶

Notes

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 payments for an invoice ¶

Notes

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 ¶

Notes

Sample Response [ JSON ]