Transaction

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

Server-side response object returned directly or within a successful result object from the following requests:
`Transaction: Adjust Authorization`
`Transaction: Cancel Release`
`Transaction: Find`
`Transaction: Hold In Escrow`
`Transaction: Refund`
`Transaction: Release From Escrow`
`Transaction: Sale`
`Transaction: Search`
`Transaction: Submit For Partial Settlement`
`Transaction: Submit For Settlement`
`Transaction: Void`
`Transaction: Clone Transaction`

Attributes

ach_return_codeString

Optional field that is added to a transaction if parsing an ACH transaction with a return via webhook.

acquirer_reference_numberString

A unique number that tags a credit or debit card transaction when it goes from the merchant’s bank through to the cardholder's bank. Also called a Trace ID, this number is often used to determine where a transaction's funds lie at a certain time. Learn more about Trace IDs here.

add_onsarray

The collection of add-ons associated with a subscription.

additional_processor_responseString

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

amountBigDecimal

The billing amount of the request.

google_pay_detailsobj

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

binString

The first 6 digits of the card number, also known as the Bank Identification Number (BIN). If this Google Pay card is network tokenized, its BIN may differ from the BIN of the underlying source card.

commercialenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

debitenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

durbin_regulatedenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

expiration_monthString

The expiration month of the credit card, formatted MM.

expiration_yearString

The 2- or 4-digit year associated with the credit card, formatted YY or YYYY.

google_transaction_idString

A unique identifier provided by Google to track the payment method's transactions.

healthcareenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

image_urlString

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

is_network_tokenized?bool

Indicates whether this card has been network tokenized. A network tokenized card is a generated virtual card with a device-specific account number (DPAN) that is used in place of the underlying source card.

payrollenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

prepaidenum

If payment_instrument_type is android_pay_card, these are the details of the card used for the transaction.

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

source_card_last_4String

The last 4 digits of the card number. If this card is network tokenized, this is the last 4 digits of the customer's actual card.

source_card_typeString

The card type. If this card is network tokenized, this is the card type of the customer's actual card.

source_descriptionString

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

tokenString

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 Android Pay card.

virtual_card_last_4String

The last 4 digits of the card number. If this card is network tokenized, this is the last 4 digits of the device-specific account number (DPAN).

virtual_card_typeString

The card type. If this card is network tokenized, this is the card type of the network tokenized card.

apple_pay_detailsobj

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

binString

The first 6 digits of the device-specific account number (DPAN), known as the Bank Identification Number. This BIN may differ from the BIN of the underlying card.

card_typeString

The type of the credit card. Possible values:

Apple Pay - Visa
Apple Pay - MasterCard
Apple Pay - American Express
Apple Pay - Discover

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

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

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

debitenum

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

durbin_regulatedenum

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

expiration_monthString

The expiration month of the credit card, formatted MM.

expiration_yearString

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

healthcareenum

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

image_urlString

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

issuing_bankString

The bank that issued the credit card.

last_4String

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

merchant_token_identifierString

A unique identifier of the merchant token for Apple Pay MPAN cards.

payment_instrument_nameString

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 Wallet (formerly Passbook). We receive this description alongside the DPAN when processing an Apple Pay transaction.

payrollenum

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

prepaidenum

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

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

source_card_last4String

The last 4 digits of the physical card number (FPAN).

source_descriptionString

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

tokenString

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.

authorization_adjustments

A collection of authorization adjustments associated with the transaction.

authorization_expires_atTime

The date/time the transaction will expire if it has the authorized status. For more details on authorization expiration timeframes, see the Statuses reference. Returned in UTC.

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 nil, 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
B = Bypass

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
B = Bypass

billing_detailsmap

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

companyString

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

country_code_alpha2String

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

country_code_alpha3String

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

country_code_numericString

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

country_nameString

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

extended_addressString

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

first_nameString

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

idString

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.

international_phonemap

The phone number that belongs to the address that is structured with country code and national number.

country_codeString

Country code of phone number. 1-3 digits. Required.

national_numberString

National number of phone number. 4-12 digits. Required.

last_nameString

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

localityString

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

phone_numberString

Deprecated.

We recommend using international_phone. This functionality still exists in the gateway but is no longer documented. This parameter will be removed in the future.

postal_codeString

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

regionString

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

street_addressString

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

channelString

If the transaction request was performed 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_atTime

The date/time the object was created. Returned in UTC.

credit_card_detailsmap

If payment_instrument_type is credit_card, these are the details of the card used for the 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 (BIN).

card_type

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

customer_locationenum

debitenum

durbin_regulatedenum

expiration_dateString

The expiration date, formatted MM/YY or MM/YYYY. May be used instead of expiration month and expiration year.

expiration_monthString

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

expiration_yearString

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

healthcareenum

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_bankString

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

A value comprising 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.

payment_reader_attributesmap

If the transaction was carried out at a physical store location with a payment reader, these are the details of the cardholder's interaction with the payment reader.

application_cryptogramString

The cryptogram provided by an integrated circuit card (ICC) used for processing the transaction. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

application_identifierString

The application identifier (AID) value returned by a payment reader that is used to identify the kind of card used to process a transaction.

application_interchange_profileString

An indicator of the credit card's capabilities within the processing application. This field is required to be included on an in-store transaction receipt that was offline declined by the issuer.

application_nameString

A value returned by a payment reader that represents the preferred mnemonic associated with the application identifier (AID). This field is required to be included on an in-store transaction receipt.

application_transaction_counterString

A counter managed by an integrated circuit card (ICC) that provides a reference to each transaction using that card. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

application_usage_controlString

An indicator used to specify an issuer's restrictions for processing in a geographic region. This field is required to be included on an in-store transaction receipt that was offline declined by the issuer.

authorization_mode

Whether the transaction was authorized by an integrated circuit card (ICC) or by the issuing bank. This field is required to be included on an in-store transaction receipt. Possible values:

Issuer
Card

authorization_response_codeString

The authorization code received from the processor in response to an authorization request. This field is required to be included on an in-store transaction receipt.

card_entry_methodString

The card entry method that was used by the cardholder to initiate the transaction at the payment reader. This field is required to be included on an in-store transaction receipt.

card_sequence_numberString

The sequence number of the card, which is a unique identifier for credit cards that share the same PAN. This field is required to be included on an in-store transaction receipt that was offline declined by the issuer.

cardholder_verification_method_resultsString

An indicator of the cardholder verification method and if it was successful or unsuccessful. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

cashback_amountString

An additional amount associated with the transaction that represents the cashback amount requested by the cardholder. This field is required to be included on an in-store transaction receipt that was offline declined by the issuer.

cryptogram_information_dataString

An indicator for the type of application cryptogram provided by an integrated circuit card (ICC) to process the transaction. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

issuer_action_code_defaultString

Specifies the conditions that caused the transaction to be offline declined by the issuer, in a scenario where the transaction may have authorized if the payment reader made a processor request but was unable to. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

issuer_action_code_denialString

Specifies the conditions that caused the transaction to be offline declined by the issuer, in a scenario where the payment reader did not attempt to make a processor request. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

issuer_action_code_onlineString

Specifies the conditions that caused the payment reader to attempt to make a processor request. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

issuer_authentication_dataString

Authentication data returned by the issuer in response to an authorization request. This field is required to be included on an in-store transaction receipt.

terminal_country_codeString

The country code that the payment reader should process the transaction with. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_transaction_dateString

The local date that the transaction requested authorization from the payment reader. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_transaction_typeString

An indicator of the type of transaction specified during authorization processing. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_verification_resultString

A value returned by a payment reader that represents the status of a series of validations against an EMV enabled credit card. This field is required to be included on an in-store transaction receipt.

unpredictable_numberString

A value used to uniquely differentiate an application cryptogram used during authorization processing. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

payrollenum

prepaidenum

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

tokenString

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_fieldsobj

A collection of custom field/value pairs.

customer_detailsmap

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

companyString

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

emailString

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

faxString

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

first_nameString

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

idString

international_phonemap

The phone number that belongs to the address that is structured with country code and national number.

country_codeString

Country code of phone number. 1-3 digits. Required.

national_numberString

National number of phone number. 4-12 digits. Required.

last_nameString

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

phoneString

Deprecated.

We recommend using international_phone. This functionality still exists in the gateway but is no longer documented. This parameter will be removed in the future.

websiteString

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
B = Bypass

descriptormap

nameString

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

phoneString

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

urlString

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

disbursement_detailsmap

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_amountBigDecimal

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

settlement_base_currency_exchange_rate

The base exchange rate from the presentment currency to 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.

discount_amountBigDecimal

The data field that specifies the discount amount that was included in the total transaction amount. It can't be negative, and it does not add to the total transaction amount. If Braintree has approved your merchant account for Level 3 processing, we will pass this field to the processor on your behalf. This Braintree line-item field is not used by PayPal.

discountsarray

A collection of discounts associated with this subscription.

disputesarray

A collection of disputes associated with the transaction.

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

facilitated_detailsmap

If the transaction request was performed using payment information from a third party via the Grant API or Shared Vault, these fields will capture information about the merchant of record. These fields are primarily useful for the third party.

merchant_idString

The merchant ID of the merchant of record.

merchant_nameString

The name of the business associated with the merchant of record.

payment_method_nonceString

facilitator_detailsmap

If the transaction request was performed using payment information from a third party via the Grant API, Shared Vault or Google Pay, these fields will capture information about the third party. These fields are primarily useful for the merchant of record.

oauth_application_client_idString

The unique identifier for the OAuth application that owns the payment information used to create the transaction.

oauth_application_nameString

The display name of the OAuth application that owns the payment information used to create the transaction.

source_payment_method_tokenString

The alphanumeric value that references a specific payment method stored in the facilitator's Vault.

gateway_rejection_reason

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

"application_incomplete"
"avs"
"avs_and_cvv"
"cvv"
"duplicate"
"fraud"
"risk_threshold"
"three_d_secure"
"token_issuance"

graphql_idString

The unique identifier used to identify this transaction in Braintree's GraphQL API.

idString

The unique transaction identifier. Length and format of gateway-generated tokens and IDs may change at any time.

line_items

A collection of line items associated with the transaction.

local_payment_detailsmap

If payment_instrument_type is local_payment, these are the details used for the transaction.

custom_fieldString

The PayPal Order's custom ID. This caller-provided ID is used to reconcile client transactions with PayPal transactions. It appears in transaction and settlement reports but is not visible to the payer.

descriptionString

The PayPal Order's purchase description.

funding_sourceString

The local bank used to fund the transaction.

implicitly_vaulted_payment_method_global_idString

The payment method global id that is returned from a one-time PayPal transaction with recurrent option.

implicitly_vaulted_payment_method_tokenString

The payment method token that is returned from a one-time PayPal transaction with recurrent option.

payer_idString

The identifier for the payer in the request.

payment_idString

The PayPal Order ID associated with the transaction.

transaction_fee_amountString

The transaction fee amount of the PayPal transaction.

transaction_fee_currency_iso_codeString

The transaction fee currency code of the PayPal transaction.

master_merchant_account_idString

This functionality still exists in the gateway but is no longer documented. Will remove this param/attr when the corresponding gateway code is removed. Old description – The master merchant account ID used to create a transaction.

masterpass_card_detailsmap

If payment_instrument_type is masterpass_card, these are the details of the card used for the transaction. If the transaction was created using Vault tokens, then this attribute is a snapshot of the Masterpass 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 (BIN).

card_type

The type of the credit card. Possible values:

American Express
Discover
JCB
Maestro
MasterCard
Visa

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

customer_locationenum

debitenum

durbin_regulatedenum

expiration_dateString

The expiration date, formatted MM/YY or MM/YYYY. May be used instead of expiration month and expiration year.

expiration_monthString

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

expiration_yearString

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

healthcareenum

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

is_network_tokenized?bool

issuing_bankString

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

payrollenum

prepaidenum

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

tokenString

merchant_account_idString

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

merchant_addressmap

The merchant address details used to process this transaction. These details are required to be included on an in-store transaction receipt.

localityString

The locality/city.

phoneString

The phone number.

postal_codeString

The postal code.

regionString

The state or province.

street_addressString

The street address.

merchant_advice_codeString

The merchant advice code. When present, this field can provide additional detail about why a recurring payment transaction was declined, and the actions merchants can take to continue to serve their recurring payment customers. See the list of possible network responses.

merchant_advice_code_textString

The merchant advice code text for the merchant_advice_code.

merchant_identification_numberString

The merchant ID that is registered with the acquiring bank. This field is required to be included on an in-store transaction receipt.

merchant_nameString

The display name of the merchant. This field is required to be included on an in-store transaction receipt.

network_response_codeString

The network response code. When present, this field can provide additional detail about why a transaction was declined, but the processor_response_code should be considered the source of truth. See the list of possible network responses.

network_response_textString

The network response text for the network_response_code.

network_tokenmap

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

bin

The first 6 digits of the credit card, known as the bank identification number (BIN).

card_type

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

customer_locationenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

debitenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

durbin_regulatedenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

expiration_dateString

The expiration date, formatted MM/YY or MM/YYYY. May be used instead of expiration month and expiration year.

expiration_monthString

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

expiration_yearString

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

healthcareenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

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

is_network_tokenized?bool

issuing_bankString

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

payrollenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

prepaidenum

If payment_instrument_type is network_token, these are the details of the token used for the transaction.

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

network_transaction_idString

The network transaction identifier provided by the payment network. This should be provided in requests to create subsequent transactions if the card used in this transaction is being stored in an external vault. This identifier can be passed in the external_vault.previous_network_transaction_id field of subsequent transactions.

order_idString

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

payment_instrument_type

payment_receiptmap

Transaction receipt data.

account_balanceBigDecimal

The remaining balance amount on a credit or debit card after it was used to process the transaction.

amountBigDecimal

The billing amount of the request.

card_last_4String

The last 4 digits of the credit card number.

card_present_datamap

Card present details.

application_cryptogramString

application_identifierString

The application identifier (AID) value returned by a payment reader that is used to identify the kind of card used to process a transaction.

application_interchange_profileString

An indicator of the credit card's capabilities within the processing application. This field is required to be included on an in-store transaction receipt that was offline declined by the issuer.

application_nameString

A value returned by a payment reader that represents the preferred mnemonic associated with the application identifier (AID). This field is required to be included on an in-store transaction receipt.

application_transaction_counterString

application_usage_controlString

authorization_mode

Whether the transaction was authorized by an integrated circuit card (ICC) or by the issuing bank. This field is required to be included on an in-store transaction receipt. Possible values:

Issuer
Card

authorization_response_codeString

The authorization code received from the processor in response to an authorization request. This field is required to be included on an in-store transaction receipt.

card_entry_methodString

The card entry method that was used by the cardholder to initiate the transaction at the payment reader. This field is required to be included on an in-store transaction receipt.

card_sequence_numberString

cardholder_verification_method_resultsString

cashback_amountString

cryptogram_information_dataString

issuer_action_code_defaultString

issuer_action_code_denialString

issuer_action_code_onlineString

issuer_authentication_dataString

Authentication data returned by the issuer in response to an authorization request. This field is required to be included on an in-store transaction receipt.

terminal_country_codeString

The country code that the payment reader should process the transaction with. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_transaction_dateString

The local date that the transaction requested authorization from the payment reader. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_transaction_typeString

An indicator of the type of transaction specified during authorization processing. This field is required to be included on an in-store transaction receipt on an offline declined transaction.

terminal_verification_resultString

unpredictable_numberString

card_typeString

The credit card type.

currency_iso_codeString

The ISO code for the currency the merchant account uses. See the ISO 4217 codes.

global_idString

The unique transaction global ID.

idString

The unique transaction identifier. Length and format of gateway-generated tokens and IDs may change at any time.

merchant_addressmap

The merchant address details used to process this transaction. These details are required to be included on an in-store transaction receipt.

localityString

The locality/city.

phoneString

The phone number.

postal_codeString

The postal code.

regionString

The state or province.

street_addressString

The street address.

merchant_identification_numberString

The merchant ID that is registered with the acquiring bank. This field is required to be included on an in-store transaction receipt.

merchant_nameString

The name of the business associated with the merchant of record.

pin_verifiedbool

An indicator for whether the transaction was successfully verified by PIN. This field is required to be included on an in-store transaction receipt.

processor_authorization_codeString

The authorization code returned by the processor.

processor_response_codeString

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

processor_response_textString

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

terminal_identification_numberString

The terminal ID that was used for processing the transaction. This field is required to be included on an in-store transaction receipt.

typeString

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

paypal_detailsmap

If payment_instrument_type is paypal_account, these are the details of the PayPal account used for the transaction.

authorization_idString

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

capture_idString

PayPal id for a transaction.

custom_fieldString

Custom field/value pairs.

image_urlString

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

implicitly_vaulted_payment_method_global_idString

The payment method global id that is returned from a one-time PayPal transaction with billing agreement creation.

implicitly_vaulted_payment_method_tokenString

The payment method token that is returned from a one-time PayPal transaction with billing agreement creation.

payer_emailString

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_nameString

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

payer_idString

The identifier for the PayPal account used in the request.

payer_last_nameString

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

payer_phoneString

The primary phone number of the PayPal account used to create the request.

payer_statusString

The status of the PayPal account used to create the request.

payment_idString

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

refund_descriptionString

The description of the refund transaction. On PayPal transactions, this field maps to the PayPal refund description.

refund_from_transaction_fee_amountString

The refund from the transaction fee amount of the PayPal transaction.

A refund from transaction fee of 1 will always be returned for sandbox integrations.

refund_from_transaction_fee_currency_iso_codeString

The currency of the associated refund from the transaction fee.

refund_idString

PayPal id for a refund.

refund_reasonString

The reason of the refund transaction. On PayPal transactions, this field maps to the PayPal refund reason.

selected_financing_currency_codeString

The currency code for the selected financing option.

selected_financing_discount_amountString

Optional discount amount for the selected financing option.

selected_financing_discount_percentageBigDecimal

Optional discount percentage on interest rates for the selected financing option.

selected_financing_monthly_payment_amountString

The monthly amount to be paid for the selected financing option.

selected_financing_terminteger

The agreed term in months for the selected financing option.

seller_protection_statusString

Indicates whether a transaction qualifies for PayPal Seller Protection.

shipping_option_idString

The identification value of the shipping option selected during PayPal Checkout.

tax_idString

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

tax_id_typeString

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

tokenString

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_amountString

The transaction fee amount of the PayPal transaction.

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

transaction_fee_currency_iso_codeString

The currency of the associated transaction fee.

paypal_here_detailsmap

If payment_instrument_type is paypal_here, these are the details of the PayPal Here payment method used for the transaction. See the PayPal Here guide for details.

authorization_idString

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

capture_idString

PayPal ID for a transaction.

invoice_idString

PayPal ID for the invoice for the transaction.

last_4String

The last 4 digits of the credit card number.

payment_idString

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

payment_typeString

The type of the credit card. Possible values:

A - American Express
D - Discover
J - JCB
T - Maestro
M - MasterCard
V - Visa

refund_idString

PayPal ID for a refund.

transaction_fee_amountobj

The amount of the transaction fee assessed for the PayPal Here transaction.

transaction_fee_currency_iso_codeString

The currency of the associated transaction fee.

transaction_initiation_dateTime

The date/time the transaction was initiated in PayPal systems. Returned in UTC.

transaction_updated_dateTime

The date/time the transaction was last updated in PayPal systems. Returned in UTC.

pin_verifiedbool

An indicator for whether the transaction was successfully verified by PIN. This field is required to be included on an in-store transaction receipt.

plan_idString

The plan identifier.

processed_with_network_token?bool

Indicates whether this transaction has been processed with a network token.

processor_authorization_code

The authorization code returned by the processor.

processor_response_codeString

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

processor_response_textString

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

processor_response_typeString

The processor response type. Possible values:

"approved"
"soft_declined"
"hard_declined"

See the list of possible processor authorization responses, and definitions of soft and hard declines.

processor_settlement_response_codeString

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

processor_settlement_response_textString

The text explanation of the above processor settlement response code.

purchase_order_numberString

A Level 2 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 ecommerce indicator (ECI) flag.

refund_idString

This functionality still exists in the gateway but is no longer documented. Will remove this param/attr when the corresponding gateway code is removed. Old description – The first transaction refund ID.

refund_ids

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

refunded_transaction_idString

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

response_emv_dataString

Response EMV data provided by the processor if this was an EMV transaction.

retried_transaction_idString

The transaction ID of the transaction that was retried.

retrieval_reference_numberString

The string value representing the reference number provided by the processor (if any).

retry_idsmap

An array of transation IDs for all retry attempts for this transaction.

risk_datamap

Any applicable risk data associated with the transaction. The data includes the risk identifier, the device data captured flag, and the risk decision, which can provide further context on how a transaction was scored by Braintree.

decisionString

The risk decision. Possible values:

Not Evaluated
Approve
Review
Decline

decision_reasonsmap

An array of strings containing the rules triggered by the fraud provider when generating the decision.

device_data_capturedbool

Flag indicating whether device session data was successfully captured and processed by the fraud service.

fraud_service_providerString

The fraud service used to determine if a transaction is likely to be fraudulent.

idString

The risk data identifier.

liability_shiftmap

Map to indicate under what circumstances liability for a chargeback has shifted and who is the new responsible party.

conditionsmap

An array of strings containing the conditions under which liability for a chargeback has shifted.

responsible_partyString

The party that is now responsible for the chargeback.

transaction_risk_scoreString

The score returned by the fraud provider as a measurement of the transaction's likelihood for being fraudulent. Only applicable to Fraud Protection Advanced product.

samsung_pay_card_detailsmap

If payment_instrument_type is samsung_pay_card, these are the details of the card used for the transaction. If the transaction was created using Vault tokens, then this attribute is a snapshot of the Samsung Pay 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 (BIN).

card_type

The type of the credit card. Possible values:

American Express
MasterCard
Visa

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

customer_locationenum

debitenum

durbin_regulatedenum

expiration_dateString

The expiration date, formatted MM/YY or MM/YYYY. May be used instead of expiration month and expiration year.

expiration_monthString

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

expiration_yearString

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

healthcareenum

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

is_network_tokenized?bool

issuing_bankString

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

payrollenum

prepaidenum

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

source_card_last_4String

The last 4 digits of the payment method tokenized by the network.

tokenString

sca_exemption_requestedString

If an exemption to the Secure Customer Authentication requirement was requested for this transaction, this value will have the specific reason for the exemption request.

sepa_debit_account_detailobj

If payment_instrument_type is sepa_debit_account, these are the details of the SEPA debit account used for the transaction.

SEPA Direct Debit payments are currently in a limited release and are only available to select merchants. See the SEPA Direct Debit guide for details.

bank_reference_tokenString

The tokenized payment source to fund a payment.

capture_idString

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

last_4String

The last characters of the International Bank Account Number, a unique identifier for a bank account that is used by banks around Europe.

mandate_typeString

Represents the type of mandate. This can be either 'ONE_OFF' or 'RECURRENT'.

merchant_or_partner_customer_idString

The unique ID for a customer in merchant's or partner's system of records.

paypal_v2_order_idString

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

refund_from_transaction_fee_amountString

The refund from the transaction fee amount of the PayPal transaction.

A refund from transaction fee of 1 will always be returned for sandbox integrations.

refund_from_transaction_fee_currency_iso_codeString

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

refund_idString

The currency of the associated refund from the transaction fee.

settlement_typeString

The type of settlement option that the merchant is configured for. This can be either 'INSTANT' or 'DELAYED'.

tokenString

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_amountString

The transaction fee amount of the PayPal transaction.

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

transaction_fee_currency_iso_codeString

The currency of the associated transaction fee.

service_fee_amountBigDecimal

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

Available to Braintree Marketplace merchants. See Creating Transactions with Service Fees for more details.

settlement_batch_idString

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_m_d where m is the merchant account token without special characters and d is an alphanumeric string to guarantee uniqueness.

shipping_amountBigDecimal

The data field that specifies the shipping cost on the entire transaction. It can't be negative, and it does not add to the total transaction amount. If Braintree has approved your merchant account for Level 3 processing, we will pass this field to the processor on your behalf.

shipping_detailsmap

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

companyString

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

country_code_alpha2String

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

country_code_alpha3String

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

country_code_numericString

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

country_nameString

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

extended_addressString

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

first_nameString

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

idString

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.

international_phonemap

The phone number that belongs to the address that is structured with country code and national number.

country_codeString

Country code of phone number. 1-3 digits. Required.

national_numberString

National number of phone number. 4-12 digits. Required.

last_nameString

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

localityString

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

phone_numberString

Deprecated.

We recommend using international_phone. This functionality still exists in the gateway but is no longer documented. This parameter will be removed in the future.

postal_codeString

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

regionString

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

shipping_method

street_addressString

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

shipping_tax_amountBigDecimal

The data field that specifies the tax charged on the shipping_amount of the entire transaction. It can't be negative, and it does not add to the total transaction amount. If Braintree has approved your merchant account for Level 3 processing, we will pass this field to the processor on your behalf.

ships_from_postal_codeString

The data field that specifies the postal code of the shipping location. If Braintree has approved your merchant account for Level 3 processing, we will pass this field to the processor on your behalf.

statusString

Possible values:

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

See the transaction status explanations for details.

status_history

A collection of status history details showing the transaction's status changes over time.

sub_merchant_account_idString

This functionality still exists in the gateway but is no longer documented. Will remove this param/attr when the corresponding gateway code is removed. Old description – The SubMerchantAccount ID used to create a transaction.

subscription_detailsmap

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_idString

The value used to identify a specific subscription.

surcharge_amountBigDecimal

The data field that specifies the surcharge amount that was included in the total transaction amount. It can't be negative, and it does not add to the total transaction amount. Your merchant account must be registered for surcharging.

tax_amountBigDecimal

A Level 2 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_exemptbool

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

terminal_identification_numberString

The terminal ID that was used for processing the transaction. This field is required to be included on an in-store transaction receipt.

three_d_secure_infoobj

The 3D Secure information for this transaction.

cavvString

Cardholder Authentication Verification Value or "CAVV". The main encrypted message issuers and card networks use to verify authentication has occured. Mastercard refers to this field as AAV, while American Express refers to this field as AEVV.

ds_transaction_idString

Transaction identifier resulting from 3D Secure 2 authentication.

eci_flagString

The value of the electronic commerce indicator (ECI) flag, which indicates the outcome of the 3DS authentication.

Possible values for Mastercard:

00 = Failed or not attempted
01 = Attempted
02 = Success
04 = Data-Only (Applies to limited processors)

Possible values for all other card brands:

07 = Failed or not attempted
06 = Attempted
05 = Success

enrolledString

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.

statusString

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

three_d_secure_versionString

The version of 3D Secure authentication used for the transaction. Composed of digits separated by periods (e.g. 1.0.2, 2.1.0).

xidString

Transaction identifier resulting from 3D Secure authentication. This field will no longer be used in 3D Secure 2 authentications.

typeString

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

updated_atTime

The date/time the object was last updated. Returned in UTC.

us_bank_account_detailsobj

If payment_instrument_type is us_bank_account, these are the details of the US Bank Account used for the transaction.

US bank account payments are available for eligible merchants. See the ACH Direct Debit guide for details.

account_holder_nameString

Account holder name.

account_typeString

The type of the bank account. Possible values:

"business_checking"
"business_savings"
"checking"
"savings"

ach_mandateString

The authorization text passed by the consumer allowing their account to be debited.

bank_nameString

The name of the issuing bank.

business_nameString

Business name.

first_nameString

The account holder's first name.

global_idString

The unique identifier used to identify this bank account in Braintree's GraphQL API.

graphql_idString

The unique identifier used to identify this bank account in Braintree's GraphQL API.

image_urlString

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

last_4String

The last 4 digits of the bank account number.

last_nameString

The account holder's last name.

ownership_typeString

The ownership type of the bank account. Possible values:

"business"
"personal"

routing_numberString

The bank routing number associated with the bank account.

tokenString

An alphanumeric value that references a specific payment method stored in your Vault.

verifiedbool

Indicates whether the bank account has been verified.

venmo_account_detailsobj

If payment_instrument_type is venmo_account, these are the details of the Venmo account used for the transaction.

Venmo payments are currently in a limited release and are only available to select merchants. See the Venmo guide for details.

image_urlString

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

source_descriptionString

A short description of the payment method, including the Venmo username.

tokenString

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 Venmo account.

usernameString

The Venmo username of the Venmo account.

venmo_user_idString

The Venmo user ID of the Venmo account.

visa_checkout_card_detailsmap

If payment_instrument_type is visa_checkout_card, these are the details of the card used for the transaction. If the transaction was created using Vault tokens, then this attribute is a snapshot of the Visa Checkout 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 (BIN).

call_idString

The Visa assigned identifier of the transaction.

card_type

The type of the credit card. Possible values:

American Express
Discover
MasterCard
Visa

cardholder_nameString

The cardholder name associated with the credit card.

commercialenum

country_of_issuanceString

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

The value Unknown will be returned if we cannot immediately determine the card's country of issuance from the bank identification number (BIN).

customer_locationenum

debitenum

durbin_regulatedenum

expiration_dateString

The expiration date, formatted MM/YY or MM/YYYY. May be used instead of expiration month and expiration year.

expiration_monthString

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

expiration_yearString

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

healthcareenum

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

is_network_tokenized?bool

issuing_bankString

The bank that issued the credit card.

last_4

The last 4 digits of the credit card number.

masked_number

payrollenum

prepaidenum

product_idString

The code for the product type of the card (e.g. D (Visa Signature Preferred), G (Visa Business)). See Product ID codes below for possible values.

tokenString

voice_referral_number

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

Result object

Successful result

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

Ruby

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

Ruby

transaction = result.transaction
transaction.payment_instrument_type == PaymentInstrumentType::PayPalAccount
#=> false
transaction.payment_instrument_type == PaymentInstrumentType::CreditCard
#=> true

Unsuccessful result

Success will return false if:

Validations prevent the transaction from being created
The processor declines the authorization or settlement
The gateway rejects the transaction

Ruby

result.success?
#=> false

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

Ruby

result.success?
#=> false
result.transaction.status
#=> "processor_declined"

result.transaction.processor_response_type
#=> "soft_declined"
result.transaction.processor_response_code
#=> "2001"
result.transaction.processor_response_text
#=> "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.

Ruby

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.

Ruby

result.success?
#=> false
result.transaction.status
#=> "settlement_declined"
result.transaction.processor_settlement_response_code
#=> "4001"
result.transaction.processor_settlement_response_text
#=> "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.

Ruby

result.success?
#=> false
result.transaction.status
#=> "gateway_rejected"
result.transaction.gateway_rejection_reason
#=> e.g. "cvv"

Risk data

We return the risk data on credit card verifications and on transactions with all compatible payment methods. The data includes the fraud service provider, the risk identifier, the device data captured flag, and the risk decision, which can provide further context on how a verification or transaction was scored by our Premium Fraud Management Tools. For users of Fraud Protection, the data will include the decision reasons. For users of Fraud Protection Advanced, the data will also include the risk score.

note
For users of our Java and .NET SDKs, you will need to upgrade to versions .NET 5.4.0 and Java 3.7.0 or later to see the decision reasons and risk score in the risk data.

Ruby

result.transaction.risk_data.id
#=> "1SG23YHM4BT5"
result.transaction.risk_data.decision
#=> "Decline"
result.transaction.risk_data.device_data_captured
#=> true
result.transaction.risk_data.fraud_service_provider
#=> "Kount"
result.transaction.risk_data.decision_reasons
#=> ["reason1", "reason2"]
result.transaction.risk_data.risk_score
#=> 42

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.

Ruby

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.

Ruby

if result.success?
  # transaction successfully submitted for settlement
elsif result.errors.any?
  puts result.errors.inspect
else
  puts result.transaction.processor_settlement_response_code
  puts result.transaction.processor_settlement_response_text
end

Processor settlement declined

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

Ruby

result.success?
#=> false
result.transaction.status
#=> "settlement_declined"
result.transaction.processor_settlement_response_code
#=> "4001"
result.transaction.processor_settlement_response_text
#=> "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 instead.

To check if the transaction has been settled, find the transaction and check the status.

Ruby

transaction = gateway.transaction.find("the_transaction_id")
    if transaction.status == "submitted_for_settlement"
      # can void
    elsif transaction.status == "settled"
      # will have to refund it
    else
      # this example only expected one of the two above statuses
    end

Authorization adjustments

The authorized amount of a transaction can be adjusted by using the adjust authorization endpoint. This will cause an authorization adjustment to be performed.

When submitting a transaction for settlement, if you specify a settlement amount that is different than the authorized amount, an authorization adjustment may be performed automatically.

For each adjustment performed, an authorization adjustment object will be associated with the original transaction. These adjustment objects will include the following details:

Adjustment Detail	Description
amount	The difference between the authorized amount and the amount submitted for settlement. Negative values indicate the authorized amount was adjusted down.
success	A boolean value indicating if the adjustment was successful.
timestamp	The date/time when the adjustment was performed.
proccessor_response_type	The processor response type. Possible values: `"approved"`, `"soft_declined"`, `"hard_declined"`. See the list of possible processor authorization responses.
proccessor_response_code	The processor response code. See the list of possible processor authorization responses.
proccessor_response_text	The processor response text. See the list of possible processor authorization responses.

Status history details

Status Detail	Description
amount	The amount of the request.
status	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
timestamp	The date/time the status change was performed. Results are returned in UTC.
transaction_source	How a transaction was created. Possible values: Api ControlPanel Recurring
user	The Braintree Control Panel username of the person who performed an action that triggered the status change of the transaction.

You can use these status events to retrieve information around transaction status changes.

Ruby

transaction = gateway.transaction.find("the_transaction_id")
transaction.status_history.each do |event|
	puts event.amount
	puts event.status
	puts event.timestamp
	puts event.transaction_source
	puts event.user

end

Product ID codes

The Braintree gateway returns the following product IDs for credit and debit card payment methods. The product ID is generally 1-3 characters and indicates the specific credit product that was issued to the customer.

Product ID code	Product name
001	Discover Consumer Credit – Rewards
002	Discover Commercial Credit
003	Discover Consumer Debit
004	Discover Commercial Debit
005	Discover Prepaid Gift
006	Discover Prepaid ID known
007	Discover Consumer Credit – Premium
008	Discover Consumer Credit - Core
009	Discover Private Label Credit
010	Discover Commercial Credit – Executive Business
011	Discover Consumer Credit – Premium Plus
012	Discover Commercial Prepaid – Non-Reloadable
013	Discover PayPal
014	Discover PayPal Mobile
A	Visa Traditional
B	Visa Traditional Rewards
BPD	MasterCard Business Premium Debit
C	Visa Signature
CIR	MasterCard Cirrus
D	Visa Signature Preferred
DAG	Global Debit MasterCard Salary
DAP	Platinum Debit MasterCard Salary
DAS	Standard Debit MasterCard Salary
DLG	Debit MasterCard Gold Delayed Debit
DLH	Debit MasterCard World Embossed Delayed Debit
DLP	Debit MasterCard Platinum Delayed Debit
DLS	Debit MasterCard Card Delayed Debit
DOS	Standard Debit MasterCard Social
DWF	Debit MasterCard Humanitarian Prepaid
E	Visa Proprietary ATM
F	Visa Classic
G	Visa Business
G1	Visa Signature Business
G3	Visa Business Enhanced (US only)
G4	Visa Infinite Business
G5	Visa Business Rewards
I	Visa Infinite
I	Visa Infinite Privilege
I2	Visa UHNW
IB	American Express Non-US
IR	American Express Non-US Reloadable
IS	American Express Non-US Stored Value
J3	Visa Healthcare
K	Visa Corporate T&E
K1	Visa GSA Corporate T&E
L	Visa Electron
MAB	World Elite MasterCard for Business Card
MAC	MasterCard World Elite Corporate Card
MAP	MasterCard Commercial Payments Account
MAQ	MasterCard Prepaid Commercial Payments Account
MBB	MasterCard Prepaid Consumer
MBC	MasterCard Prepaid Voucher
MBD	MasterCard Professional Debit BusinessCard Card
MBE	MasterCard Electronic Business Card
MBF	Prepaid MC Food
MBK	MasterCard Black Card
MBM	Prepaid MC Meal
MBP	MasterCard Corporate Prepaid
MBS	MasterCard B2B Product
MBT	MasterCard Corporate Prepaid Travel
MBW	World MasterCard Black Edition Debit
MCB	MasterCard BusinessCard Card
MCC	MasterCard Credit Card (mixed BIN)
MCD	Debit MasterCard Card
MCE	MasterCard Electronic Card
MCF	MasterCard Fleet Card
MCG	Gold MasterCard Card
MCH	MasterCard Premium Charge
MCO	MasterCard Corporate (Meeting) Card
MCP	MasterCard Purchasing Card
MCS	(Unembossed) Standard MasterCard Card
MCT	Titanium MasterCard Card
MCV	Merchant-Branded Program
MCW	World MasterCard Card
MDB	Debit MasterCard BusinessCard Card
MDG	Gold Debit MasterCard Card
MDH	World Debit Embossed MasterCard Card
MDJ	Debit MasterCard (Enhanced)
MDL	MasterCard Business Debit Other Embossed
MDO	MasterCard Debit Other
MDP	Premium Debit MasterCard Card
MDR	MasterCard Debit Brokerage
MDS	Debit MasterCard Card
MDT	Commercial Debit MasterCard Card
MDW	World Elite Debit MasterCard
MEB	MasterCard Executive BusinessCard Card
MEC	MasterCard Electronic Commercial
MEF	MasterCard Electronic Payment Account
MEO	MasterCard Corporate Executive Card
MET	Titanium Debit MasterCard Card
MFB	MasterCard Flex World Elite
MFD	MasterCard Flex Platinum
MFE	MasterCard Flex Charge World Elite
MFH	MasterCard Flex World
MFL	MasterCard Flex Charge Platinum
MFW	MasterCard Flex World Charge
MGF	MasterCard Government Commercial Card
MHA	MasterCard Healthcare Prepaid Non-Tax
MHB	MasterCard HSA Substantiated (Debit MasterCard)
MHD	MasterCard HELOC Debit Standard
MHH	MasterCard HSA Non-Substantiated (Debit MasterCard)
MHK	MasterCard Magna Health Access Card
MHD	MasterCard HELOC Debit Gold
MHD	MasterCard HELOC Debit Platninum
MHD	MasterCard HELOC Debit Premium
MIA	Prepaid MasterCard Unembossed Student Card
MIK	Prepaid MasterCard Electronic Student (Non-US) Card
MIL	Unembossed MasterCard Student Card (Non-US)
MIP	Prepaid Debit MasterCard Student Card
MIU	Debit MasterCard Unembossed (Non-US)
MLA	MasterCard Central Travel Solutions Air Card
MLB	MasterCard Brazil Benefit for Home Improvement
MLD	MasterCard Distribution Card
MLE	MasterCard Brazil General Benefits
MLF	MasterCard Agro Card
MLL	MasterCard Central Travel Solutions Land Card
MNF	MasterCard Public Sector Commercial Card
MNW	MasterCard World Card
MOC	Standard Maestro Social
MOG	Maestro Gold Card
MOP	Maestro Platinum
MOW	World Maestro
MPA	MasterCard Prepaid Debit Standard Payroll
MPB	MasterCard Preferred Business Card
MPD	MasterCard Flex Prepaid
MPF	MasterCard Prepaid Debit Standard Gift
MPG	Debit MasterCard Standard Prepaid General Spend
MPH	MasterCard Cash
MPJ	Prepaid Debit MasterCard Card Gold
MPK	MasterCard Prepaid Government Commercial Card
MPL	Platinum MasterCard Card
MPM	MasterCard Prepaid Debit Standard Consumer Incentive
MPN	MasterCard Prepaid Debit Standard Insurance
MPO	MasterCard Prepaid Debit Standard Offer
MPP	MasterCard Prepaid Card – Commercial Reward Funding
MPQ	MasterCard Prepaid Debit Standard Government Disaster
MPR	MasterCard Prepaid Debit Standard Travel
MPT	MasterCard Prepaid Debit Standard Teen
MPV	MasterCard Prepaid Debit Standard Government
MPW	Debit MasterCard Business Card Prepaid Workplace Business
MPX	MasterCard Prepaid Debit Standard Flex Benefit
MPY	MasterCard Prepaid Debit Standard Employee Incentive
MPZ	MasterCard Prepaid Debit Standard Government Consumer
MRB	MasterCard Prepaid Electronic Business Card (Non-US)
MRC	Prepaid MasterCard Electronic Card (Non-US)
MRF	MasterCard European Regulated Individual Pay
MRG	MasterCard Prepaid Card (Non-US)
MRH	MasterCard Platinum Prepaid Travel (US)
MRJ	Prepaid MasterCard Gold Card
MRK	Prepaid MasterCard Public Sector Commercial Card
MRL	Prepaid MasterCard Electronic Commercial Card (Non-US)
MRO	MasterCard Rewards Only
MRP	Standard Retailer Centric Payments
MRS	Prepaid MasterCard ISIC Student Card
MRW	Prepaid MasterCard Business Card (Non-US)
MSA	Prepaid Maestro Payroll Card
MSB	Maestro Small Business Card
MSF	Prepaid Maestro Gift Card
MSG	Prepaid Maestro Consumer Reloadable Card
MSI	Maestro Student Card
MSJ	Prepaid Maestro Gold
MSM	Prepaid Maestro Consumer Promotion Card
MSN	Prepaid Maestro Insurance Card
MSO	Prepaid Maestro Other Card
MSQ	Unknown MasterCard
MSR	Prepaid Maestro Travel Card
MST	Prepaid Maestro Teen Card
MSV	Prepaid Maestro Government Benefit Card
MSW	Prepaid Maestro Corporate (Reloadable) Card
MSX	Prepaid Maestro Flex Benefit Card
MSY	Prepaid Maestro Employee Incentive Card
MSZ	Prepaid Maestro Emergency Assistance Card
MTP	MasterCard Platinum Prepaid Travel (UK and Brazil)
MUS	Prepaid Unembossed MasterCard Card
MUW	MasterCard World Domestic Affluent
MWB	World Elite MasterCard Business Card
MWD	World Deferred MasterCard
MWE	World Elite MasterCard Card
MWF	MasterCard Humanitarian Prepaid
MWO	World Elite MasterCard Corporate Card
MWR	MasterCard World Retailer Centric Payments
N	Visa Platform
N1	Visa Rewards
N2	Visa Select
OLB	Maestro Small Business Delayed Debit
OLG	Maestro Gold Delayed Debit
OLP	Maestro Platinum Delayed Debit
OLS	Maestro (Student Card) Delayed Debit
OLW	World Maestro Delayed Debit
P	Visa Gold
PMC	MasterCard Proprietary Credit Card (Swedish domestic)
PMD	MasterCard Proprietary Debit Card (Swedish domestic)
PSC	MasterCard Common Proprietary Swedish Credit Card
PSD	MasterCard Common Proprietary Swedish Debit Card
PVA	MasterCard Private Label A
PVB	MasterCard Private Label B
PVC	MasterCard Private Label C
PVD	MasterCard Private Label D
PVE	MasterCard Private Label E
PVF	MasterCard Private Label F
PVG	MasterCard Private Label G
PVH	MasterCard Private Label H
PVI	MasterCard Private Label I
PVJ	MasterCard Private Label J
PVL	MasterCard Private Label L
Q	Visa Private Label
Q2	Visa Private Label Basic
Q3	Visa Private Label Standard
Q4	Visa Private Label Enhanced
Q5	Visa Private Label Specialized
Q6	Visa Private Label Premium
R	Visa Proprietary
RP	American Express US Reloadable
S	Visa Purchasing
S1	Visa Purchasing with Fleet
S2	Visa GSA Purchasing
S3	Visa GSA Purchasing with Fleet
S4	Visa Government Services Loan
S5	Visa Commercial Transport (EBT)
S6	Visa Business Loan
S7	Visa Distribution
SAG	Gold MasterCard Salary Immediate Debit
SAL	Standard Maestro Salary
SAP	Platinum MasterCard Salary Immediate Debit
SAS	Standard MasterCard Salary Immediate Debit
SOS	Standard MasterCard Social Immediate Debit
SUR	Prepaid Unembossed MasterCard Card (Non-US)
SV	American Express US Stored Value
TBE	MasterCard Electronic Business Immediate Debit
TCB	MasterCard Corporate Immediate Debit
TCC	MasterCard (mixed BIN) Immediate Debit
TCE	MasterCard (Electronic) Student Card Immediate Debit
TCF	MasterCard Fleet Card Immediate Debit
TCG	Gold MasterCard Card Immediate Debit
TCO	MasterCard (Corporate) Immediate Debit
TCP	MasterCard Purchasing Card Immediate Debit
TCS	MasterCard Standard (Unembossed) Card Immediate Debit
TCW	MasterCard World Signia Immediate Debit
TEB	MasterCard Executive BusinessCard Card Immediate Debit
TEC	MasterCard Electronic Commercial Immediate Debit
TEO	MasterCard Corporate Executive Card Immediate Debit
TNF	MasterCard Public Sector Commercial Card Immediate Debit
TNW	MasterCard New World Immediate Debit
TPB	MasterCard Preferred Business Card Immediate Debit
TPL	Platinum MasterCard Immediate Debit
TWB	World MasterCard Black Edition Immediate Debit
U	Visa Travel Money
V	Visa V Pay
WBE	World MasterCard Black Edition
X	Visa B2B Virtual Payments

Network response codes

In addition to the processor response code and text, some transaction and verification objects also include a network response code and text.

These network response values are the raw responses that may be returned by the card network, and when present they can provide additional detail about why a request was approved or declined. However, this information is supplemental to the processor response code; you should consider the processor response code to be the source of truth.

Each card network has distinct response codes:

Card Network	Code	Text
Visa	00	Successful approval/completion or V.I.P. PIN verification is successful
Visa	01	Refer to card issuer
Visa	02	Refer to card issuer, special condition
Visa	03	Invalid merchant or service provider
Visa	04	Pick up card
Visa	05	Do not Honor
Visa	06	Error
Visa	07	Pick up card, special condition (other than lost/stolen card)
Visa	10	Partial Approval
Visa	11	V.I.P. approval
Visa	12	Invalid transaction
Visa	13	Invalid amount (currency conversion field overflow); or amount exceeds maximum for card program
Visa	14	Invalid account number (no such number)
Visa	15	No such issuer
Visa	19	Re-enter transaction
Visa	21	No action taken (unable to back out prior transaction)
Visa	25	Unable to locate record in file, or account number is missing from the inquiry
Visa	28	File is temporarily unavailable
Visa	39	No credit account
Visa	41	Pick up card (lost card)
Visa	43	Pick up card (stolen card)
Visa	46	Closed Account
Visa	51	Insufficient funds
Visa	52	No checking account
Visa	53	No savings account
Visa	54	Expired card
Visa	55	Incorrect PIN
Visa	57	Transaction not permitted to cardholder
Visa	58	Transaction not allowed at terminal
Visa	59	Suspected fraud
Visa	61	Activity amount limit exceeded
Visa	62	Restricted card (for instance, in Country Exclusion table)
Visa	63	Security violation
Visa	64	Transaction does not fulfill AML requirement
Visa	65	Activity count limit exceeded
Visa	75	Allowable number of PIN-entry tries exceeded
Visa	76	Unable to locate previous message (no match on retrieval reference number)
Visa	77	Previous message located for a repeat or reversal, but repeat or reversal data inconsistent with original message
Visa	78	Blocked, first used — Transaction from new cardholder, and card not properly unblocked
Visa	79	Transaction reversed
Visa	80	Visa transactions: credit issuer unavailable. Private label: invalid date
Visa	81	PIN cryptographic error found (error found by VIC security module during PIN decryption)
Visa	82	Negative Online CAM, dCVV, iCVV, or CVV results Or Offline PIN authentication interrupted
Visa	85	No reason to decline request for account number verification, address verification, CVV2 verification, or credit voucher or merchandise return
Visa	86	Cannot verify PIN
Visa	91	Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) Issuers can respond with this code, which V.I.P. passes to the acquirer without invoking stand-in processing (STIP). Issuer processors use the code to indicate they cannot perform authorization on issuers’ behalf. Code causes decline at POS.
Visa	1A	Additional customer authentication required
Visa	B1	B116 Surcharge amount not permitted on Visa cards
Visa	N0	Force STIP
Visa	N3	Cash service not available
Visa	N4	Cashback request exceeds issuer limit
Visa	N7	Decline for CVV2 failure
Visa	N8	Transaction amount exceeds pre-authorized approval amount
Visa	P2	P2 Invalid biller information
Visa	P5	PIN change/unblock request declined
Visa	P6	Unsafe PIN
Visa	R0	Stop payment order
Visa	R1	Revocation of authorization order
Visa	R3	Revocation of all authorizations order
Visa	Z3	Unable to go online; declined
Visa	XA	Forward to issuer
Visa	XD	Forward to issuer
Visa	Q1	Card authentication failed Or Offline PIN authentication interrupted
Mastercard	00	Approved or completed successfully
Mastercard	01	Refer to card issuer
Mastercard	03	Invalid merchant
Mastercard	04	Capture card Capture
Mastercard	05	Do not honor
Mastercard	08	Honor with ID
Mastercard	10	Partial Approval
Mastercard	12	Invalid transaction
Mastercard	13	Invalid amount
Mastercard	14	Invalid card number
Mastercard	15	Invalid issuer
Mastercard	30	Format error
Mastercard	41	Lost card
Mastercard	43	Stolen Card
Mastercard	51	Insufficient funds/over credit limit
Mastercard	54	Expired card
Mastercard	55	Invalid PIN
Mastercard	57	Transaction not permitted to issuer/cardholder
Mastercard	58	Transaction not permitted to acquirer/terminal
Mastercard	61	Exceeds withdrawal amount limit
Mastercard	62	Restricted card
Mastercard	63	Security violation
Mastercard	65	Exceeds withdrawal count limit
Mastercard	70	Contact Card Issuer
Mastercard	71	PIN Not Changed
Mastercard	75	Allowable number of PIN tries exceeded
Mastercard	76	Invalid/nonexistent To Account specified
Mastercard	77	Invalid/nonexistent From Account specified
Mastercard	78	Invalid/nonexistent account specified (general)
Mastercard	79	Lifecycle Declines
Mastercard	81	Domestic Debit Transaction Not Allowed (Regional use only)
Mastercard	82	Policy Declines
Mastercard	84	Invalid Authorization Life Cycle
Mastercard	85	Not declined. Valid for all zero amount transactions.
Mastercard	86	PIN Validation not possible
Mastercard	87	Purchase Amount Only, No Cash Back Allowed
Mastercard	88	Cryptographic failure
Mastercard	89	Unacceptable PIN—Transaction Declined—Retry
Mastercard	91	Authorization System or issuer system inoperative
Mastercard	92	Unable to route transaction
Mastercard	94	Duplicate transmission detected
Mastercard	96	System error
Discover	00	Approved or completed successfully
Discover	01	Reserved for future use
Discover	02	Reserved for future use
Discover	03	Invalid Merchant
Discover	04	Capture Card
Discover	05	Do not honor
Discover	07	Pick-up Card, special condition
Discover	08	Reserved for future use
Discover	10	Approved for partial amount
Discover	11	Approved
Discover	12	Invalid transaction
Discover	13	Invalid amount
Discover	14	Invalid Card Number
Discover	15	Reserved for future use
Discover	19	Re-enter transaction
Discover	30	Format error
Discover	31	Bank not supported by switch
Discover	33	Reserved for future use
Discover	34	Reserved for future use
Discover	35	Reserved for future use
Discover	36	Reserved for future use
Discover	37	Reserved for future use
Discover	38	Allowable PIN tries exceeded
Discover	39	No credit Account
Discover	40	Requested function not supported
Discover	41	Lost Card
Discover	43	Stolen Card
Discover	51	Decline
Discover	53	No savings Account
Discover	54	Expired Card
Discover	55	Invalid PIN
Discover	56	No Card record
Discover	57	Transaction not permitted to Issuer/Cardholder
Discover	58	Transaction not permitted to Acquirer/terminal
Discover	59	Suspected fraud
Discover	60	Card acceptor contact Acquirer
Discover	61	Exceeds withdrawal amount limit
Discover	62	Restricted Card
Discover	63	Security violation
Discover	64	Original amount incorrect
Discover	65	Exceeds withdrawal count limit
Discover	66	Card Acceptor call Acquirer’s security dept
Discover	67	Hard capture (requires ATM pick-up)
Discover	68	Response received too late Decline
Discover	75	Allowable number of PIN tries exceeded
Discover	76	Invalid/nonexistent “to” Account specified
Discover	77	Invalid/nonexistent “from” Account specified
Discover	78	Invalid/nonexistent Account specified (general)
Discover	83	Domain Restriction Controls Failure
Discover	85	No reason to decline
Discover	87	Network unavailable
Discover	91	Authorization system or Issuer system inoperative
Discover	92	Unable to route transaction Decline
Discover	93	Transaction cannot be completed, violation of law
Discover	94	Duplicate transmission detected
Discover	96	System malfunction Decline
Discover	N1	System up
Discover	N2	Soft down
Discover	N3	System down
Discover	N7	Decline for AVS or CID mismatch
Discover	P5	PIN Change/Unblock failed
Discover	P6	New PIN not accepted
American Express	000	Approved
American Express	001	Approved with ID
American Express	002	Partial Approval (Prepaid Cards only)
American Express	100	Deny
American Express	101	Expired Card / Invalid Expiration Date
American Express	106	Exceeded PIN attempts
American Express	107	Please Call Issuer
American Express	109	Invalid merchant
American Express	110	Invalid amount
American Express	111	Invalid account / Invalid MICR (Travelers Cheque)
American Express	115	Requested function not supported
American Express	117	Invalid PIN
American Express	119	Cardmember not enrolled / not permitted
American Express	122	Invalid card security code (a.k.a., CID, 4DBC, 4CSC)
American Express	125	Invalid effective date
American Express	181	Format error
American Express	183	Invalid currency code
American Express	187	Deny - New card issued
American Express	189	Deny - Canceled or Closed Merchant/SE
American Express	200	Deny - Pick up card
American Express	900	Accepted - ATC Synchronization
American Express	909	System Malfunction (Cryptographic error)
American Express	912	Issuer not available

Transaction

Attributes

Result object

Successful result

Unsuccessful result

Validation errors

Processor declined

Processor settlement declined

Gateway rejection

Risk data

Params retrieval

Examples

Currencies

Settlement status

Processor settlement declined

Voiding settlement

Authorization adjustments

Status history details

Product ID codes

Network response codes

See also