Transaction.sale()

See also the Transaction response object.

To create a transaction, you must include an amount and either a paymentMethodNonce or a paymentMethodToken.

The following example creates a transaction using a paymentMethodNonce from a client and instructs that it should be submitted for settlement immediately using options.submitForSettlement. See more examples of transaction.sale() calls in our Transactions guide.

gateway.transaction.sale({
  amount: "10.00",
  paymentMethodNonce: nonceFromTheClient,
  options: {
    submitForSettlement: true
  }
}, function (err, result) {
});
Node.js
Parameters
amount
Required, String

The billing amount of the request. This value must be greater than 0, and must match the appropriate currency format.

billing

Billing address information associated with a specific customer ID.

AVS rules are not applied when creating a transaction from a Vault record using a payment method token. Braintree still submits the street address and postal code to the processor to run AVS checks. The transaction response includes processor AVS response codes.

company

Company name. 255 character maximum.

countryCodeAlpha2

The ISO 3166-1 alpha-2 country code specified in an address. The gateway only accepts specific alpha-2 values.

PayPal transactions must use the alpha-2 format. See PayPal's country code documentation for details.

countryCodeAlpha3

The ISO 3166-1 alpha-3 country code specified in an address. The gateway only accepts specific alpha-3 values.

countryCodeNumeric

The ISO 3166-1 numeric country code specified in an address. The gateway only accepts specific numeric values.

countryName

The country name specified in an address. Braintree only accepts specific country names.

extendedAddress

The extended address information—such as apartment or suite number. 255 character maximum.

firstName

The first name. The first name value must be less than or equal to 255 characters.

lastName

The last name. The last name value must be less than or equal to 255 characters.

locality

The locality/city. 255 character maximum.

postalCode

The postal code. Postal code must be a string of 5 or 9 alphanumeric digits, optionally separated by a dash or a space. Spaces, hyphens, and all other special characters are ignored.

region

The state or province. The region must be a 2-letter abbreviation and must be less than or equal to 255 characters.

streetAddress

The billing street address. Maximum 255 characters, and must contain at least 1 digit. Required when AVS rules are configured to require street address.

billingAddressId

The two-letter value for an address associated with a specific customer ID. The maximum number of addresses per customer is 50.

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 paypal.bn_code.

creditCard

Deprecated
We recommend using paymentMethodNonce to avoid any PCI concerns with raw credit card data being present on your server.

A credit or debit payment method.

cardholderName

The name associated with the credit card. Must be less than or equal to 175 characters.

cvv

A 3 or 4 digit card verification value assigned to credit cards.

To meet PCI guidelines, CVV will never be stored in the gateway. CVV is not required when creating a transaction from Vault tokens; CVV rules will be applied to transactions if and only if the CVV is supplied with the tokens.

CVV checking can also be done when you create or update the Vault record by using card verification.

expirationDate

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

expirationMonth
Number

The expiration month of a credit card, formatted MM. May be used with expiration_year, and instead of expiration_date.

expirationYear
Number

The two or four digit year associated with a credit card, formatted YYYY or YY. May be used with expiration_month, and instead of expiration_date.

number

The 12-19 digit value consisting of a bank identification number (BIN) and primary account number (PAN).

token

An alphanumeric value that references a specific payment method stored in your Vault. Must be less than or equal to 35 characters. If using a custom integration, you can specify what you want the token to be. If not specified, the gateway will generate one that can be accessed on the result. If using our Drop-in UI, you cannot specify your own token. Length and format of gateway-generated tokens and IDs may change at any time.

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.

customer

The object under which information specific to a customer—its payment methods, subscriptions, and more—can be defined. See the customer object for further detail.

company

Company name. 255 character maximum.

email

Email address comprised of ASCII characters.

fax

Fax number. 255 character maximum.

firstName

The first name. The first name value must be less than or equal to 255 characters.

id

The customer ID used to create the transaction. See the customer object for more details.

lastName

The last name. The last name value must be less than or equal to 255 characters.

phone

Phone number. Phone must be 10-14 characters and can only contain numbers, dashes, parentheses and periods.

website

Website URL. Must be less than or equal to 255 characters. Website must be well-formed. The URL scheme is optional.

customerId

The identification value of the customer. The value must be less than or equal to 36 characters. Valid characters are letters, numbers, - and _. The words "all" and "new" currently cannot be used.

descriptor

Dynamic Descriptors are not enabled on all accounts by default. If you receive a validation error of 92203, please contact us.

Dynamic descriptors are sent on a per-transaction basis. They can be used to define what will appear on your customers' credit card statements for a specific purchase. The more clear the description of your product, the less likely customers will issue chargebacks due to confusion or non-recognition.

See the dynamic descriptor example for additional information.

name

The value in the business name field of a customer's statement. Company name/DBA section must be either 3, 7 or 12 characters and the product descriptor can be up to 18, 14, or 9 characters respectively (with an * in between for a total descriptor name of 22 characters).

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. The URL must be 13 characters or shorter.

deviceData

Customer device information used by Advanced Fraud Tools. When used with one-time Vaulted PayPal transactions, this value will include a PayPal Correlation ID.

deviceSessionId

A unique alphanumeric identifier used by our Advanced Fraud Tools to link a device to transactions.

merchantAccountId

The merchant account ID used to create a transaction. Currency is also determined by merchant account ID. If no merchant account ID is specified, we will use your default merchant account.

options

Optional values that can be passed with a request.

addBillingAddressToPaymentMethod
bool

The option that determines whether the billing address information provided on the request should be added to the payment method specified.

holdInEscrow
bool

For Marketplace merchants only. This value specifies whether a transaction is held in escrow. See Escrow for more detail.

paypal

PayPal-specific options

customField

Variable passed directly to PayPal via the API for your own tracking purposes. Customers do not see this value, but you can see it in reports from your PayPal console. Unlike Braintree custom fields, this field does not need to be configured in the Braintree Control Panel, nor is the value stored in Braintree.

description

Description of the transaction that is displayed to customers in PayPal email receipts. Max 127 characters. Currently only available for our Vault flow and Ruby, Python, PHP, Node, and .NET.

storeInVault
bool

The option that determines whether the payment method should be stored in the Vault, regardless of the transaction's success.

storeInVaultOnSuccess
bool

The option that determines whether the payment method associated with the successful transaction should be stored in the Vault.

storeShippingAddressInVault
bool

The option that determines whether the shipping address information provided with the transaction should be associated with the customer ID specified. When passed, the payment method will always be stored in the Vault.

submitForSettlement
bool

The option that determines whether an authorized transaction is submitted for settlement.

orderId

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

paymentMethodNonce

One-time-use token that references a payment method provided by your customer, such as a credit card or PayPal account.

The nonce serves as proof that the user has authorized payment (e.g. credit card number or PayPal details). This should be sent to your server and used with any of Braintree's server-side client libraries that accept new or saved payment details. This can be passed instead of a payment_method_token parameter.

paymentMethodToken

An alphanumeric value that references a specific payment method stored in your Vault. Must be less than or equal to 35 characters. If using a custom integration, you can specify what you want the token to be. If not specified, the gateway will generate one that can be accessed on the result. If using our Drop-in UI, you cannot specify your own token. Length and format of gateway-generated tokens and IDs may change at any time.

purchaseOrderNumber

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

recurring
bool

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

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 charging a service fee and holding funds in escrow on Marketplace transactions.

shipping

Shipping address information associated with a specific customer ID.

company

Company name. 255 character maximum.

countryCodeAlpha2

The ISO 3166-1 alpha-2 country code specified in an address. The gateway only accepts specific alpha-2 values.

countryCodeAlpha3

The ISO 3166-1 alpha-3 country code specified in an address. The gateway only accepts specific alpha-3 values.

countryCodeNumeric

The ISO 3166-1 numeric country code specified in an address. The gateway only accepts specific numeric values.

countryName

The country name specified in an address. Braintree only accepts specific country names.

extendedAddress

The extended address information—such as apartment or suite number. 255 character maximum.

firstName

The first name. The first name value must be less than or equal to 255 characters.

lastName

The last name. The last name value must be less than or equal to 255 characters.

locality

The locality/city. 255 character maximum.

postalCode

The postal code. Postal code must be a string of 5 or 9 alphanumeric digits, optionally separated by a dash or a space. Spaces, hyphens, and all other special characters are ignored.

region

The state or province. The region must be a 2-letter abbreviation and must be less than or equal to 255 characters.

streetAddress

The street address. Street address must be less than or equal to 255 characters. Must contain at least 1 digit. Only required for verification when AVS rules are configured to require street address.

shippingAddressId

A shipping address associated with a specific customer ID. The maximum number of addresses per customer is 50.

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.

Examples

Full example

Here is an example of passing in everything possible.

Some parameters are mutually exclusive, so we'll show those in separate examples. If there is anything you want to store with the transaction details that we don't have a field for, you can always use custom fields.

gateway.transaction.sale({
  amount: "10.00",
  orderId: "order id",
  merchantAccountId: "aMerchantAccountId",
  paymentMethodNonce: nonceFromTheClient,
  customer: {
    firstName: "Drew",
    lastName: "Smith",
    company: "Braintree",
    phone: "312-555-1234",
    fax: "312-555-12346",
    website: "http://www.example.com",
    email: "drew@example.com"
  },
  billing: {
    firstName: "Paul",
    lastName: "Smith",
    company: "Braintree",
    streetAddress: "1 E Main St",
    extendedAddress: "Suite 403",
    locality: "Chicago",
    region: "IL",
    postalCode: "60622",
    countryCodeAlpha2: "US"
  },
  shipping: {
    firstName: "Jen",
    lastName: "Smith",
    company: "Braintree",
    streetAddress: "1 E 1st St",
    extendedAddress: "5th Floor",
    locality: "Bartlett",
    region: "IL",
    postalCode: "60103",
    countryCodeAlpha2: "US"
  },
  options: {
    submitForSettlement: true
  },
  channel: "MyShoppingCartProvider"
}, function (err, result) {
});
Node.js

If all the parameters are valid, a transaction will be created with a status of submitted_for_settlement and success? will return true.

result.success;
// true

result.transaction.type;
// 'credit'

result.transaction.status;
// 'submitted_for_settlement'
Node.js

Storing in Vault

If you would like to charge a new customer and store their payment method in the Vault at the same time, you can pass their customer ID. To store the customer details and credit card in the Vault only if the transaction is successful set the store_in_vault_on_success option to true.

gateway.transaction.sale({
  amount: '10.00',
  paymentMethodNonce: nonceFromTheClient,
  customer: {
    id: 'aCustomerId'
  },
  options: {
    storeInVaultOnSuccess: true
  }
}, function (err, result) {
});
Node.js

Using stored addresses

You can use addresses stored on a customer by passing the address's ID. This works for both the shipping address and billing address.

gateway.transaction.sale({
  customerId: "theCustomerId",
  amount: "10.00",
  billingAddressId: "AA",
  shippingAddressId: "AB"
}, function (err, result) {
});
Node.js

Custom fields

Whatever you configure as the API name for your custom fields will be used when setting them on the transaction. Here is an example of setting custom fields with API names of custom_field_one and custom_field_two.

gateway.transaction.sale({
  amount: "100.00",
  paymentMethodNonce: nonceFromTheClient,
  customFields: {
    customFieldOne: "value one",
    customFieldTwo: "value two"
  }
}, function (err, result) {
  if (result.success) {
    result.transaction.customFields;
    // {customFieldOne: "value one", customFieldTwo: "value two"}
  }
});
Node.js

Dynamic descriptors

gateway.transaction.sale({
  amount: "10.00",
  paymentMethodNonce: nonceFromTheClient,
  descriptor: {
    name: "company*my production",
    phone: "3125551212",
    url: "company.com"
  }
}, function (err, result) {
  result.transaction.descriptor.name;
  // "company*my production"

  result.transaction.descriptor.phone;
  // "3125551212"
});
Node.js

PayPal

Only the name of the descriptor will be passed for PayPal transactions. Before being passed, the value will be truncated to 22 characters to follow PayPal's descriptor character limit.

The payment information displayed to a customer in their PayPal account overview does not contain the dynamic descriptor. The information displayed there is data the merchant has configured with PayPal directly (e.g., business name, e-mail address, business contact details).

Marketplace

Any string up to 12 characters can be used; longer strings will be truncated. Your descriptor will start with "BT [MyDescriptor]" and end with a randomly generated six character string (e.g. 123abc) which identifies the sub merchant account:

BT *MyDescriptor123abc

The 6-character string is not accessible to the Sub Merchant. It is not needed in the API call to create a transaction. It cannot be changed, as it is required to be on each transaction we process for the Sub Merchant.

Hold a Marketplace transaction in escrow on creation

Upon creating a Marketplace transaction, you can specify that its funds should be held in escrow. These funds can then be released at your discretion. By default, funds are not held in escrow.

gateway.transaction.sale({
  amount: "100.00",
  merchantAccountId: "blue_ladders_store",
  paymentMethodNonce: nonceFromTheClient,
  options: {
    submitForSettlement: true,
    holdInEscrow: true,
  },
  serviceFeeAmount: "10.00"
}, function (err, result) {
});
Node.js

Still Have Questions?

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