Braintree_Transaction

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

Returned from:

Attributes
addOns
Array of Braintree_AddOn objects

The collection of add-ons associated with a subscription. Add-on details can only be managed within the Control Panel.

additionalProcessorResponse

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

amount
String

The billing amount of the request. This value must be greater than 0, must match the appropriate currency format, and cannot exceed the service fee amount (if applicable), the total amount authorized, or the total amount settled. If you settle an amount that is less than what was authorized, the transaction object will return the amount settled.

avsErrorResponseCode

This field will be populated if there was an error when checking AVS or the processing bank does not support AVS. If this value is null, you will see responses in both avsPostalCodeResponseCode and avsStreetAddressResponseCode.

avsPostalCodeResponseCode

This will be 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
avsStreetAddressResponseCode

This will be 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
billingDetails

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

company

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

countryCodeAlpha2

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

countryCodeAlpha3

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

countryCodeNumeric

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

countryName

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

extendedAddress

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

firstName

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

id

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.

lastName

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

locality

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

postalCode

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

region

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

streetAddress

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

channel

If the transaction request was created through a shopping cart provider or other 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.

createdAt
DateTime

The date/time the object was created.

creditCardDetails

The credit card details used to process this transaction. If the transaction was created using Vault tokens, then credit_card_details 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.

cardType

The type of the credit card. Possible values:

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

The cardholder name associated with the credit card.

commercial
enum

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

  • Braintree_CreditCard::COMMERCIAL_YES
  • Braintree_CreditCard::COMMERCIAL_NO
  • Braintree_CreditCard::COMMERCIAL_UNKNOWN
countryOfIssuance

The country that issued the credit card.

customerLocation

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

debit
enum

Whether the card is a debit card. Possible values:

  • Braintree_CreditCard::DEBIT_YES
  • Braintree_CreditCard::DEBIT_NO
  • Braintree_CreditCard::DEBIT_UNKNOWN
durbinRegulated
enum

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

  • Braintree_CreditCard::DURBIN_REGULATED_YES
  • Braintree_CreditCard::DURBIN_REGULATED_NO
  • Braintree_CreditCard::DURBIN_REGULATED_UNKNOWN
expirationDate

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

expirationMonth

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

expirationYear

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

healthcare
enum

Whether the card is a healthcare card. Possible values:

  • Braintree_CreditCard::HEALTHCARE_YES
  • Braintree_CreditCard::HEALTHCARE_NO
  • Braintree_CreditCard::HEALTHCARE_UNKNOWN
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).

issuingBank

The bank that issued the credit card.

last4

The last 4 digits of the credit card number.

maskedNumber

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

payroll
enum

Whether the card is a payroll card. Possible values:

  • Braintree_CreditCard::PAYROLL_YES
  • Braintree_CreditCard::PAYROLL_NO
  • Braintree_CreditCard::PAYROLL_UNKNOWN
prepaid
enum

Whether the card is a prepaid card. Possible values:

  • Braintree_CreditCard::PREPAID_YES
  • Braintree_CreditCard::PREPAID_NO
  • Braintree_CreditCard::PREPAID_UNKNOWN
token

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

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.

customFields

A collection of custom field/value pairs. Fields and values must be less than 255 characters. You must set up each custom field in the Control Panel prior to passing it with a request. Querying this value returns a collection of custom field values stored on the customer object.

customerDetails

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

company

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

email

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

fax

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

firstName

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

id

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

lastName

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

phone

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

website

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
  • A = Not Applicable
descriptor
name

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

phone

The value in the phone number field of a customer's statement. Phone must be 10-14 characters and can only contain numbers, dashes, parentheses and periods.

url

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

disbursementDetails

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.

fundsHeld

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

settlementAmount
String

The amount of the transaction in 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 by the appropriate team within Braintree.

discounts
Array of Braintree_Discount objects

A collection of discounts associated with this subscription. Discount details can only be managed within the Control Panel.

disputes

A collection of disputes associated with the transaction.

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

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

  • "hold_pending"
  • "held"
  • "release_pending"
  • "released"
  • "refunded"
europeBankAccount
accountHolderName

The name of the Europe bank account holder.

bic

The Bank Identifier Code used in the request. This value is not masked.

imageUrl

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

mandateAcceptedAt
DateTime

The date that the mandate was accepted by the customer.

mandateReferenceNumber

The value used to display the mandate to the customer. See our SEPA guide for more details.

maskedIban

A masked value that represents the International Bank Account Number used in the request. Only the first 2 characters representing the country of the IBAN and last 4 digits of the bank account number appear in clear text in the masked value. All other digits are replaced with asterisks.

The format of the IBAN and its length vary by the country that the IBAN belongs to. In addition to the standard values such as the country code, bank code, branch code, and account number, the IBAN could also contain the account type, a checksum constant, a national check digit, or a national identification number.

token

An alphanumeric value that references a specific payment method stored in your Vault. If not specified, the gateway will generate one that can be accessed on the result. Must be less than or equal to 35 characters. Length and format of gateway-generated tokens and IDs may change at any time.

gatewayRejectionReason

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

  • "avs"
  • "avs_and_cvv"
  • "cvv"
  • "duplicate"
  • "fraud"
  • "three_d_secure"
merchantAccountId

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

orderId

Use this field to pass additional information about the transaction, such as a PayPal invoice ID.

paymentInstrumentType

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

  • "credit_card"
  • "paypal_account"
  • "europe_bank_account"
  • "apple_pay_card"
  • "coinbase_account"
  • "android_pay_card"
paypalDetails
authorizationId

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

captureId

PayPal id for a transaction.

customField

Custom field/value pairs. Fields and values must be less than 255 characters. You must set up each custom field in the Control Panel prior to passing it with a request.

imageUrl

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

payerEmail

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.

payerFirstName

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

payerId

The identifier for the paypal account used in the request.

payerLastName

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

paymentId

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

refundId

PayPal id for a refund.

sellerProtectionStatus

Indicates whether a transaction qualifies for PayPal Seller Protection.

token

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.

transactionFeeAmount

The transaction fee amount of the Paypal transaction. Currently only available for Ruby, Python, PHP, Node, and .NET.

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

transactionFeeCurrencyIsoCode

The currency of the associated transaction fee. Currently only available for Ruby, Python, PHP, Node, and .NET.

planId

The plan identifier. Values can use only letters, numbers, -, and _. Plans must be created in the Control Panel.

processorAuthorizationCode

The authorization code returned by the processor.

processorResponseCode

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

processorResponseText

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

processorSettlementResponseCode

The status of the request to capture the funds.

  • 4000 - Settled
  • 4001 - Settlement Declined
  • 4002 - Settlement Pending
  • 4003 - Already Captured
  • 4004 - Already Refunded
  • 4005 - PayPal Risk Rejected
  • 4006 - Capture amount exceeded allowable limit
  • 4007 - Error Communicating with PayPal
processorSettlementResponseText

The text explanation of the above processor settlement response code.

purchaseOrderNumber

A Level II data field that can be used to pass a purchase order identification value of up to 17 ASCII characters.

recurring

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

refundIds

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

refundedTransactionId

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

riskData

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

decision

The risk decision. Possible values:

  • Not Evaluated
  • Approve
  • Review
  • Decline
id

The risk data identifier.

serviceFeeAmount
String

The portion of a Sub Merchant's transaction revenue that is routed to the Master Merchant account. If set, this value must be greater than 0, must match the appropriate currency format, and cannot exceed the transaction amount.

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

settlementBatchId

The identification value of the settlement batch in which the transaction was processed. See the transaction API requests section for details.

shippingDetails

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

company

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

countryCodeAlpha2

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

countryCodeAlpha3

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

countryCodeNumeric

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

countryName

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

extendedAddress

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

firstName

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

id

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.

lastName

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

locality

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

postalCode

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

region

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

streetAddress

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

status

Possible values:

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

See the transaction status explanations for details.

statusHistory

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

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

The end date for the current billing period. This gets adjusted each time the gateway attempts to charge the subscription. We do not adjust this date when automatically retrying charges.

billingPeriodStartDate

The start date for the current billing period. This gets adjusted each time the gateway attempts to charge the subscription. We do not adjust this date when automatically retrying charges.

subscriptionId

The value used to identify a specific subscription. If you do not specify an ID when creating a subscription, the gateway will generate a 6- or 7-character alphanumeric ID. When updating a subscription, you can only use tokens associated with the same customer that the subscription is currently associated with. Once canceled, a subscription cannot be edited or reactivated. You must create a new subscription.

taxAmount
String

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

taxExempt
bool

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

type

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

updatedAt
DateTime

The date/time the object was last updated.

voiceReferralNumber

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

Result Object

Read more about result objects.

Success

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

$result->success
# true

$transaction = $result->transaction;
$transaction->status
# "authorized"
PHP

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.

$transaction = $result->transaction;
$transaction->paymentInstrumentType == Braintree_PaymentInstrumentType::PAYPAL_ACCOUNT;
# false
$transaction->paymentInstrumentType == Braintree_PaymentInstrumentType::CREDIT_CARD;
# true
PHP

Unsuccessful result

Success will return false if validations prevent the transaction from being created, if the processor declines the transaction, or if the gateway rejects the transaction.

Validation errors

If any parameters are invalid, then the success will return false and the result object will contain validation errors indicating which parameters were invalid.

$result->success
# false

$result->errors->deepAll()
PHP

Processor declined

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

$result->success
# false

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

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

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

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.

$result->transaction->additionalProcessorResponse
# e.g. "05 : NOT AUTHORISED"
PHP

Processor settlement declined

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

$result->success
# false

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

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

$result->transaction->processorSettlementResponseText
# e.g. "Settlement Declined"
PHP

Gateway rejection

If the transaction is rejected by the gateway according to the configured AVS, CVV or duplicate processing rules or fraud rules you can check for a gateway rejection and a rejection reason.

$result->success
# false

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

$result->transaction->gatewayRejectionReason
# e.g. "cvv"
PHP

Risk data

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

$result->transaction->riskData->id
# "1SG23YHM4BT5"
$result->transaction->riskData->decision
# "Decline"
PHP

The possible values of the risk decision are Not Evaluated, Approve, Review, and Decline.

Params retrieval

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

$transaction->currencyIsoCode
# e.g. 'USD'
PHP

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.

$result = Braintree_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;
}
PHP

Processor settlement declined

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

$result->success
# false

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

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

$result->transaction->processorSettlementResponseText
# e.g. "Settlement Declined"
PHP

Voiding settlement

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

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

See Also


Still Have Questions?

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