See also the Transaction response object.

To create a transaction, you must include an amount and either a payment_method_nonce or a payment_method_token.

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. See more examples of transaction sales calls in our Transactions guide.

Python
result = braintree.Transaction.sale({
    "amount": "10.00",
    "payment_method_nonce": nonce_from_the_client,
    "options": {
        "submit_for_settlement": True
    }
})
Parameters
'amount'
required, Decimal or str

The billing amount of the request. This value must be greater than 0, and must match the currency format of the merchant account. Cannot be greater than the maximum allowed by the processor. Contact our Support team for your specific limit.

'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'
str

Company name. 255 character maximum.

'country_code_alpha2'
str

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.

'country_code_alpha3'
str

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

'country_code_numeric'
str

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

'country_name'
str

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

'extended_address'
str

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

'first_name'
str

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

'last_name'
str

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

'locality'
str

The locality/city. 255 character maximum.

'postal_code'
str

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'
str

The state or province. For PayPal addresses, the region must be a 2-letter abbreviation; for all other payment methods, it must be less than or equal to 255 characters.

'street_address'
str

The billing street address. 255 character maximum. Required when AVS rules are configured to require street address.

'billing_address_id'
str

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

'channel'
str

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

'credit_card'

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

A credit or debit payment method.

'cardholder_name'
str

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

'cvv'
str

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.

'expiration_date'
str

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

'expiration_month'
int

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

'expiration_year'
int

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'
str

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

'token'
str

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.

'custom_fields'

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'
str

Company name. 255 character maximum.

'email'
str

Email address comprised of ASCII characters.

'fax'
str

Fax number. 255 character maximum.

'first_name'
str

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

'id'
str

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

'last_name'
str

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

'phone'
str

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

'website'
str

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

'customer_id'
str

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 or if your dynamic descriptors are not displaying as expected, please contact us.

Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. The clearer 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'
str

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'
str

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'
str

The value in the URL/web address field of a customer's statement. The URL must be 13 characters or shorter.

'device_data'
str

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

'device_session_id'
str

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

'merchant_account_id'
str

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.

'add_billing_address_to_payment_method'
bool

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

'hold_in_escrow'
bool

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

'paypal'

PayPal-specific options

'custom_field'
str

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'
str

Description of the transaction that is displayed to customers in PayPal email receipts. Max 127 characters.

'store_in_vault'
bool

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

'store_in_vault_on_success'
bool

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

'store_shipping_address_in_vault'
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.

'submit_for_settlement'
bool

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

'three_d_secure'

Options for 3D Secure verification. Can only be used when the payment method nonce parameter is present.

'required'
required, bool

Specify whether to require the 3D Secure verification to pass before performing transaction. We recommend this is always set to true for merchants using 3D Secure. For more inforation see the server-side implementation guide.

'order_id'
str

Use this field to pass additional information about the transaction. On PayPal transactions, this field maps to the PayPal invoice ID. PayPal invoice IDs must be unique in your PayPal business account.

'payment_method_nonce'
str

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.

'payment_method_token'
str

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.

'purchase_order_number'
str

A Level II data field that can be used to pass a purchase order identification value of up to 12 ASCII characters for AIB and 17 ASCII characters for all other processors.

'recurring'
bool

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

'service_fee_amount'
Decimal or str

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 or equal to 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'
str

Company name. 255 character maximum.

'country_code_alpha2'
str

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

'country_code_alpha3'
str

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

'country_code_numeric'
str

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

'country_name'
str

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

'extended_address'
str

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

'first_name'
str

The first name. The first name value must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'last_name'
str

The last name. The last name value must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'locality'
str

The locality/city. 255 character maximum. Required if passing a PayPal shipping address.

'postal_code'
str

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. Required if passing a PayPal shipping address.

'region'
str

The state or province. For PayPal addresses, the region must be a 2-letter abbreviation; for all other payment methods, it must be less than or equal to 255 characters. Required if passing a PayPal shipping address.

'street_address'
str

The street address. 255 character maximum. Only required for verification when AVS rules are configured to require street address. Required if passing a PayPal shipping address.

'shipping_address_id'
str

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

'tax_amount'
Decimal or str

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.

'tax_exempt'
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 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.

Python
result = braintree.Transaction.sale({
  "amount": "10.00",
  "order_id": "order id",
  "merchant_account_id": "a_merchant_account_id",
  "payment_method_nonce": nonce_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.

Python
result.is_success
# True

result.transaction.type
# "credit"

result.transaction.status
# "submitted_for_settlement"

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.

Python
result = braintree.Transaction.sale({
  "amount": "10.00",
  "payment_method_nonce": nonce_from_the_client,
  "customer": {
    "id": "a_customer_id"
  },
  "options": {
    "store_in_vault_on_success": True,
  }
})

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.

Python
result = braintree.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.

Python
result = braintree.Transaction.sale({
    "amount": "100.00",
    "payment_method_nonce": nonce_from_the_client,
    "custom_fields": {
        "custom_field_one": "value one",
        "custom_field_two": "value two"
    }
})

if result.is_success:
    result.transaction.custom_fields
    # {"custom_field_one": "value one", "custom_field_two": "value two"}

Dynamic descriptors

Dynamic descriptors are typically comprised of a name and phone number or URL. The name generally includes both the business name and product name, 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 Marketplace transactions. See below for details on PayPal and 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 Support for more information on your processor's specific requirements.

Python
result = braintree.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"

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

Marketplace

The only dynamic descriptor value we will pass for 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.

For the dynamic descriptor name, you can use any string up to 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

The sub-merchant cannot access the 6-character string—we automatically append it to the descriptor name after you submit the transaction request. The string cannot be changed, as it is required in order to identify 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.

Python
result = braintree.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"
})

Still Have Questions?

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