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

achReturnCodestring

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

acquirerReferenceNumberstring

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.

addOnsarray

The collection of add-ons associated with a subscription.

additionalProcessorResponsestring

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

amountString

The billing amount of the request.

googlePayCardDetailsobj

If paymentInstrumentType is androidPayCard, 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 paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

countryOfIssuancestring

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 paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

durbinRegulatedenum

If paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

expirationMonthstring

The expiration month of the credit card, formatted MM.

expirationYearstring

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

googleTransactionIdstring

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

healthcareenum

If paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

imageUrlstring

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

isNetworkTokenizedbool

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 paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

prepaidenum

If paymentInstrumentType is androidPayCard, these are the details of the card used for the transaction.

productIdstring

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.

sourceCardLast4string

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.

sourceCardTypestring

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

sourceDescriptionstring

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.

virtualCardLast4string

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

virtualCardTypestring

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

applePayCardDetailsobj

If paymentInstrumentType is applePayCard, 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.

cardTypestring

The type of the credit card. Possible values:

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

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

If paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

countryOfIssuancestring

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 paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

durbinRegulatedenum

If paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

expirationMonthstring

The expiration month of the credit card, formatted MM.

expirationYearstring

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

healthcareenum

If paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

imageUrlstring

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

issuingBankstring

The bank that issued the credit card.

last4string

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

merchantTokenIdentifierstring

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

paymentInstrumentNamestring

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 paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

prepaidenum

If paymentInstrumentType is applePayCard, these are the details of the credit card used for the transaction.

productIdstring

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.

sourceCardLast4string

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

sourceDescriptionstring

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.

authorizationAdjustments

A collection of authorization adjustments associated with the transaction.

authorizationExpiresAtDateTime

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.

avsErrorResponseCode

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 null, you will see responses in both avsPostalCodeResponseCode and avsStreetAddressResponseCode.

avsPostalCodeResponseCode

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

avsStreetAddressResponseCode

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

billingDetailsmap

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.

countryCodeAlpha2string

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

countryCodeAlpha3string

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

countryCodeNumericstring

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

countryNamestring

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

extendedAddressstring

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

firstNamestring

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.

internationalPhonemap

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

countryCodestring

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

nationalNumberstring

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

lastNamestring

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

localitystring

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

phoneNumberstring

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.

postalCodestring

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

regionstring

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

streetAddressstring

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.

createdAtDateTime

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

creditCardDetailsmap

If paymentInstrumentType is creditCard, 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).

cardType

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

countryOfIssuancestring

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

customerLocationenum

debitenum

durbinRegulatedenum

expirationDatestring

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

expirationMonthstring

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

expirationYearstring

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

healthcareenum

imageUrl

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

issuingBankstring

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

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.

paymentReaderAttributesmap

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.

applicationCryptogramstring

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.

applicationIdentifierstring

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

applicationInterchangeProfilestring

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.

applicationNamestring

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.

applicationTransactionCounterstring

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.

applicationUsageControlstring

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.

authorizationMode

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

authorizationResponseCodestring

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.

cardEntryMethodstring

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.

cardSequenceNumberstring

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.

cardholderVerificationMethodResultsstring

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.

cashbackAmountstring

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.

cryptogramInformationDatastring

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.

issuerActionCodeDefaultstring

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.

issuerActionCodeDenialstring

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.

issuerActionCodeOnlinestring

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.

issuerAuthenticationDatastring

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.

terminalCountryCodestring

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.

terminalTransactionDatestring

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.

terminalTransactionTypestring

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.

terminalVerificationResultstring

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.

unpredictableNumberstring

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

productIdstring

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

uniqueNumberIdentifier

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.

currencyIsoCode

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

customFieldsobj

A collection of custom field/value pairs.

customerDetailsmap

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.

firstNamestring

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

idstring

internationalPhonemap

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

countryCodestring

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

nationalNumberstring

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

lastNamestring

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.

cvvResponseCode

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.

disbursementDetailsmap

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.

disbursementDate

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

fundsHeldbool

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

settlementAmountString

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

settlementBaseCurrencyExchangeRate

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

settlementCurrencyExchangeRate

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

settlementCurrencyIsoCode

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.

discountAmountString

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.

escrowStatus

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

facilitatedDetailsmap

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.

merchantIdstring

The merchant ID of the merchant of record.

merchantNamestring

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

paymentMethodNoncestring

facilitatorDetailsmap

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.

oauthApplicationClientIdstring

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

oauthApplicationNamestring

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

sourcePaymentMethodTokenstring

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

gatewayRejectionReason

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"

graphQLIdstring

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.

lineItems

A collection of line items associated with the transaction.

localPaymentDetailsmap

If paymentInstrumentType is localPayment, these are the details used for the transaction.

customFieldstring

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.

fundingSourcestring

The local bank used to fund the transaction.

implicitlyVaultedPaymentMethodGlobalIdstring

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

implicitlyVaultedPaymentMethodTokenstring

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

payerIdstring

The identifier for the payer in the request.

paymentIdstring

The PayPal Order ID associated with the transaction.

transactionFeeAmountstring

The transaction fee amount of the PayPal transaction.

transactionFeeCurrencyIsoCodestring

The transaction fee currency code of the PayPal transaction.

masterMerchantAccountIdstring

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.

masterpassCardDetailsmap

If paymentInstrumentType is masterpassCard, 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).

cardType

The type of the credit card. Possible values:

American Express
Discover
JCB
Maestro
MasterCard
Visa

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

countryOfIssuancestring

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

customerLocationenum

debitenum

durbinRegulatedenum

expirationDatestring

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

expirationMonthstring

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

expirationYearstring

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

healthcareenum

imageUrl

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

isNetworkTokenizedbool

issuingBankstring

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

payrollenum

prepaidenum

productIdstring

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

merchantAccountIdstring

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

merchantAddressmap

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.

postalCodestring

The postal code.

regionstring

The state or province.

streetAddressstring

The street address.

merchantAdviceCodestring

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.

merchantAdviceCodeTextstring

The merchant advice code text for the merchantAdviceCode.

merchantIdentificationNumberstring

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

merchantNamestring

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

networkResponseCodestring

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

networkResponseTextstring

The network response text for the networkResponseCode.

networkTokenmap

If paymentInstrumentType is networkToken, 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).

cardType

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

countryOfIssuancestring

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

customerLocationenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

debitenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

durbinRegulatedenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

expirationDatestring

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

expirationMonthstring

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

expirationYearstring

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

healthcareenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

imageUrl

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

isNetworkTokenizedbool

issuingBankstring

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

payrollenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

prepaidenum

If paymentInstrumentType is networkToken, these are the details of the token used for the transaction.

productIdstring

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.

networkTransactionIdstring

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 externalVault.previousNetworkTransactionId field of subsequent transactions.

orderIdstring

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.

paymentInstrumentType

paymentReceiptmap

Transaction receipt data.

accountBalanceString

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

amountString

The billing amount of the request.

cardLast4string

The last 4 digits of the credit card number.

cardPresentDatamap

Card present details.

applicationCryptogramstring

applicationIdentifierstring

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

applicationInterchangeProfilestring

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.

applicationNamestring

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.

applicationTransactionCounterstring

applicationUsageControlstring

authorizationMode

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

authorizationResponseCodestring

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.

cardEntryMethodstring

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.

cardSequenceNumberstring

cardholderVerificationMethodResultsstring

cashbackAmountstring

cryptogramInformationDatastring

issuerActionCodeDefaultstring

issuerActionCodeDenialstring

issuerActionCodeOnlinestring

issuerAuthenticationDatastring

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.

terminalCountryCodestring

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.

terminalTransactionDatestring

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.

terminalTransactionTypestring

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.

terminalVerificationResultstring

unpredictableNumberstring

cardTypestring

The credit card type.

currencyIsoCodestring

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

globalIdstring

The unique transaction global ID.

idstring

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

merchantAddressmap

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.

postalCodestring

The postal code.

regionstring

The state or province.

streetAddressstring

The street address.

merchantIdentificationNumberstring

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

merchantNamestring

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

pinVerifiedbool

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

processorAuthorizationCodestring

The authorization code returned by the processor.

processorResponseCodestring

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

processorResponseTextstring

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

terminalIdentificationNumberstring

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.

paypalDetailsmap

If paymentInstrumentType is paypalAccount, these are the details of the PayPal account used for the transaction.

authorizationIdstring

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

captureIdstring

PayPal id for a transaction.

customFieldstring

Custom field/value pairs.

imageUrlstring

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

implicitlyVaultedPaymentMethodGlobalIdstring

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

implicitlyVaultedPaymentMethodTokenstring

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

payerEmailstring

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.

payerFirstNamestring

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

payerIdstring

The identifier for the PayPal account used in the request.

payerLastNamestring

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

payerPhonestring

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

payerStatusstring

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

paymentIdstring

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

refundDescriptionstring

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

refundFromTransactionFeeAmountstring

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.

refundFromTransactionFeeCurrencyIsoCodestring

The currency of the associated refund from the transaction fee.

refundIdstring

PayPal id for a refund.

refundReasonstring

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

selectedFinancingCurrencyCodestring

The currency code for the selected financing option.

selectedFinancingDiscountAmountstring

Optional discount amount for the selected financing option.

selectedFinancingDiscountPercentageString

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

selectedFinancingMonthlyPaymentAmountstring

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

selectedFinancingTerminteger

The agreed term in months for the selected financing option.

sellerProtectionStatusstring

Indicates whether a transaction qualifies for PayPal Seller Protection.

shippingOptionIdstring

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

taxIdstring

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

taxIdTypestring

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.

transactionFeeAmountstring

The transaction fee amount of the PayPal transaction.

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

transactionFeeCurrencyIsoCodestring

The currency of the associated transaction fee.

paypalHereDetailsmap

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

authorizationIdstring

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

captureIdstring

PayPal ID for a transaction.

invoiceIdstring

PayPal ID for the invoice for the transaction.

last4string

The last 4 digits of the credit card number.

paymentIdstring

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

paymentTypestring

The type of the credit card. Possible values:

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

refundIdstring

PayPal ID for a refund.

transactionFeeAmountobj

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

transactionFeeCurrencyIsoCodestring

The currency of the associated transaction fee.

transactionInitiationDateDateTime

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

transactionUpdatedDateDateTime

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

pinVerifiedbool

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

planIdstring

The plan identifier.

processedWithNetworkTokenbool

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

processorAuthorizationCode

The authorization code returned by the processor.

processorResponseCodestring

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

processorResponseTextstring

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

processorResponseTypestring

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.

processorSettlementResponseCodestring

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

processorSettlementResponseTextstring

The text explanation of the above processor settlement response code.

purchaseOrderNumberstring

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.

refundIdstring

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.

refundIds

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

refundedTransactionIdstring

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

responseEmvDatastring

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

retriedTransactionIdstring

The transaction ID of the transaction that was retried.

retrievalReferenceNumberstring

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

retryIdsmap

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

riskDatamap

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

decisionReasonsmap

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

deviceDataCapturedbool

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

fraudServiceProviderstring

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

idstring

The risk data identifier.

liabilityShiftmap

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.

responsiblePartystring

The party that is now responsible for the chargeback.

transactionRiskScorestring

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.

samsungPayCardDetailsmap

If paymentInstrumentType is samsungPayCard, 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).

cardType

The type of the credit card. Possible values:

American Express
MasterCard
Visa

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

countryOfIssuancestring

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

customerLocationenum

debitenum

durbinRegulatedenum

expirationDatestring

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

expirationMonthstring

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

expirationYearstring

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

healthcareenum

imageUrl

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

isNetworkTokenizedbool

issuingBankstring

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

payrollenum

prepaidenum

productIdstring

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.

sourceCardLast4string

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

tokenstring

scaExemptionRequestedstring

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.

sepaDebitAccountDetailobj

If paymentInstrumentType is sepaDebitAccount, 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.

bankReferenceTokenstring

The tokenized payment source to fund a payment.

captureIdstring

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

last4string

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

mandateTypestring

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

merchantOrPartnerCustomerIdstring

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

paypalV2OrderIdstring

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

refundFromTransactionFeeAmountstring

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.

refundFromTransactionFeeCurrencyIsoCodestring

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

refundIdstring

The currency of the associated refund from the transaction fee.

settlementTypestring

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.

transactionFeeAmountstring

The transaction fee amount of the PayPal transaction.

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

transactionFeeCurrencyIsoCodestring

The currency of the associated transaction fee.

serviceFeeAmountString

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.

settlementBatchIdstring

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.

shippingAmountString

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.

shippingDetailsmap

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.

countryCodeAlpha2string

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

countryCodeAlpha3string

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

countryCodeNumericstring

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

countryNamestring

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

extendedAddressstring

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

firstNamestring

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.

internationalPhonemap

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

countryCodestring

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

nationalNumberstring

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

lastNamestring

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

localitystring

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

phoneNumberstring

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.

postalCodestring

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

regionstring

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

shippingMethod

streetAddressstring

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

shippingTaxAmountString

The data field that specifies the tax charged on the shippingAmount 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.

shipsFromPostalCodestring

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:

authorizationExpired
authorized
authorizing
settlementPending
settlementDeclined
failed
gatewayRejected
processorDeclined
settled
settling
submittedForSettlement
voided

See the transaction status explanations for details.

statusHistory

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

subMerchantAccountIdstring

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.

subscriptionDetailsmap

billingPeriodEndDate

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.

billingPeriodStartDate

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.

subscriptionIdstring

The value used to identify a specific subscription.

surchargeAmountString

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.

taxAmountString

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.

taxExemptbool

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.

terminalIdentificationNumberstring

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

threeDSecureInfoobj

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.

dsTransactionIdstring

Transaction identifier resulting from 3D Secure 2 authentication.

eciFlagstring

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

liabilityShiftPossiblebool

Indicates whether a liability shift is possible.

liabilityShiftedbool

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.

threeDSecureVersionstring

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.

updatedAtDateTime

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

usBankAccountDetailsobj

If paymentInstrumentType is usBankAccount, 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.

accountHolderNamestring

Account holder name.

accountTypestring

The type of the bank account. Possible values:

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

achMandatestring

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

bankNamestring

The name of the issuing bank.

businessNamestring

Business name.

firstNamestring

The account holder's first name.

globalIdstring

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

graphQLIdstring

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

imageUrlstring

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

last4string

The last 4 digits of the bank account number.

lastNamestring

The account holder's last name.

ownershipTypestring

The ownership type of the bank account. Possible values:

"business"
"personal"

routingNumberstring

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.

venmoAccountDetailsobj

If paymentInstrumentType is venmoAccount, 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.

imageUrlstring

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

sourceDescriptionstring

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.

venmoUserIdstring

The Venmo user ID of the Venmo account.

visaCheckoutCardDetailsmap

If paymentInstrumentType is visaCheckoutCard, 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).

callIdstring

The Visa assigned identifier of the transaction.

cardType

The type of the credit card. Possible values:

American Express
Discover
MasterCard
Visa

cardholderNamestring

The cardholder name associated with the credit card.

commercialenum

countryOfIssuancestring

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

customerLocationenum

debitenum

durbinRegulatedenum

expirationDatestring

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

expirationMonthstring

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

expirationYearstring

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

healthcareenum

imageUrl

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

isNetworkTokenizedbool

issuingBankstring

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

payrollenum

prepaidenum

productIdstring

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

voiceReferralNumber

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-submitForSettlement option was used) a submitted for settlement status.

PHP

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

PHP

$transaction = $result->transaction;
$transaction->paymentInstrumentType == BraintreePaymentInstrumentType::PAYPAL_ACCOUNT;
# false
$transaction->paymentInstrumentType == BraintreePaymentInstrumentType::CREDIT_CARD;
# 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

PHP

$result->success
# false

$result->errors->deepAll()

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.

PHP

$result->success
# false

$result->transaction->status
# "processor_declined"

$result->transaction->processorResponseType
# "soft_declined"

$result->transaction->processorResponseCode
# e.g. 2000

$result->transaction->processorResponseText
# e.g. "Do Not Honor"

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.

PHP

$result->transaction->additionalProcessorResponse
# 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.

PHP

$result->success
# false

$result->transaction->status
# "settlement_declined"

$result->transaction->processorSettlementResponseCode
# e.g. 4001

$result->transaction->processorSettlementResponseText
# 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.

PHP

$result->success
# false

$result->transaction->status
# "gateway_rejected"

$result->transaction->gatewayRejectionReason
# 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.

PHP

$result->transaction->riskData->id
# "1SG23YHM4BT5"
$result->transaction->riskData->decision
# "Decline"
$result->transaction->riskData->deviceDataCaptured
# True
$result->transaction->riskData->fraudServiceProvider
# "Kount"
$result->transaction->riskData->decisionReasons
# ["reason1", "reason2"]
$result->transaction->riskData->riskScore
# 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.

PHP

$transaction->currencyIsoCode
# e.g. '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 processorSettlementResponseCode on the transaction, which will indicate if the processor declined the request.

PHP

$result = $gateway->transaction()->submitForSettlement('the_transaction_id', '35.00');
if ($result->success) {
    // success
} else if ($result->errors->deepSize() > 0) {
    print_r($result->errors);
} else {
    echo $result->transaction->processorSettlementResponseCode;
    echo $result->transaction->processorSettlementResponseText;
}

Processor settlement declined

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

PHP

$result->success
# false

$result->transaction->status
# "settlement_declined"

$result->transaction->processorSettlementResponseCode
# e.g. 4001

$result->transaction->processorSettlementResponseText
# 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 instead.

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

PHP

$transaction = $gateway->transaction()->find('the_transaction_id');
if ($transaction->status == BraintreeTransaction::SUBMITTED_FOR_SETTLEMENT) {
  # can void
} else if ($transaction->status == BraintreeTransaction::SETTLED) {
  # will have to refund it
} else {
  # This example only expected one of the two above statuses
}

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.
proccessorResponseType	The processor response type. Possible values: `"approved"`, `"soft_declined"`, `"hard_declined"`. See the list of possible processor authorization responses.
proccessorResponseCode	The processor response code. See the list of possible processor authorization responses.
proccessorResponseText	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: authorizationExpired authorized authorizing settlementPending settlementConfirmed settlementDeclined failed gatewayRejected processorDeclined settled settling submittedForSettlement voided
timestamp	The date/time the status change was performed. Results are returned in UTC.
transactionSource	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.

PHP

$transaction = $gateway->transaction()->find('the_transaction_id');
foreach ($transaction->statusHistory as &$event) {
	 print_r($event->amount);
	 print_r($event->status);
	 print_r($event->timestamp);
	 print_r($event->transactionSource);
	 print_r($event->user);
}

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