Transaction

Transaction: Sale

RubySDK

• Current Braintree SDKs
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

See also the Transaction response object.

To create a transaction, you must include an amount and either a payment_method_nonce, a payment_method_token, or a customer_id. Passing a customer_id is equivalent to passing the payment_method_token of the customer's default payment method.

Braintree offers products that manage risk and fraud related to each transaction. These products can only be leveraged if there is adequate data to support the capabilities. The required data can be easily added during the Braintree SDK or Graph QL. integration, and must be done prior using risk products. For additional guidance go to Premium Fraud Management Tools.

The following example creates a transaction using a payment_method_nonce from a client and instructs that it should be submitted for settlement immediately using options.submit_for_settlement. You can see more examples, including using a vaulted payment method, below the parameter reference.

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :device_data => device_data_from_the_client,
  :options => {
    :submit_for_settlement => true
  }
)

if result.success?
  # See result.transaction for details
else
  # Handle errors
end

Parameters

Examples

Full example

Here is an example of passing in everything a typical merchant might use.

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.

Collect device data from the client and include the device_data_from_the_client in the transaction.

result = gateway.transaction.sale(
  :amount => "100.00",
  :order_id => "order id",
  :merchant_account_id => "a_merchant_account_id",
  :payment_method_nonce => nonce_from_the_client,
  :device_data => device_data_from_the_client,
  :customer => {
    :first_name => "Drew",
    :last_name => "Smith",
    :company => "Braintree",
    :phone => "312-555-1234",
    :fax => "312-555-1235",
    :website => "http://www.example.com",
    :email => "drew@example.com"
  },
  :billing => {
    :first_name => "Paul",
    :last_name => "Smith",
    :company => "Braintree",
    :street_address => "1 E Main St",
    :extended_address => "Suite 403",
    :locality => "Chicago",
    :region => "IL",
    :postal_code => "60622",
    :country_code_alpha2 => "US"
  },
  :shipping => {
    :first_name => "Jen",
    :last_name => "Smith",
    :company => "Braintree",
    :street_address => "1 E 1st St",
    :extended_address => "Suite 403",
    :locality => "Bartlett",
    :region => "IL",
    :postal_code => "60103",
    :country_code_alpha2 => "US"
  },
  :options => {
    :submit_for_settlement => true
  },
)

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"

Storing in Vault

When creating a transaction, you can also store the payment method in your Vault.

Existing customer with new payment method

To associate this transaction's payment method with an existing customer, pass a customer_id along with options.store_in_vault or options.store_in_vault_on_success as true.

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :customer_id => "the_customer_id",
  :options => {
    :store_in_vault_on_success => true
  }
)

New customer with new payment method

To store a payment method for a new customer, set options.store_in_vault or options.store_in_vault_on_success to true on your transaction. You can optionally specify customer parameters for your new customer, as well:

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :customer => {
    :id => "a_customer_id"
  },
  :options => {
    :store_in_vault_on_success => true
  }
)

note

The customer parameter should only be used when creating a new customer with a new payment method, and store_in_vault_on_success only vaults the payment method if the transaction is successful.

Using a vaulted payment method

You can create a transaction using a payment method stored in the Vault by passing a payment_method_token:

result = gateway.transaction.sale(
  :payment_method_token => "the_token",
  :amount => "10.00"
)

Or use customer_id, which will use the customer's default payment method:

result = gateway.transaction.sale(
  :customer_id => "the_customer_id",
  :amount => "10.00"
)

Using a CVV-only nonce

To transact with a CVV-only nonce, use both a nonce representing the CVV and a payment_method_token representing the vaulted payment method.

To collect a CVV-only nonce, use the client SDKs to tokenize only the CVV property. See an example in our Hosted Fields FAQ.

result = gateway.transaction.sale(
  :payment_method_token => "the_token",
  :payment_method_nonce => cvvOnlyNonceFromClient,
  :amount => "10.00"
)

Specify merchant account ID

To specify which merchant account to use, pass the merchant_account_id when creating the transaction.

result = gateway.transaction.sale(
  :amount => "10.00",
  :merchant_account_id => "your_merchant_account",
  :payment_method_nonce => nonce_from_the_client
)

If you don't specify the merchant account to use to process a transaction, Braintree will process it using your default merchant account.

Contact us if you would like to change which merchant account is default.

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.

result = gateway.transaction.sale(
  :customer_id => "the_customer_id",
  :amount => "10.00",
  :billing_address_id => "AA",
  :shipping_address_id => "AB"
)

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.

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :custom_fields => {
    :custom_field_one => "value one",
    :custom_field_two => "value two"
  }
)

if result.success?
  result.transaction.custom_fields
  #=> {:custom_field_one => "value one", :custom_field_two => "value two"}
end

Dynamic descriptors

Dynamic descriptors are typically composed of a name and phone number or URL. The name must include the business name, followed by a product name or identifier, separated by an asterisk (*). Depending on the type of transaction you're creating, the length/character limits may differ from those outlined above. For example, you can only specify up to 18 characters for dynamic descriptor names on Braintree Marketplace transactions. See below for details on Venmo, PayPal, and Braintree Marketplace dynamic descriptors.

Your processor may also restrict which descriptor values you can pass; certain processors allow you to pass URLs instead of phone numbers, while others accept only phone numbers or only names. If your processor supports URLs and you send both a phone number and URL, we will only pass the URL to the processor. Contact us for more information on your processor's specific requirements.

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :descriptor => {
    :name => "company*my product",
    :phone => "3125551212",
    :url => "company.com"
  }
)

result.transaction.descriptor.name
#=> "company*my product"

result.transaction.descriptor.phone
#=> "3125551212"

Venmo

Venmo only supports the dynamic descriptor name. Its format allows alpha-numeric characters and +-. (space included); any other characters will result in the dynamic descriptor name not being included in the full descriptor sent to the processor.

The full descriptor submitted to the processor is structured as follows:

• The default prefix of

  VENMO  *

  (Two whitespaces).
• The Business Name submitted in the Venmo application form.
• The Dynamic Descriptor Name submitted in the transaction.sale() or transaction.submit_for_settlement() call.

An example of a full descriptor with a valid dynamic descriptor name is: VENMO *AStore O-1234, where AStore is the Business Name and O-1234 is the Dynamic Descriptor Name. If the dynamic descriptor name contains invalid characters, e.g. 0#1234, the entire dynamic descriptor name will be ignored.

note

The full descriptor is limited to 22 characters. If this limit is exceeded, the Business Name and Dynamic Descriptor Name portion will be truncated as needed. If you want to change the Business Name of the descriptor, you can edit your Venmo profile via the Venmo Processing page in the Control Panel. This will also update the name displayed to customers in the Venmo app during transaction processing.

PayPal

The PayPal dynamic descriptor is limited to a total of 22 characters and includes the following elements:

• The default prefix of PAYPAL *
• Your PayPal hard descriptor*
• The product portion of your name (learn more below)

*Depending on your PayPal account setup, the PayPal hard descriptor may not be included in the dynamic descriptor. You can update the hard descriptor value from your PayPal console.

The name must meet the following guidelines:

• Must include your registered Doing Business As (DBA) name, followed by an asterisk and a product description
• The DBA portion must be 3, 7 or 12 characters long - this portion will be dropped from your dynamic descriptor

note

If the three parts of your dynamic descriptor combined exceed the 22 character limit, the name portion will automatically be truncated as needed.

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, email address, business contact details).

Braintree Marketplace

The only dynamic descriptor value we will pass for Braintree Marketplace transactions is the name you specify. We will not send any dynamic phone or url values to the processor, but we will pass the phone from the hard descriptor on your master merchant account.

The dynamic descriptor name can only contain the ASCII characters a-z, A-Z, the numbers 0-9, and the characters .-+ and spaces (it can't contain special characters like Ñ, ü, and é). The maximum length is 18 characters; we will truncate any longer strings. The descriptor we pass to the processor will start with "BT *", followed by the name you specify.

• If the specified name is 12 characters or fewer, the descriptor we pass to the processor will end with a randomly generated 6-character string (e.g. 123abc) which identifies the sub-merchant:

BT *MYDESCRIPTOR123abc

• If the specified name is 13 characters or greater, the descriptor we pass to the processor will not end with a randomly generated 6-character string:

BT *MYDESCRIPTORISLONG

note

The sub-merchant can't access the 6-character string—we automatically append it to the descriptor name after you submit the transaction request. The string can't be changed, as it is required in order to identify each transaction we process for the sub-merchant.

Hold a Braintree Marketplace transaction in escrow on creation

Upon creating a Braintree 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.

result = gateway.transaction.sale(
  :amount => "100.00",
  :merchant_account_id => "blue_ladders_store",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :submit_for_settlement => true,
    :hold_in_escrow => true
  },
  :service_fee_amount => "10.00"
)