Transactions

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

Sample TransactionJSON

API Index URL

https://[site].chargebee.com/api/v2/transactions

Transactions attributes

required, 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

required, enumerated string, default=card

The payment method of this transaction

Enum Values

card

Card

cash

Cash

check

Check

chargeback

Only 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_transfer

Bank Transfer

reference_number

optional, string, max chars=100

The reference number for this transaction. For example, the check number when payment_method = check .

gateway

required, enumerated string

Gateway through which this transaction was done. Applicable only for 'Card' Payment Method

Enum Values

chargebee

Chargebee test gateway.

chargebee_payments

Chargebee Payments gateway

adyen

Adyen is a payment gateway.

stripe

Stripe is a payment gateway.

wepay

WePay is a payment gateway.

type

required, enumerated string

Type of the transaction.

Enum Values

authorization

The transaction represents an authorization for capturing the amount from the customer's payment_source .

payment

The transaction represents capture of amount from the customer's payment_source .

refund

The transaction represents a refund of amount to the customer's payment_source .

payment_reversal

Indicates a reversal transaction.

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

required, 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.

Enum Values

in_progress

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

success

The transaction is successful.

voided

The transaction got voided or authorization expired at gateway.

failure

Transaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure

timeout

Transaction failed because of Gateway not accepting the connection.

needs_attention

When connection with the Gateway gets terminated abruptly. For needs_attention status Chargebee automatically reconcile the transaction for few gateways, for rest of the gateways you have to use the Reconcile transaction API. You can use this API to update the id_at_gateway (Gateway Transaction ID) and status for a needs_attention transaction to be reconciled at par with the gateway.

Learn more about needs_attention transaction status

late_failure

Indicates that a successful payment transaction has failed now due to a late failure notification from the payment gateway, typically caused by issues like insufficient funds or a closed bank account.

fraud_flag

optional, enumerated string

Indicates whether or not the transaction has been identified as fraudulent.

Enum Values

safe

The transaction has been marked as safe

suspicious

The transaction has been identified as potentially fraudulent by the gateway

fraudulent

The transaction has been marked as fraudulent

initiator_type

optional, enumerated string

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

Enum Values

customer

Customer initiated 3DS payment

merchant

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

authorization_reason

optional, enumerated string

Type of authorization transaction.

Enum Values

blocking_funds

The transaction has been created to block the funds from payment method.

verification

The transaction has been created for payment method verification.

scheduled_capture

The transaction was authorized in advance for capture at a later time by a scheduled system job. The capture may succeed or fail, and its outcome is recorded as a linked transaction under linked_payments .

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

required, 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

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

linked_credit_notes

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

linked_refunds

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

The list of payments captured for this authorization transaction.

error_detail

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