A record that includes all details of a transaction, including current status.

Returned within a successful result object from the following requests:

Attributes
add_ons
Array of AddOn objects

The collection of add-ons associated with a subscription.

additional_processor_response
str

Optional additional processor response information, provided as further context for the primary processor response.

amount
Decimal

The billing amount of the request.

apple_pay

If payment_instrument_type is "apple_pay_card", these are the details of the credit card used for the transaction.

card_type
str

The type of the credit card. Possible values:

  • Apple Pay - Visa
  • Apple Pay - MasterCard
  • Apple Pay - American Express
  • Apple Pay - Discover
cardholder_name
str

The cardholder name associated with the credit card.

expiration_month
str

The expiration month of the credit card, formatted MM.

expiration_year
str

The four-digit expiration year of the credit card, formatted YYYY.

last_4
str

The last 4 digits of the device-specific account number (DPAN).

payment_instrument_name
str

A description of the payment method intended for display to the user, typically card type and last 4 digits of the physical card number stored by Passbook. Braintree receives this description alongside the DPAN when processing an Apple Pay transaction.

source_description
str

Indicates what type of payment method was tokenized by the network. Also includes an identifier for the account (e.g. last 4 digits if the payment method was a credit card).

token
str

An alphanumeric value that references a specific payment method stored in your Vault. Value will be nil if the transaction was not created from a vaulted Apple Pay card.

avs_error_response_code

This field is populated if there was an error when checking AVS or the processing bank does not support AVS. Possible values:

  • S = Issuing bank does not support AVS
  • E = AVS system error


If this value is none, you will see responses in both avs_postal_code_response_code and avs_street_address_response_code.

avs_postal_code_response_code

This is populated if the processor supports the address verification system (AVS). Possible values:

  • M = Matches
  • N = Does not match
  • U = Not verified
  • I = Not provided
  • A = Not applicable
avs_street_address_response_code

This is populated if the processor supports the address verification system (AVS). Possible values:

  • M = Matches
  • N = Does not match
  • U = Not verified
  • I = Not provided
  • A = Not applicable
billing_details

The billing address details used to process this transaction. If billing address was stored in the Vault, then the billing_details is a snapshot of the address in the Vault at the time the transaction was created.

company
str

The billing company name. See the transaction API requests section for details.

country_code_alpha2
str

The 2-letter billing country code. See the transaction API requests section for details.

country_code_alpha3
str

The 3-letter billing country code. See the transaction API requests section for details.

country_code_numeric
str

The numeric billing country code. See the transaction API requests section for details.

country_name
str

The billing country name. See the transaction API requests section for details.

extended_address
str

The extended billing address. See the transaction API requests section for details.

first_name
str

The first name. See the transaction API requests section for details.

id
str

The billing details ID. A customer Vault record can contain up to 50 shipping and billing addresses, each with a unique ID. See the transaction API requests section for details.

last_name
str

The last name. See the transaction API requests section for details.

locality
str

The locality/city. See the transaction API requests section for details.

postal_code
str

The postal code. See the transaction API requests section for details.

region
str

The state or province. See the transaction API requests section for details.

street_address
str

The street address. See the transaction API requests section for details.

channel
str

If the transaction request was created through a shopping cart provider or Braintree Partner, this field will have a string identifier for that shopping cart provider or Partner. For PayPal transactions, this maps to the PayPal account's bn_code.

created_at
datetime

The date/time the object was created.

credit_card_details

The credit card details used to process this transaction. If the transaction was created using Vault tokens, then this attribute is a snapshot of the credit card in the Vault at the time the transaction was created.

bin

The first 6 digits of the credit card, known as the Bank Identification Number.

card_type

The type of the credit card. Possible values:

  • American Express
  • Carte Blanche
  • China UnionPay
  • Diners Club
  • Discover
  • JCB
  • Laser
  • Maestro
  • MasterCard
  • Solo
  • Switch
  • Visa
  • Unknown
cardholder_name
str

The cardholder name associated with the credit card.

commercial
enum

Whether the card type is a commercial card and is capable of processing Level 2 transactions. Possible values:

  • CreditCard.Commercial.Yes
  • CreditCard.Commercial.No
  • CreditCard.Commercial.Unknown
country_of_issuance
str

The country that issued the credit card. Possible country values follow ISO 3166-1.

customer_location

This is "US" if the billing address is in the US or if a country is not specified. The location is "International" if the billing country passed is not the US.

debit
enum

Whether the card is a debit card. Possible values:

  • CreditCard.Debit.Yes
  • CreditCard.Debit.No
  • CreditCard.Debit.Unknown
durbin_regulated
enum

A value indicating whether the issuing bank's card range is regulated by the Durbin Amendment due to the bank's assets. Possible values:

  • CreditCard.DurbinRegulated.Yes
  • CreditCard.DurbinRegulated.No
  • CreditCard.DurbinRegulated.Unknown
expiration_date
str

The expiration date, formatted MMYY or MMYYYY. May be used instead of expiration_month and expiration_year.

expiration_month
str

The expiration month of the credit card used, formatted MM.

expiration_year
str

The expiration year of the credit card used, formatted YYYY.

healthcare
enum

Whether the card is a healthcare card. Possible values:

  • CreditCard.HealthCare.Yes
  • CreditCard.HealthCare.No
  • CreditCard.HealthCare.Unknown
image_url

A URL that points to an image resource (a PNG file) hosted by Braintree, which represents the issuing card network (Visa, MasterCard, American Express, Discover, JCB).

issuing_bank
str

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

A value comprised of the bank identification number (BIN), 6 asterisks blocking out the middle numbers (regardless of the number of digits present), and the last 4 digits of the card number. This complies with PCI security standards.

payroll
enum

Whether the card is a payroll card. Possible values:

  • CreditCard.Payroll.Yes
  • CreditCard.Payroll.No
  • CreditCard.Payroll.Unknown
prepaid
enum

Whether the card is a prepaid card. Possible values:

  • CreditCard.Prepaid.Yes
  • CreditCard.Prepaid.No
  • CreditCard.Prepaid.Unknown
token
str

The Vault token for the credit card. This attribute is not a snapshot. If you update the payment method token after creating a transaction, credit_card_details.token attribute will return the new value rather than the value associated with the transaction at the time it was created. See the transaction API requests section for additional details.

unique_number_identifier

A randomly-generated string that uniquely identifies a credit card number in the Vault. If the same credit card is added to a merchant's Vault multiple times, each Vault entry will have the same unique identifier. This value is randomly generated by merchant gateway account, so it will be different for each merchant's Vault.

currency_iso_code

The currency for the transaction (e.g. "USD" for US dollars). See the ISO 4217 codes.

custom_fields

A collection of custom field/value pairs.

customer_details

The customer details used to process this transaction. If the transaction was created using Vault tokens, then the customer_details is a snapshot of the customer in the Vault at the time the transaction was created.

company
str

The customer company name. See the transaction API requests section for details.

email
str

The email address. See the transaction API requests section for details.

fax
str

The customer fax number. See the transaction API requests section for details.

first_name
str

The first name. See the transaction API requests section for details.

id
str

Reference value that is associated with the customer's id at the time of the transaction.

last_name
str

The last name. See the transaction API requests section for details.

phone
str

The customer phone number. See the transaction API requests section for details.

website
str

The customer website address. See the transaction API requests section for details.

cvv_response_code

The processing bank's response to the card verification value (CVV) provided by the customer. Possible values:

  • M = Matches
  • N = Does not match
  • U = Not verified
  • I = Not provided
  • S = Issuer does not participate
  • A = Not applicable
descriptor
name
str

The value in the business name field of a customer's statement.

phone
str

The value in the phone number field of a customer's statement.

url
str

The value in the URL/web address field of a customer's statement.

disbursement_details

Disbursement details contain information about how and when the transaction was disbursed, including timing and currency information. This detail is only available if you have an eligible merchant account.

disbursement_date

The date that the funds associated with this transaction were disbursed. This attribute is only available if you have an eligible merchant account.

funds_held
bool

A value indicating whether funds have been withheld from a disbursement to the merchant's bank account.

settlement_amount
Decimal

The amount of the transaction in the settlement currency. This attribute is only available if you have an eligible merchant account.

settlement_currency_exchange_rate

The exchange rate from the presentment currency to the settlement currency. This attribute is only available if you have an eligible merchant account.

settlement_currency_iso_code

The settlement currency. See the ISO 4217 codes. This attribute is only available if you have an eligible merchant account.

success

A value indicating whether the funds were disbursed successfully. This value can change over time if we receive an exception and then retry the disbursement. This attribute is only available on eligible merchant accounts.

Some of the most common reasons that funds are held from disbursement are risk reviews of the merchant's recent processing or as a result of ACH returns or rejects. If funds are held (for any reason) you will be notified with the proper steps to take by the appropriate team within Braintree.

discounts
Array of Discount objects

A collection of discounts associated with this subscription.

disputes

A collection of disputes associated with the transaction.

  • dispute.amount - Amount customer requested when disputing the transaction. This can be any amount up to the full amount of the original transaction.
  • dispute.currency_iso_code - The currency of the amount.
  • dispute.date_opened - The date the dispute was opened.
  • dispute.date_won - The date the dispute was won. Only available on disputes that were won.
  • dispute.id - A unique ID for each dispute.
  • dispute.kind - The kind of dispute. Possible values: chargeback, pre_arbitration, retrieval. For more information see the article on dispute kinds.
  • dispute.received_date - The date we received the dispute.
  • dispute.reply_by_date - The date a reply with evidence is due.
  • dispute.reason - The reason the dispute was created. Possible values:
    • cancelled_recurring_transaction - The cardholder was billed for a recurring charge they canceled or attempted to cancel.
    • credit_not_processed - The cardholder was told they were to receive a credit and did not.
    • duplicate - The individual charge was submitted more than once.
    • fraud - The cardholder is claiming this transaction to be fraudulent.
    • general - A generic response was provided by the card-issuing bank.
    • invalid_account - Card was expired, had an invalid account number, or had an account number that did not match the card number of the original transaction.
    • not_recognized - The cardholder claims they do not recognize/did not participate in this charge.
    • product_not_received - The cardholder did not receive (or only partially received) the goods/services they paid for.
    • product_unsatisfactory - The cardholder received the goods/services, but the product was defective, different than described, or otherwise did not meet expectations.
    • transaction_amount_differs - The cardholder claims the charge the merchant submitted was different than what the cardholder agreed to pay.
  • dispute.status - The latest status of the dispute. Possible values:
    • open - Dispute has been opened by the customer and funds have been debited from your account
    • lost - The bank has reviewed evidence and declined to reverse the dispute or you didn't provide evidence
    • won - The bank has reversed the dispute and funds have been credited to your account
escrow_status

This attribute is only available to Braintree Marketplace merchants. See Holding Funds in Escrow to learn more. Possible values:

  • "hold_pending"
  • "held"
  • "release_pending"
  • "released"
  • "refunded"
gateway_rejection_reason

This value will only be set if the transaction status is gateway_rejected. Possible values:

  • "avs"
  • "avs_and_cvv"
  • "cvv"
  • "duplicate"
  • "fraud"
  • "three_d_secure"
  • "application_incomplete"
merchant_account_id
str

The merchant account ID used to create a transaction. Currency is also determined by merchant account ID.

order_id
str

The order ID of the transaction. On PayPal transactions, this field maps to the PayPal invoice ID. PayPal invoice IDs are unique in your PayPal business account.

payment_instrument_type

The method of payment used to process the transaction. Possible values:

  • "credit_card"
  • "paypal_account"
  • "apple_pay_card"
  • "coinbase_account"
  • "venmo_account"
  • "android_pay_card"
paypal_details
authorization_id
str

The identification value of the authorization within PayPal's API.

capture_id
str

PayPal id for a transaction.

custom_field
str

Custom field/value pairs.

image_url
str

A URL that points to a PayPal image resource (a PNG file) hosted by Braintree.

payer_email
str

The email address associated with the PayPal account that was used to create the request. This field will not be populated if the PayPal transaction declines and the payment method was not previously stored in the Vault.

payer_first_name
str

The first name associated with the PayPal account used to create the request.

payer_id
str

The identifier for the PayPal account used in the request.

payer_last_name
str

The last name associated with the PayPal account used to create the request.

payment_id
str

The identification value of the payment within PayPal's API.

refund_id
str

PayPal id for a refund.

seller_protection_status
str

Indicates whether a transaction qualifies for PayPal Seller Protection.

tax_id
str

Payer's tax id. Only returned for payments from Brazilian accounts.

tax_id_type
str

Payer's tax id type. Only returned for payments from Brazilian accounts. Allowed values BR_CPF or BR_CNPJ.

token
str

An alphanumeric value that references a specific payment method stored in your Vault. Length and format of gateway-generated tokens and IDs may change at any time.

transaction_fee_amount
str

The transaction fee amount of the PayPal transaction.

A transaction fee of 1 will always be returned in sandbox integrations.

transaction_fee_currency_iso_code
str

The currency of the associated transaction fee.

plan_id
str

The plan identifier.

processor_authorization_code

The authorization code returned by the processor.

processor_response_code
str

The processor response code. See the list of possible processor authorization responses.

processor_response_text
str

The processor response text. See the list of possible processor authorization responses.

processor_settlement_response_code
str

The status of the request to capture the funds. See the list of possible processor settlement responses.

processor_settlement_response_text
str

The text explanation of the above processor settlement response code.

purchase_order_number
str

A Level II data field that can be used to store a purchase order identification value.

recurring

A value indicating whether the transaction was passed with a recurring e-commerce indicator (ECI) flag.

refund_ids

The transaction refund ID(s) associated with a sale transaction. See the transaction API requests section for details.

refunded_transaction_id
str

The sale transaction ID associated with a refund transaction. See the transaction API requests section for details.

risk_data

Risk data on credit card transactions. The data includes the risk identifier and the risk decision, which can provide further context on how a transaction was scored by Braintree.

decision
str

The risk decision. Possible values:

  • Not Evaluated
  • Approve
  • Review
  • Decline
id
str

The risk data identifier.

service_fee_amount
Decimal

The portion of a sub-merchant's transaction revenue that was routed to the master merchant account.

Available to Braintree Marketplace merchants and Partners. See Service Fee for more details.

settlement_batch_id
str

The identification value of the settlement batch in which the transaction was processed. The format may change at any time but is currently YYYY-MM-DD_md where m is the merchant account token without special characters and d is an optional digit to guarantee uniqueness.

shipping_details

The shipping address details used to process this transaction. If shipping address was stored in the Vault, then the shipping_details is a snapshot of the address in the Vault at the time the transaction was created.

company
str

The shipping company name. See the transaction API requests section for details.

country_code_alpha2
str

The 2-letter shipping country code. See the transaction API requests section for details.

country_code_alpha3
str

The 3-letter shipping country code. See the transaction API requests section for details.

country_code_numeric
str

The numeric shipping country code. See the transaction API requests section for details.

country_name
str

The shipping country name. See the transaction API requests section for details.

extended_address
str

The extended shipping address. See the transaction API requests section for details.

first_name
str

The first name. See the transaction API requests section for details.

id
str

The shipping details ID. A customer Vault record can contain up to 50 shipping and billing addresses, each with a unique ID. See the transaction API requests section for details.

last_name
str

The last name. See the transaction API requests section for details.

locality
str

The locality/city. See the transaction API requests section for details.

postal_code
str

The postal code. See the transaction API requests section for details.

region
str

The state or province. See the transaction API requests section for details.

street_address
str

The street address. See the transaction API requests section for details.

status
str

Possible values:

  • "authorization_expired"
  • "authorized"
  • "authorizing"
  • "settlement_pending"
  • "settlement_confirmed"
  • "settlement_declined"
  • "failed"
  • "gateway_rejected"
  • "processor_declined"
  • "settled"
  • "settling"
  • "submitted_for_settlement"
  • "voided"

See the transaction status explanations for details.

status_history

This value is a record of the statuses that a transaction has progressed through. Possible values:

  • "authorization_expired"
  • "authorized"
  • "authorizing"
  • "settlement_pending"
  • "settlement_confirmed"
  • "settlement_declined"
  • "failed"
  • "gateway_rejected"
  • "processor_declined"
  • "settled"
  • "settling"
  • "submitted_for_settlement"
  • "voided"
subscription_details
billing_period_end_date

The end date for the current billing period, regardless of subscription status. Automatic retries on past due subscriptions do not change the start and end dates of the current billing period.

billing_period_start_date

The start date for the current billing period, regardless of subscription status. Automatic retries on past due subscriptions do not change the start and end dates of the current billing period.

subscription_id
str

The value used to identify a specific subscription.

tax_amount
Decimal

A Level II data field that specifies the amount of tax that was included in the total transaction amount. It is never negative, and it does not add to the total transaction amount.

tax_exempt
bool

A Level II data field that indicates whether or not the transaction should be considered eligible for tax exemption. This does not affect the total transaction amount.

three_d_secure_info

The 3D Secure information for this transaction.

enrolled
str

Indicates whether a card is enrolled in a 3D Secure program or not. Possible values:

  • Y = Yes
  • N = No
  • U = Unavailable
  • B = Bypass
  • E = RequestFailure
liability_shift_possible
bool

Indicates whether a liability shift is possible.

liability_shifted
bool

Indicates whether the liability shifted or not.

status
str

The 3D Secure status value. For a list of all possible statuses and their liability shifts, see the 3D Secure guide.

type
str

The value that defines whether a transaction is a sale or credit.

updated_at
datetime

The date/time the object was last updated.

voice_referral_number

The value passed by the merchant with a voice-authorized transaction.

Result object

Read more about result objects.

Successful result

If the result is successful, the transaction will have either an authorized status, or (if the options.submit_for_settlement option was used) a submitted for settlement status.

Python
result.is_success
# True

transaction = result.transaction
transaction.status
# "authorized"

Additionally, you may inspect the result to determine if the transaction was created using a specific payment method type (e.g. PayPal account or a credit card), using the provided format.

Python
transaction = result.transaction
transaction.payment_instrument_type == braintree.PaymentInstrumentType.PayPalAccount
# False
transaction.payment_instrument_type == braintree.PaymentInstrumentType.CreditCard
# True

Unsuccessful result

Success will return False if:

Python
result.is_success
# False

result.errors.deep_errors

Validation errors

If any parameters are invalid, then the success call will return False and the result object will contain one or more validation errors indicating which parameters were invalid.

When receiving a validation error, a Transaction object will not be present on the result object.

Processor declined

If the processor declines the transaction during the authorization, the processor response will be available on the transaction object.

Python
result.is_success
# false

result.transaction.status
# "processor_declined"

result.transaction.processor_response_code
# e.g. "2001"

result.transaction.processor_response_text
# e.g. "Insufficient Funds"

As a supplement to the standardized processor response codes, we will return bank-specific Additional Processor Responses on the transaction object. The standardized code is what you should use when handling the result object, but the Additional Processor Response might provide further context.

Python
result.transaction.additional_processor_response
# e.g. "05 : NOT AUTHORISED"

Processor settlement declined

If the processor declines the transaction at the settlement stage, the processor response will be available on the transaction object.

Python
result.is_success
# false

result.transaction.status
# "settlement_declined"

result.transaction.processor_settlement_response_code
# e.g. "4001"

result.transaction.processor_settlement_response_text
# e.g. "Settlement Declined"

Gateway rejection

If the transaction is rejected by the gateway based on your account settings, you can check for the transaction status and gateway rejection reason.

Python
result.is_success
# false

result.transaction.status
# "gateway_rejected"

result.transaction.gateway_rejection_reason
# e.g. "cvv"

Risk data

We will also return the risk data on all credit card transactions. The data includes the risk identifier and the risk decision, which can provide further context on how a transaction was scored by Braintree.

Python
result.transaction.risk_data.id
# "1SG23YHM4BT5"
result.transaction.risk_data.decision
# "Decline"

The possible values of the risk decision are:

  • "Not Evaluated"
  • "Approve"
  • "Review"
  • "Decline"

Params retrieval

See our documentation on result objects.

Examples

Currencies

Each merchant account can only process transactions for a single currency. Setting which merchant account to use will also determine which currency the transaction is processed with.

Python
result.transaction.currency_iso_code
# USD

Settlement status

Check the result for success, and if it has failed, then first check for validation errors. If there are no validation errors, inspect the processor_settlement_response_code on the transaction, which will indicate if the processor declined the request.

Python
if result.is_success:
  # transaction successfully submitted for settlement
elif result.errors.deep_errors:
    print(result.error.deep_errors)
else:
    print(result.transaction.processor_settlement_response_code)
    print(result.transaction.processor_settlement_response_text)

Processor settlement declined

If the settlement request is declined by the processor, the processor response will be available on the transaction object.

Python
result.is_success
# false

result.transaction.status
# "settlement_declined"

result.transaction.processor_settlement_response_code
# e.g. "4001"

result.transaction.processor_settlement_response_text
# e.g. "Settlement Declined"

Voiding settlement

If you submit a transaction for settlement and then decide you actually don't want to settle it, you can void it before it's settled. After it's settled, you'll need to refund it. To check if the transaction has been settled, find the transaction and check the status.

Python
transaction = braintree.Transaction.find("the_transaction_id")
if transaction.status == braintree.Transaction.Status.SubmittedForSettlement:
    # can void
elif transaction.status == braintree.Transaction.Status.Settled:
    # will have to refund it
else:
    # this example only expected one of the two above statuses

See also

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or email our Support team.