See also the Transaction response object.

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

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. You can see more examples, including using a vaulted payment method, below the parameter reference.

PHP
Copy
Copied
$result = $gateway->transaction()->sale([
  'amount' => '10.00',
  'paymentMethodNonce' => nonceFromTheClient,
  'options' => [
    'submitForSettlement' => True
  ]
]);

if ($result->success) {
  // See $result->transaction for details
} else {
  // Handle errors
}
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.
Parameters
'amount' required, String

The billing amount of the request. This value must be greater than 0, and must match the currency format of the merchant account. Can only contain numbers and one decimal point (e.g. x.xx). Can't 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. We still submit the street address and postal code to the processor to run AVS checks. The transaction response includes processor AVS response codes.

'company' string

Company name. 255 character maximum.

'countryCodeAlpha2' string

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

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

'countryCodeNumeric' string

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

'countryName' string

The country name specified in an address. We only accept specific country names.

'extendedAddress' string

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

'firstName' string

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

'lastName' string

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

'locality' string

The locality/city. 255 character maximum.

'postalCode' string

The postal code. Postal code must be a string of 4-9 alphanumeric characters, optionally separated by a dash or a space. Spaces and hyphens are ignored.

'region' string

The state or province. For PayPal addresses, the region must meet PayPal's state restrictions; for all other payment methods, it must be less than or equal to 255 characters.

'streetAddress' string

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

'billingAddressId' string

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

'channel' string

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.

'creditCard'

Typically requires PCI SAQ D compliance

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

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

'cvv' string

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

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

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

'token' string

An alphanumeric value that references a specific payment method stored in your Vault. Must be less than or equal to 36 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 with a customer ID to vault payment methods, you can't 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 formatted as strings or integers. Maximum 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 transaction object.

'customer'

When storing a new customer in the Vault, you can use this object to specify the customer's details. Only use this parameter when creating a new customer with a new payment method. See the customer object for further detail.

'company' string

Company name. 255 character maximum.

'email' string

Email address composed of ASCII characters. 255 character maximum.

'fax' string

Fax number. 255 character maximum.

'firstName' string

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

'id' string

A string value that will represent this specific customer in your Vault. 36 character maximum; must be unique within your Vault; valid characters are letters, numbers, -, and _; the words "all" and "new" currently can't be used. If not specified on creation, the gateway will generate an alphanumeric ID that can be accessed on the result. The generated IDs will never start with a leading 0 and are case insensitive.

'lastName' string

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

'phone' string

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

'website' string

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

'customerId' string

A string value representing an existing customer in your Vault that you want to charge.

'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 our Support team.

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

The value in the business name field of a customer's statement. The specific length/character requirements for this value depend on your processor. Contact our Support team for assistance.

'phone' string

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

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

'deviceData' string

Customer device information. Required when creating transactions on the following payment method types:

This value will contain a Fraud Merchant ID as the unique, numeric identifier for a Kount account and a Device Session ID as the unique identifier for a customer device. For PayPal and Venmo transactions, this value will also include a PayPal Correlation ID. Provide the full string received from the Braintree client SDK.

'deviceSessionId' string

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

'discountAmount' String

A Level 3 field that specifies the discount amount that was included in the total transaction amount. It can't be negative, and it does not add to the total transaction amount.

'externalVault'

Options used to indicate when a payment method is externally vaulted. These fields should be provided when storing a customer's payment methods in an external vault (e.g. third-party vault, not tokenizing through Braintree).

'previousNetworkTransactionId' string

Network transaction identifier issued by the card brand network during a previous transaction. Currently only applicable for Visa payment methods. Visa provides network transaction identifiers to improve authorization approval rates for stored credential transactions.

'status' string

The option indicates the vaulted status of the externally vaulted payment method. Accepted values:

  • vaulted = Indicates the payment method is already stored on behalf of the customer.
  • will_vault = Indicates the payment method is intended to be vaulted upon successful processing of the transaction.
'lineItems'

The line items for this transaction. It can include up to 249 line items. If your merchant account has been configured Level 3 processing this field will be passed to processor on your behalf.

'commodityCode' string

Code used to classify items purchased and track the total amount spent across various categories of products and services. Different corporate purchasing organizations may use different standards, but the United Nations Standard Products and Services Code (UNSPSC) is frequently used. Maximum 12 characters.

'description' string

Item description. Maximum 127 characters.

'discountAmount' String

Discount amount for the line item. Can include up to 2 decimal places. This value can't be negative.

'kind' required, string

Indicates whether the line item is a debit (sale) or credit (refund) to the customer. Accepted values:

  • "debit"
  • "credit"
'name' required, string

Item name. Maximum 35 characters, or 127 characters for PayPal transactions.

'productCode' string

Product or UPC code for the item. Maximum 12 characters, or 127 characters for PayPal transactions.

'quantity' required, String

Number of units of the item purchased. Can include up to 4 decimal places. This value can't be negative or zero.

'taxAmount' String

Tax amount for the line item. Can include up to 2 decimal places. This value can't be negative.

'totalAmount' required, String

Quantity x unit amount. Can include up to 2 decimal places.

'unitAmount' required, String

Per-unit price of the item. Can include up to 4 decimal places. This value can't be negative or zero.

'unitOfMeasure' string

The unit of measure or the unit of measure code. Maximum 12 characters.

'unitTaxAmount' String

Per-unit tax price of the item. Can include up to 2 decimal places. This value can't be negative or zero.

'url' string

The URL to product information.

'merchantAccountId' string

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 in the request should be added to the payment method specified. This option works only for new payment methods.

'holdInEscrow' bool

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

'paypal'

PayPal-specific options.

'customField' string

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. It also appears in the Braintree Control Panel on the Transaction Details page of the associated PayPal transaction, and in the CSV file of downloaded transaction searches. Unlike Braintree custom fields, this field does not need to be configured in the Braintree Control Panel.

'description' string

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

'skipAdvancedFraudChecking' boolean

Prevents the transaction from being sent to Kount for evaluation as part of Advanced Fraud Tools checks. Use with caution – once you've skipped checks for a transaction, it is not possible to run them retroactively.

'skipAvs' boolean

Skip AVS checks for the transaction. Will result in a processor response code of B for avsPostalCodeResponseCode and avsStreetAddressResponseCode, and nil for avsErrorResponseCode. Use with caution – once you've skipped checks for a transaction, it is not possible to run them retroactively.

'skipCvv' boolean

Skip CVV checks for the transaction. Will result in a processor response code of B for cvvResponseCode. Use with caution – once you've skipped checks for a transaction, it is not possible to run them retroactively.

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

If there is already a shipping address associated with the customer, this parameter will not replace the existing information; an additional address will be stored instead. You can associate up to 50 addresses with a single customer ID.

'submitForSettlement' bool

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

'threeDSecure'

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

'required' bool

Specify whether to require 3D Secure verification to succeed before creating a transaction. Defaults to true for all transactions sent through 3D Secure verification unless you explicitly pass false. For more information, see 3D Secure advanced server-side options.

'venmo'

Options for a Pay with Venmo transaction.

'profileId' string

Specify which Venmo business profile to use for a transaction.

'orderId' string

Use this field to pass additional information about the transaction. On PayPal transactions, this field maps to the PayPal invoice number. PayPal invoice numbers must be unique in your PayPal business account. Maximum 255 characters or 127 for PayPal transactions.

'paymentMethodNonce' string

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

'paymentMethodToken' string

An alphanumeric value that references a specific payment method stored in your Vault. Must be less than or equal to 36 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 with a customer ID to vault payment methods, you can't specify your own token. Length and format of gateway-generated tokens and IDs may change at any time.

'purchaseOrderNumber' string

A Level 2 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

Deprecated.

We recommend using transactionSource with a value of recurring.

A value indicating whether the transaction is being passed with a recurring ecommerce indicator (ECI) flag. If passed, the amount submitted for settlement must exactly match the authorized amount.

AVS and CVV rules do not apply to recurring payments.

'riskData'

Customer device information, which is sent directly to supported processors for fraud analysis. These fields are automatically populated if using Advanced Fraud Tools. Currently only available when processing American Express via Amex Direct. Contact our Support team with any questions.

'customerBrowser' string

The User-Agent header provided by the customer's browser, which gives information about the browser. Maximum 255 characters.

'customerIp' string

The customer's IP address.

'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 or equal to 0, must match the appropriate currency format, and can't exceed the transaction amount.

Available to Braintree Marketplace merchants. See charging a service fee and holding funds in escrow on Braintree Marketplace transactions.

'sharedBillingAddressId' string

For Shared Vault only

The ID of an address belonging to the OAuth application owner. If used in conjunction with a sharedCustomerId, must belong to the specified customer.

'sharedCustomerId' string

For Shared Vault only

The ID of a customer belonging to the OAuth application owner. If no sharedPaymentMethodToken is specified, the customer's default payment method will be used.

'sharedPaymentMethodNonce' string

For Shared Vault only

A payment method nonce belonging to the OAuth application owner. These payment method nonces can be credit cards or channel-initiated PayPal Billing Agreements that have been executed. Mutually exclusive with sharedPaymentMethodToken.

'sharedPaymentMethodToken' string

For Shared Vault only

The token of a payment method belonging to the OAuth application owner. Mutually exclusive with sharedPaymentMethodNonce. If no sharedCustomerId is explicitly specified, the customer that owns the payment method is implicitly specified. If used in conjunction with a sharedCustomerId, must belong to the specified customer.

'sharedShippingAddressId' string

For Shared Vault only

The ID of an address belonging to the OAuth application owner. If used in conjunction with a sharedCustomerId, must belong to the specified customer.

'shipping'

Shipping address information associated with a specific customer ID.

'company' string

Company name. 255 character maximum.

'countryCodeAlpha2' string

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

'countryCodeAlpha3' string

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

'countryCodeNumeric' string

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

'countryName' string

The country name specified in an address. We only accept specific country names.

'extendedAddress' string

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

'firstName' string

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

'lastName' string

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

'locality' string

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

'postalCode' string

The postal code. Postal code must be a string of 4-9 alphanumeric characters, optionally separated by a dash or a space. Spaces and hyphens are ignored. Required if passing a PayPal shipping address.

'region' string

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

'streetAddress' string

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.

'shippingAddressId' string

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

'shippingAmount' String

A Level 3 field that specifies the shipping cost on the entire transaction. It can't be negative, and it does not add to the total transaction amount.

'shipsFromPostalCode' string

A Level 3 field that specifies the postal code of the shipping location.

'taxAmount' String

A Level 2 field that specifies the amount of tax that was included in the total transaction amount. The value can't be negative, and in most cases, it must be greater than zero in order to qualify for lower interchange rates. It does not add to the total transaction amount.

'taxExempt' bool

A Level 2 field that indicates whether or not the transaction should be considered eligible for tax exemption. This does not affect the total transaction amount.

'threeDSecurePassThru'

Results of a merchant-performed 3D Secure authentication. You will only need to use these fields if you've performed your own integration with a 3D Secure MPI provider (e.g. Cardinal Centinel). Otherwise, Braintree's SDKs handle this for you in our standard 3D Secure integration.

'cavv' string

Cardholder authentication verification value.

'eciFlag' required, string

Electronic commerce indicator.

'threeDSecureVersion' string

The version of 3D Secure authentication used for the transaction. Must be composed of digits separated by periods (e.g. 1.0.2).

'xid' string

Transaction identifier resulting from 3D Secure authentication.

'transactionSource' string

Specifies the source of the transaction. The value passed depends on whether the transaction is initiated by the merchant or the customer. If the transaction is an ecommerce transaction initiated by the customer, no value is passed.

Accepted values for merchant-initiated transactions:

  • recurring = Transactions for subsequent recurring payments (e.g. subscriptions with a fixed amount on a predefined schedule).
  • unscheduled = Transactions for unscheduled payments that are not recurring on a predefined schedule or amount (e.g. balance top-up). Formerly merchant.

Accepted values for customer-initiated transactions:

  • recurring_first = Transactions that represent the first in a series of recurring payments or subscription.
  • moto = Transactions that are initiated by the customer via the merchant by mail or telephone.

Learn more about the Visa Stored Credential Framework in our blog.

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.

PHP
Copy
Copied
$result = $gateway->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
  ]
]);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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

PHP
Copy
Copied
$result->success
# true

$result->transaction->status
# e.g. 'submitted_for_settlement'

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

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 customerId along with options.storeInVault or options.storeInVaultOnSuccess as true.

PHP
Copy
Copied
$result = $gateway->transaction()->sale([
  'amount' => '10.00',
  'paymentMethodNonce' => nonceFromTheClient,
  'customerId' => 'the_customer_id',
  'options' => [
    'storeInVaultOnSuccess' => true,
  ]
]);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

New customer with new payment method

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

PHP
Copy
Copied
$result = $gateway->transaction()->sale([
  'amount' => '10.00',
  'paymentMethodNonce' => nonceFromTheClient,
  'customer' => [
    'id' => 'a_customer_id'
  ],
  'options' => [
    'storeInVaultOnSuccess' => true,
  ]
]);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.
note

The customer parameter should only be used when creating a new customer with a new payment method, and $storeInVaultOnSuccess 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 paymentMethodToken:

PHP
Copy
Copied
$result = $gateway->transaction()->sale(
  [
    'paymentMethodToken' => 'the_payment_method_token',
    'amount' => '100.00'
  ]
);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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

PHP
Copy
Copied
$result = $gateway->transaction()->sale(
  [
    'customerId' => 'the_customer_id',
    'amount' => '100.00'
  ]
);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Specify merchant account ID

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

PHP
Copy
Copied
$result = $gateway->transaction()->sale([
  'amount' => '100.00',
  'merchantAccountId' => 'gbp_merchant_account',
  'paymentMethodNonce' => nonceFromTheClient
]);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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

If you would like to change which merchant account is default, contact our Support team.

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.

PHP
Copy
Copied
$result = $gateway->transaction()->sale(
  [
    'customerId' => 'the_customer_id',
    'amount' => '100.00',
    'billingAddressId' => 'AA',
    'shippingAddressId' => 'AB'
  ]
);
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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.

PHP
Copy
Copied
$result = $gateway->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'
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Dynamic descriptors

Dynamic descriptors are typically composed 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 Braintree Marketplace transactions. See below for details on 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 Support for more information on your processor's specific requirements.

PHP
Copy
Copied
$result = $gateway->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'
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

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.

PHP
Copy
Copied
$result = $gateway->transaction()->sale(
  [
    'amount' => '100.00',
    'merchantAccountId' => 'blue_ladders_store',
    'paymentMethodNonce' => nonceFromTheClient,
    'options' => [
      'submitForSettlement' => true,
      'holdInEscrow' => true,
    ],
    'serviceFeeAmount' => "10.00"
  ]
)
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Still have questions?

If you can’t find an answer, contact our Support team