Sale

Availability

The XML API is currently only available to select partners.

Once you have the payment-method-nonce you can use it to charge the customer. In this example, it is assumed that a $NONCE has been generated by Braintree's Client SDK; and an $ORDER_ID has been generated from your webstore. Both the $NONCE and $ORDER_ID are passed over into the transaction request. This example request will generate an authorization.

Note

The sale call is a POST.

bash

curl -v https://api.sandbox.braintreegateway.com/merchants/$MERCHANT_ID/transactions \
  -u "$PUBLIC_KEY:$PRIVATE_KEY" \
  -H "X-ApiVersion: 4" \
  -H "Content-Type: application/xml" \
  -H "User-Agent: API Demo 0.1.0" \
  -X POST \
  -d "<transaction>
    <type>sale</type>
    <order-id>$ORDER_ID</order-id>
    <amount>5</amount>
    <payment-method-nonce>$NONCE
    </payment-method-nonce>
    <customer>
      <first-name>Drew</first-name>
      <last-name>Smith</last-name>
      <company>Braintree</company>
      <phone>312-555-1234</phone>
      <fax>312-555-1235</fax>
      <website>http://www.example.com</website>
      <email>drew@example.com</email>
    </customer>
    <billing>
      <first-name>Paul</first-name>
      <last-name>Smith</last-name>
      <company>Braintree</company>
      <street-address>1 E Main St</street-address>
      <extended-address>Suite 403</extended-address>
      <locality>Chicago</locality>
      <region>IL</region>
      <postal-code>60622</postal-code>
      <country-code-alpha2>US</country-code-alpha2>
    </billing>
    <shipping>
      <first-name>Jen</first-name>
      <last-name>Smith</last-name>
      <company>Braintree</company>
      <street-address>1 E 1st St</street-address>
      <extended-address>Suite 403</extended-address>
      <locality>Bartlett</locality>
      <region>IL</region>
      <postal-code>60103</postal-code>
      <country-code-alpha2>US</country-code-alpha2>
    </shipping>
    <options>
      <store-in-vault-on-success type="boolean">true</store-in-vault-on-success>
    </options>
    <device-data>{\"device_session_id\":\"f52176b89ae7e987d249829750dbc6d9\",\"fraud_merchant_id\":\"600000\",\"correlation_id\":\"2dc42ad3a2a8d2222acca7b6e63ba7db\"}</device-data>
</transaction>"

Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
  <id>82w23y</id>
  <status>authorized</status>
  <type>sale</type>
  <currency-iso-code>USD</currency-iso-code>
  <amount>5.00</amount>
  <merchant-account-id>fhpcfp58pnsfrcr2</merchant-account-id>
  <order-id>0a2a2b25e9</order-id>
  <created-at type="datetime">2015-09-29T16:51:52Z</created-at>
  <updated-at type="datetime">2015-09-29T16:51:53Z</updated-at>
  <customer>
    <id>13315009</id>
    <first-name>Drew</first-name>
    <last-name>Smith</last-name>
    <company>Braintree</company>
    <email>drew@example.com</email>
    <website>http://www.example.com</website>
    <phone>312-555-1234</phone>
    <fax>312-555-1235</fax>
  </customer>
  <billing>
    <id nil="true"/>
    <first-name>Paul</first-name>
    <last-name>Smith</last-name>
    <company>Braintree</company>
    <street-address>1 E Main St</street-address>
    <extended-address>Suite 403</extended-address>
    <locality>Chicago</locality>
    <region>IL</region>
    <postal-code>60622</postal-code>
    <country-name>United States of America</country-name>
    <country-code-alpha2>US</country-code-alpha2>
    <country-code-alpha3>USA</country-code-alpha3>
    <country-code-numeric>840</country-code-numeric>
  </billing>
  <refund-id nil="true"/>
  <refund-ids type="array"/>
  <refunded-transaction-id nil="true"/>
  <partial-settlement-transaction-ids type="array"/>
  <authorized-transaction-id nil="true"/>
  <settlement-batch-id nil="true"/>
  <shipping>
    <id nil="true"/>
    <first-name>Jen</first-name>
    <last-name>Smith</last-name>
    <company>Braintree</company>
    <street-address>1 E 1st St</street-address>
    <extended-address>Suite 403</extended-address>
    <locality>Bartlett</locality>
    <region>IL</region>
    <postal-code>60103</postal-code>
    <country-name>United States of America</country-name>
    <country-code-alpha2>US</country-code-alpha2>
    <country-code-alpha3>USA</country-code-alpha3>
    <country-code-numeric>840</country-code-numeric>
  </shipping>
  <custom-fields/>
  <avs-error-response-code nil="true"/>
  <avs-postal-code-response-code>M</avs-postal-code-response-code>
  <avs-street-address-response-code>M</avs-street-address-response-code>
  <cvv-response-code>I</cvv-response-code>
  <gateway-rejection-reason nil="true"/>
  <processor-authorization-code>073W8M</processor-authorization-code>
  <processor-response-code>1000</processor-response-code>
  <processor-response-text>Approved</processor-response-text>
  <additional-processor-response nil="true"/>
  <voice-referral-number nil="true"/>
  <purchase-order-number nil="true"/>
  <tax-amount nil="true"/>
  <tax-exempt type="boolean">false</tax-exempt>
  <credit-card>
    <token>d46sg6</token>
    <bin>411111</bin>
    <last-4>1111</last-4>
    <card-type>Visa</card-type>
    <expiration-month>12</expiration-month>
    <expiration-year>2020</expiration-year>
    <customer-location>US</customer-location>
    <cardholder-name nil="true"/>
    <image-url>https://assets.braintreegateway.com/payment_method_logo/visa.png?environment=sandbox</image-url>
    <prepaid>Unknown</prepaid>
    <healthcare>Unknown</healthcare>
    <debit>Unknown</debit>
    <durbin-regulated>Unknown</durbin-regulated>
    <commercial>Unknown</commercial>
    <payroll>Unknown</payroll>
    <issuing-bank>Unknown</issuing-bank>
    <country-of-issuance>Unknown</country-of-issuance>
    <product-id>Unknown</product-id>
    <unique-number-identifier>89a4d7b5effd9a38772694dff310fa90</unique-number-identifier>
    <venmo-sdk type="boolean">false</venmo-sdk>
  </credit-card>
  <status-history type="array"/>
  <plan-id nil="true"/>
  <subscription-id nil="true"/>
  <subscription>
    <billing-period-end-date nil="true"/>
    <billing-period-start-date nil="true"/>
  </subscription>
  <add-ons type="array"/>
  <discounts type="array"/>
  <descriptor>
    <name nil="true"/>
    <phone nil="true"/>
    <url nil="true"/>
  </descriptor>
  <recurring type="boolean">false</recurring>
  <channel nil="true"/>
  <service-fee-amount nil="true"/>
  <escrow-status nil="true"/>
  <disbursement-details>
    <disbursement-date nil="true"/>
    <settlement-amount nil="true"/>
    <settlement-currency-iso-code nil="true"/>
    <settlement-currency-exchange-rate nil="true"/>
    <funds-held nil="true"/>
    <success nil="true"/>
  </disbursement-details>
  <disputes type="array"/>
  <payment-instrument-type>credit_card</payment-instrument-type>
  <processor-settlement-response-code></processor-settlement-response-code>
  <processor-settlement-response-text></processor-settlement-response-text>
  <risk-data>
    <id>31MS087C6BN4</id>
    <decision>Approve</decision>
    <fraud-service-provider>Kount</fraud-service-provider>
    <device-data-captured>True</device-data-captured>
    <decision-reasons>reason1, reason2</decision-reasons>
    <risk-score>42</risk-score>
  </risk-data>
  <three-d-secure-info nil="true"/>
</transaction>

From the response, you should store the transaction ID 82w23y. You would then use the transaction ID in the submit_for_settlement call. If you would rather authorize and capture in a single API call, you can pass the option submit-for-settlement as true in the authorization call.

bash

curl -v https://api.sandbox.braintreegateway.com/merchants/$MERCHANT_ID/transactions \
  -u "$PUBLIC_KEY:$PRIVATE_KEY" \
  -H "X-ApiVersion: 4" \
  -H "Content-Type: application/xml" \
  -H "User-Agent: API Demo 0.1.0" \
  -X POST \
  -d "<transaction>
    <type>sale</type>
    <amount>10</amount>
    <payment-method-nonce>$NONCE
    </payment-method-nonce>
    <options>
      <submit-for-settlement>true</submit-for-settlement>
    </options>
</transaction>"

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 transaction identifier such as an order number, reference number, product name or an other transaction 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 12 characters for dynamic descriptor names on Braintree Marketplace transactions. See below for details on PayPal 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.

PayPal

Only the name of the descriptor will be passed for PayPal transactions. The PayPal dynamic descriptor includes the prefix PAYPAL * by default and is truncated to a total of 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).

bash

curl -v https://api.sandbox.braintreegateway.com/merchants/$MERCHANT_ID/transactions \
  -u "$PUBLIC_KEY:$PRIVATE_KEY" \
  -H "X-ApiVersion: 4" \
  -H "Content-Type: application/xml" \
  -H "User-Agent: API Demo 0.1.0" \
  -X POST \
  -d "<transaction>
    <type>sale</type>
    <order-id>2949f0bfc4</order-id>
    <amount>10</amount>
    <payment-method-nonce>$NONCE
    </payment-method-nonce>
    <customer>
      <first-name>John</first-name>
      <last-name>Smith</last-name>
      <phone>4025551212</phone>
    </customer>
    <descriptor>
      <name>company*my product</name>
      <phone>3125551212</phone>
      <url>company.com</url>
    </descriptor>
    <options>
      <submit-for-settlement>true</submit-for-settlement>
    </options>
</transaction>"

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.

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

'country-code-alpha2'

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'

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

'country-code-numeric'

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

'country-name'

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

'extended-address'

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

'first-name'

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

'last-name'

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

'locality'

The locality/city. 255 character maximum.

'postal-code'

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'

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

'street-address'

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

'billing-address-id'

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

'channel'

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'

Typically requires PCI SAQ D compliance

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'

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.

'expiration-date'

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'

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

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

Company name. 255 character maximum.

'email'

Email address composed of ASCII characters.

'fax'

Fax number. 255 character maximum.

'first-name'

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.

'last-name'

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.

'customer-id'

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 can't 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, 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'

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). See PayPal dynamic descriptors for details on PayPal transactions.

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

'device-data'

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

'device-session-id'

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

'merchant-account-id'

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 Braintree Marketplace merchants only. This value specifies whether a transaction is held in escrow. See Escrow for more detail.

'paypal'

PayPal-specific options

'custom-field'

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

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

'skip-avs'bool

The option that determines whether the merchant's AVS rules are applied to the transaction. Transactions that have this flag passed as "true" will have an AVS response code of 'B' to denote that the rules were bypassed.

'skip-cvv'bool

The option that determines whether the merchant's CVV rules are applied to the transaction. Transactions that have this flag passed as "true" will have an CVV response code of 'B' to denote that the rules were bypassed.

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

'order-id'

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.

'payment-method-nonce'

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 information. This can be passed instead of a payment-method-token parameter.

'payment-method-token'

'purchase-order-number'

A Level 2 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 is being passed with a recurring ecommerce indicator (ECI) flag.

'service-fee-amount'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 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.

'shared-billing-address-id'String

For Shared Vault only

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

'shared-customer-id'String

For Shared Vault only

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

'shared-payment-method-nonce'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 shared-payment-method-token.

'shared-payment-method-token'String

For Shared Vault only

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

'shared-shipping-address-id'String

For Shared Vault only

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

'shipping'

Shipping address information associated with a specific customer ID.

'company'

Company name. 255 character maximum.

'country-code-alpha2'

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

'country-code-alpha3'

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

'country-code-numeric'

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

'country-name'

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

'extended-address'

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

'first-name'

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

'last-name'

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

'locality'

The locality/city. 255 character maximum.

'postal-code'

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'

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

'street-address'

The street address. Street address must be less than or equal to 255 characters. Must contain at least 1 digit.

'shipping-address-id'

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

'tax-amount'String

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

'tax-exempt'bool

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