Skip to main content

Braintree

Overview​

Gateway Website: https://www.braintreepayments.com/
Developer Documentation: https://developers.braintreepayments.com/
Default Currency: USD

Request Objects: BillingAddress, ShippingAddress, CreditCard, OrderInfo, SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of Braintree forwards request to the below endpoints

ActionProductionSandbox
Card Authorize, Card Purchasehttps://api.braintreegateway.com/merchants/{merchantId}/transactionshttps://api.sandbox.braintreegateway.com/merchants/{merchantId}/transactions
Card Capturehttps://api.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/submit_for_settlementhttps://api.sandbox.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/submit_for_settlement
Card Refundhttps://api.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/refundhttps://api.sandbox.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/refund
Card Voidhttps://api.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/voidhttps://api.sandbox.braintreegateway.com/merchants/{merchantId}/transactions/{transaction.id}/void

Supported Request Parameters​

* denotes a required field
Field NameTypeBraintree MappingNotes
gatewaystringN/ABraintree
merchantId*stringMerchantAccountIdThis is the unique identifier for your entire Braintree gateway account, including the multiple merchant accounts that may be in your gateway. Often referred to as the public ID or production ID, your Braintree merchant ID will be different for your production and sandbox gateways.
publicKey*stringPublicKeyThis is your Braintree user-specific public identifier. Each user associated with your Braintree gateway will have their own public key.
privateKey*stringPrivateKeyThis is your Braintree user-specific private identifier. Each user associated with your Braintree gateway will have their own private key. Your private key should not be shared outside the use of an API call.
testModebooleanEnvironmentTrue = SANDBOX, False = PRODUCTION
amountintAmountTransaction amount in whole units. Example: $10.00 USD should be sent as 1000
currencyCodestringCurrencyIsoCodeThe ISO currency code pertaining to the amount
orderIdstringOrderIdUse this field to pass additional information about the transaction
storestringCustomer.​IdA string value that will represent this specific customer in your Braintree Vault. If blank, CustomerId will be used instead. Additionally, if blank, Options.StoreInVault will be false. See Braintree documentation for additional information.
customerIdstringCustomer.​IdA string value that will represent this specific customer in your Braintree Vault.
emailstringCustomer.​EmailEmail address composed of ASCII characters. 255 character maximum
storeInVaultOnSuccessboolean (nullable)Options.​StoreInVaultOnSuccessThe option that determines whether the payment method associated with the successful transaction should be stored in the Braintree Vault.
submitForSettlementbooleanOptions.​SubmitForSettlementThe option that determines whether an authorized transaction is submitted for settlement. Always true for Purchase requests
holdInEscrowbooleanOptions.​HoldInEscrowFor Braintree Marketplace merchants only. This value specifies whether a transaction is held in escrow.
customFieldsobjectCustomFieldsA collection of custom field/value pairs. Fields and values must be formatted as strings or integers. See Braintree documentation for additional information.
userData1stringDeviceDataLegacy field for passing in DeviceData. Used only if DeviceData is empty
deviceDatastringDeviceDataCustomer device information. Required when using Advanced Fraud Management Tools, when creating one-time Vaulted PayPal transactions, and when creating Venmo transactions. See Braintree documentation for additional information.
merchantAccountIdstringMerchantAccountIdThe merchant account ID used to create a transaction. Currency is also determined by merchant account ID. If no merchant account ID is specified, Braintree will use your default Braintree merchant account.
transactionSourcestringTransactionSourceSpecifies the source of the transaction. The value passed depends on whether the transaction is initiated by the merchant or the customer. If empty, "recurring" or "unscheduled" are used, depending on the value of Recurring
recurringbooleanTransactionSourceIf TransactionSource is empty, True = "recurring", False = "unscheduled"
channelstringChannelFor Braintree partners and shopping carts only. If you are a shopping cart provider or other Braintree partner, pass a string identifier for your service. For PayPal transactions, this maps to paypal.bn_code.
paymentMethodTokenstringPaymentMethodTokenAn alphanumeric value that references a specific payment method stored in your Braintree Vault. Must be less than or equal to 36 characters. See Braintree documentation for additional information.
paymentMethodNoncestringPaymentMethodNonceOne-time-use reference to payment information provided by your customer, such as a credit card or PayPal account. Can be passed instead of a PaymentMethodToken parameter.
creditCard.​FirstNamestringCustomer.​FirstNameThe first name of the cardholder. CreditCard.FirstName and CreditCard.LastName are concatenated and filled into the CreditCard.CardHolderName property of the Braintree request
creditCard.​LastNamestringCustomer.​LastNameThe last name of the cardholder. CreditCard.FirstName and CreditCard.LastName are concatenated and filled into the CreditCard.CardHolderName property of the Braintree request
creditCard.​Numberstring / TokenCreditCard.​NumberCard number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
creditCard.​CVVstringCreditCard.​CVVThe three- or four-digit number on the back of a credit card (on the front for American Express).

This field is required if the merchant would like to use the Card Code Verification (CCV) security feature.

Cardholder information must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.
creditCard.​ExpMonthnumericCreditCard.​ExpirationMonthThe two-digit expiration month of the card. Example: 01
creditCard.​ExpYearnumericCreditCard.​ExpirationYearThe four-digit expiration year of the card. Example: 2022
threeDSecure.​AuthenticationRequiredbooleanOptions.ThreeDSecure.​RequiredIndicates whether the Braintree request should be validated as a 3DS-enabled transaction. More information
threeDSecure.​ThreeDSecureAuthenticationIdstringThreeDSecureAuthenticationIdID of the 3D Secure authentication performed for this transaction. Do not provide this field if you are using a nonce for this transaction that is 3D Secure enriched.
threeDSecure.​CAVVstringThreeDSecurePassThru.​CavvThe Cardholder Authentication Verification Value (CAVV) for a Visa transaction, or Accountholder Authentication Value (AVV)/ Universal Cardholder Authentication Field indicator (UCAF) for a Mastercard transaction. The cardholder authentication process generates the CAVV, AAV, or UCAF value prior to submitting the transaction.
threeDSecure.​DSTransIdstringThreeDSecurePassThru.​DsTransactionIdTransaction identifier resulting from 3D Secure 2 authentication. This field must be supplied for Mastercard Identity Check.
threeDSecure.​ECIstringThreeDSecurePassThru.​EciFlagThe Electronic Commerce Indicator (ECI) value for a Visa transaction, or the Universal Cardholder Authentication Field indicator (UCAF) for a Mastercard transaction. The cardholder authentication process generates the ECI or UCAF value prior to submitting the transaction.
threeDSecure.​ThreeDSecureVersionstringThreeDSecurePassThru.​ThreeDSecureVersionThe version of 3D-Secure used for authentication. 1 (for 2.1.0) or 2 (for 2.2.0). Values not "1" or "2" are forwarded to Braintree unmodified.
threeDSecure.​XidstringThreeDSecurePassThru.​XidTransaction identifier resulting from 3D Secure authentication. Uniquely identifies the transaction and sometimes required in the authorization message. Must be base64-encoded. No longer used in 3D Secure 2 authentications.
shippingAddress.​Address1stringShippingAddress.​StreetAddressCustomer’s shipping address.
shippingAddress.​Address2stringShippingAddress.​ExtendedAddressCustomer’s shipping address, line 2.
shippingAddress.​CompanystringShippingAddress.​CompanyCompany associated with customer’s shipping address.
shippingAddress.​CitystringShippingAddress.​LocalityCity of customer’s shipping address.
shippingAddress.​StatestringShippingAddress.​RegionState of customer’s shipping address.
shippingAddress.​ZipstringShippingAddress.​PostalCodePostal code of customer’s shipping address.
shippingAddress.​CountrystringShippingAddress.​CountryCodeAlpha3Alpha-3 ISO country code
billingAddress.​Address1stringBillingAddress.​StreetAddressCustomer’s billing address. BillingAddress is mapped if not using a PaymentMethodToken
billingAddress.​Address2stringBillingAddress.​ExtendedAddressSecond line of customer’s billing address.
billingAddress.​CompanystringBillingAddress.​CompanyCompany associated with customer’s billing address.
billingAddress.​CitystringBillingAddress.​LocalityCity of customer’s billing address.
billingAddress.​StatestringBillingAddress.​RegionState of customer’s billing address.
billingAddress.​ZipstringBillingAddress.​PostalCodePostal code of customer’s billing address.
billingAddress.​CountrystringBillingAddress.​CountryCodeAlpha3Alpha-3 ISO country code
softDescriptors.​MerchantNamestringDescriptor.​NameDynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. See Braintree documentation for additional information
softDescriptors.​MerchantPhonestringDescriptor.​PhoneThe phone number that will appear on your customers' credit card statements for a specific purchase. See Braintree documentation for additional information
softDescriptors.​MerchantUrlstringDescriptor.​UrlThe URL that will appear on your customers' credit card statements for a specific purchase. See Braintree documentation for additional information
orderInfo.​PurchaseOrderNumberstringPurchaseOrderNumberThe PO number for the order.
tax.​ExemptbooleanTaxExemptOrder's tax-exempt status.
tax.​AmountintTaxAmountTax amount in whole units. Example: $10.00 USD should be sent as 1000
storedCredentials.​InitiatorstringunmappedIf "cardholder", TransactionSource is auto-populated with "recurring_first".
storedCredentials.​CredentialStoredbooleanExternalVault.​StatusSee usage in The Basics - Stored Credentials. True = "vaulted", False = "will_vault".
storedCredentials.​PreviousNetworkTransactionIdstringExternalVault.​PreviousNetworkTransactionIdSee usage in The Basics - Stored Credentials. Value obtained from Braintree response field Target.NetworkTransactionId.
storedCredentials.​TransactionTypestringTransactionSourceSee storedCredentials.Initiator.
valid values:
"recurring" = "recurring"
"unscheduled" = "unscheduled"
any other string value = forwarded. See Braintree documentation

Example Requests​

{
  "publicKey": "<Your Braintree Public Key>",
  "privateKey": "<Your Braintree Private Key>",
  "merchantId": "<Your Braintree Merchant ID>",
  "orderId": "81553724",
  "email": "[email protected]",
  "merchantAccountId": "<Your Braintree Merchant Account ID>",
  "creditCard": {
    "brand": "Visa",
    "number": "4111111111111111",
    "expMonth": 6,
    "expYear": 2024,
    "firstName": "John",
    "lastName": "Doe",
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "fax": "555-555-6666",
    "firstName": "John",
    "lastName": "Doe",
    "name": "John Doe",
    "company": "Test Co.",
    "address1": "123 Someplace Lane",
    "address2": null,
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  },
  "amount": 1200,
  "gateway": "Braintree"
}

Gateway Response Parameters​

Field NameTypeBraintree Result MappingNotes
approvalCodestringTarget.​ProcessorAuthorizationCodeA six-character pseudo-ID from the processing network.
approvedbooleanIsSuccessTrue if the transaction result is successful, false if it failed
providerTransactionCodestringTarget.​Id
Transaction.​Id		Transaction ID of the newly run transaction
tokenexTransactionCodestringTarget.​IdBase64 encoded Braintree gateway response field Target.Id
networkTransactionIdstringTarget.​NetworkTransactionId
Transaction.​NetworkTransactionId		The network transaction identifier provided by the payment network.
merchantReferenceIdstringTarget.​OrderId
Transaction.​OrderId		The order ID of the transaction.
customerProfileIdstringTarget.​Customer.Id
Transaction.​Customer.Id		Reference value that is associated with the customer's at the time of the transaction.
gatewayTokenstringTarget.​CreditCard.TokenThe Braintree vault token for the credit card
brandAuthResponseCodestringTarget.​NetworkResponseCodeDecline code at the card brand level. Also known as Issuer Response Codes.
brandAuthResponseCodeDescriptionstringTarget.​NetworkResponseTextThe description for the Brand authorization response code.
recurringAdviceCodestringTarget.​MerchantAdviceCodeCode provided by the card network offering a suggestion of when the transaction should be retried. Currently this value is only provided by MasterCard as the Merchant Advice Code (MAC Code).
recurringAdviceDescriptionstringTarget.​MerchantAdviceCodeTextThe description for the Retry Advice Code.
verificationResult.CvvRawstringTarget.​CvvResponseCode
Transaction.​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
verificationResult.ProviderParsed.AvsstringTarget.​AvsErrorResponseCode
Transaction.​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
verificationResult.ProviderParsed.StreetMatchstringTarget.​AvsStreetAddressResponseCode
Transaction.​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
verificationResult.ProviderParsed.PostalCodeMatchstringTarget.​AvsPostalCodeResponseCode
Transaction.​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

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\"Target\":{\"Id\":\"b781pn2z\",\"AddOns\":[],\"Amount\":917.01,\"AvsPostalCodeResponseCode\":\"M\",\"AvsStreetAddressResponseCode\":\"M\",\"BillingAddress\":{\"Company\":\"Test Co.\",\"StreetAddress\":\"123 Someplace Lane\",\"ExtendedAddress\":\"Some Place\",\"Locality\":\"Tulsa\",\"Region\":\"OK\",\"PostalCode\":\"74111\",\"CountryCodeAlpha2\":\"US\",\"CountryCodeAlpha3\":\"USA\",\"CountryCodeNumeric\":\"840\",\"CountryName\":\"United States of America\"},\"Channel\":\"TokenEx_SP\",\"CreatedAt\":\"2023-12-04T13:47:28Z\",\"CreditCard\":{\"Bin\":\"400000\",\"CardholderName\":\"John Doe\",\"CardType\":14,\"IsVenmoSdk\":false,\"IsNetworkTokenized\":false,\"CustomerLocation\":0,\"LastFour\":\"1000\",\"Subscriptions\":[],\"BillingAddress\":{},\"ExpirationMonth\":\"01\",\"ExpirationYear\":\"2025\",\"Prepaid\":2,\"Payroll\":2,\"Debit\":2,\"Commercial\":2,\"Healthcare\":2,\"DurbinRegulated\":2,\"ImageUrl\":\"https://assets.braintreegateway.com/payment_method_logo/visa.png?environment=sandbox\",\"AccountType\":\"credit\",\"CountryOfIssuance\":\"Unknown\",\"IssuingBank\":\"Unknown\",\"ProductId\":\"Unknown\",\"ExpirationDate\":\"01/2025\",\"MaskedNumber\":\"400000******1000\"},\"CurrencyIsoCode\":\"USD\",\"CustomerDetails\":{\"FirstName\":\"John\",\"LastName\":\"Doe\"},\"CvvResponseCode\":\"M\",\"Descriptor\":{},\"Discounts\":[],\"Disputes\":[],\"GatewayRejectionReason\":9,\"GraphQLId\":\"dHJhbnNhY3Rpb25fYjc4MXBuMno\",\"MerchantAccountId\":\"tokenex\",\"ProcessedWithNetworkToken\":false,\"ProcessorAuthorizationCode\":\"4VGBS3\",\"ProcessorResponseType\":0,\"ProcessorResponseCode\":\"1000\",\"ProcessorResponseText\":\"Approved\",\"NetworkResponseCode\":\"XX\",\"NetworkResponseText\":\"sample network response text\",\"Recurring\":false,\"RefundIds\":[],\"PartialSettlementTransactionIds\":[],\"ShippingAddress\":{\"Company\":\"Test Co.\",\"StreetAddress\":\"123 Someplace Lane\",\"ExtendedAddress\":\"Some Place\",\"Locality\":\"Tulsa\",\"Region\":\"OK\",\"PostalCode\":\"74111\",\"CountryCodeAlpha2\":\"US\",\"CountryCodeAlpha3\":\"USA\",\"CountryCodeNumeric\":\"840\",\"CountryName\":\"United States of America\"},\"EscrowStatus\":5,\"Status\":1,\"StatusHistory\":[{\"Amount\":917.01,\"Status\":1,\"Timestamp\":\"2023-12-04T13:47:28Z\",\"Source\":0,\"User\":\"tmaguire\"}],\"AuthorizationAdjustments\":[],\"SubscriptionDetails\":{},\"TaxExempt\":false,\"Type\":1,\"UpdatedAt\":\"2023-12-04T13:47:28Z\",\"CustomFields\":{},\"DisbursementDetails\":{},\"PaymentInstrumentType\":2,\"NetworkTransactionId\":\"020231204134728\",\"AuthorizationExpiresAt\":\"2023-12-05T13:47:28Z\",\"RetrievalReferenceNumber\":\"1234567\",\"Installments\":[],\"RefundedInstallments\":[],\"Retried\":false}}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "Yjc4MXBuMno=",
    "approvalCode": "4VGBS3",
    "providerTransactionCode": "b781pn2z",
    "approved": true,
    "verificationResult": {
      "cvvRaw": "M",
      "providerParsed": {
        "streetMatch": "M",
        "postalCodeMatch": "M"
      }
    },
    "networkTransactionId": "020231204134728"
  },
  "referenceNumber": "23120407472778674556",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on