Braintree_Transaction::sale()

See also the Braintree_Transaction response object.

Create a transaction using payment information. For example, you can create a transaction using a paymentMethodNonce from a client and instruct that it should be submitted for settlement immediately using options.submitForSettlement.

$result = Braintree_Transaction::sale([
  'amount' => '100.00',
  'paymentMethodNonce' => nonceFromTheClient,
  'options' => [
    'submitForSettlement' => True
  ]
]);
PHP
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 transcation 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'
int

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

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

The 12-19 digit value consisting of a bank identification number (BIN) and personal identification 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.

'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 for your own tracking purposes, which buyers do not see. This value is not stored in the Braintree Vault.

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

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

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

$result = Braintree_Transaction::sale([
  'amount' => '100.00',
  'orderId' => 'order id',
  'merchantAccountId' => 'a_merchant_account_id',
  'paymentMethodNonce' => nonceFromTheClient,
  'customer' => [
    'firstName' => 'Drew',
    'lastName' => 'Smith',
    'company' => 'Braintree',
    'phone' => '312-555-1234',
    'fax' => '312-555-1235',
    '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' => 'Suite 403',
    'locality' => 'Bartlett',
    'region' => 'IL',
    'postalCode' => '60103',
    'countryCodeAlpha2' => 'US'
  ],
  'options' => [
    'submitForSettlement' => true
  ],
  'channel' => 'MyShoppingCartProvider'
]);
PHP

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->status
# e.g. 'submitted_for_settlement'

$result->transaction->type
# e.g. 'credit'
PHP

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.

$result = Braintree_Transaction::sale([
  'amount' => '10.00',
  'paymentMethodNonce' => nonceFromTheClient,
  'customer' => [
    'id' => 'a_customer_id'
  ],
  'options' => [
    'storeInVaultOnSuccess' => true,
  ]
]);
PHP

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 = Braintree_Transaction::sale(
  [
    'customerId' => 'the_customer_id',
    'amount' => '100.00',
    'billingAddressId' => 'AA',
    'shippingAddressId' => 'AB'
  ]
);
PHP

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 = Braintree_Transaction::sale([
    'amount' => '100.00',
    'paymentMethodNonce' => nonceFromTheClient,
    'customFields' => [
        'custom_field_one' => 'custom value',
        'custom_field_two' => 'another custom value'
    ]
]);

$result->transaction->customFields['custom_field_one']
# 'custom value'

$result->transaction->customFields['custom_field_two']
# 'another custom value'
PHP

Dynamic descriptors

$result = Braintree_Transaction::sale([
    'amount' => '10.00',
    'paymentMethodNonce' => nonceFromTheClient,
    'descriptor' => [
        'name' => 'company*my product',
        'phone' => '3125551212',
        'url' => 'company.com'
    ]
]);
$result->transaction->descriptor->name
# 'company*my product'

$result->transaction->descriptor->phone
# '3125551212'
PHP

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.

$result = Braintree_Transaction::sale(
  [
    'amount' => '100.00',
    'merchantAccountId' => 'blue_ladders_store',
    'paymentMethodNonce' => nonceFromTheClient,
    'options' => [
      'submitForSettlement' => true,
      'holdInEscrow' => true,
    ],
    'serviceFeeAmount' => "10.00"
  ]
)
PHP