braintree Transactions API
Operations for creating, capturing, voiding, refunding, and retrieving payment transactions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Braintree Payments Add-Ons Transactions API
description: The Braintree Payments API is the core server-side interface for accepting and processing payments through Braintree's gateway. It enables developers to create and manage transactions, handle authorizations and captures, and process refunds and voids. The API supports a wide range of payment methods including credit and debit cards, PayPal, Apple Pay, Google Pay, and Venmo. Authentication uses HTTP Basic auth with the merchant's public key as the username and private key as the password. All requests and responses use XML or JSON depending on the SDK and endpoint variant used.
version: '1.0'
contact:
name: Braintree Developer Support
url: https://developer.paypal.com/braintree/docs/
termsOfService: https://www.braintreepayments.com/legal
servers:
- url: https://api.braintreegateway.com/merchants/{merchantId}
description: Production Server
variables:
merchantId:
description: The unique identifier for the merchant account.
default: your_merchant_id
- url: https://api.sandbox.braintreegateway.com/merchants/{merchantId}
description: Sandbox Server
variables:
merchantId:
description: The unique identifier for the sandbox merchant account.
default: your_merchant_id
security:
- basicAuth: []
tags:
- name: Transactions
description: Operations for creating, capturing, voiding, refunding, and retrieving payment transactions.
paths:
/transactions:
post:
operationId: createTransaction
summary: Create a transaction
description: Creates a new payment transaction (sale) through the Braintree gateway. Requires either a payment_method_nonce for a one-time payment method, a payment_method_token referencing a vaulted payment method, or a customer_id to use the customer's default vaulted payment method. The amount must be a positive decimal value matching the currency format. Optionally submit the transaction immediately for settlement or hold it in an authorized state for later capture.
tags:
- Transactions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'201':
description: Transaction created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/transactions/{transactionId}:
get:
operationId: getTransaction
summary: Get a transaction
description: Retrieves the full details of a specific transaction by its unique identifier. Returns the complete transaction object including current status, payment method details, billing and shipping addresses, descriptor information, and any associated disbursement data.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/TransactionId'
responses:
'200':
description: Transaction retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/transactions/{transactionId}/submit_for_settlement:
put:
operationId: submitTransactionForSettlement
summary: Submit transaction for settlement
description: Submits a previously authorized transaction for settlement, initiating the transfer of funds to the merchant. An optional amount may be specified for partial settlement if less than the full authorized amount is desired. The transaction must be in the authorized state to be eligible for settlement submission.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/TransactionId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
amount:
type: string
description: Amount to submit for settlement. If omitted, the full authorized amount is submitted. Must be less than or equal to the authorized amount.
example: '10.00'
responses:
'200':
description: Transaction submitted for settlement successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/transactions/{transactionId}/void:
put:
operationId: voidTransaction
summary: Void a transaction
description: Voids an authorized or submitted-for-settlement transaction, preventing it from being settled. Voiding cancels the payment before funds are transferred. A transaction can only be voided if it is in the authorized, submitted_for_settlement, or settlement_pending status. Once voided, a transaction cannot be captured or refunded.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/TransactionId'
responses:
'200':
description: Transaction voided successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/transactions/{transactionId}/refund:
post:
operationId: refundTransaction
summary: Refund a transaction
description: Issues a full or partial refund on a settled transaction. Partial refunds may be issued multiple times until the cumulative refunded amount equals the settled amount. A new transaction of type "credit" is created representing the refund. The original transaction must be in a settled or settling status to be eligible for refund.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/TransactionId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
amount:
type: string
description: Amount to refund. If omitted, the full settled amount is refunded. Must be a positive decimal value less than or equal to the settled amount.
example: '5.00'
order_id:
type: string
description: An order identifier to associate with this refund transaction for merchant reference.
maxLength: 255
responses:
'201':
description: Refund transaction created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
LineItem:
type: object
description: A line item representing a single product or service in a transaction, used for Level 3 processing data.
required:
- name
- quantity
- unit_amount
- total_amount
- kind
properties:
name:
type: string
description: Name or description of the product or service.
maxLength: 127
description:
type: string
description: Additional description of the line item.
maxLength: 127
kind:
type: string
description: Whether this item is a debit (charge) or credit (discount).
enum:
- debit
- credit
quantity:
type: string
description: Quantity of the line item as a decimal string.
example: '1.0000'
unit_amount:
type: string
description: Unit price of the line item as a decimal string.
example: '5.00'
total_amount:
type: string
description: Total amount for this line item (quantity * unit_amount) as a decimal.
example: '5.00'
unit_of_measure:
type: string
description: Unit of measure for the quantity, such as "each" or "kg".
maxLength: 12
commodity_code:
type: string
description: Commodity code for Level 3 processing.
maxLength: 12
tax_amount:
type: string
description: Tax amount for this line item as a decimal string.
Address:
type: object
description: A billing or shipping address associated with a transaction or customer.
properties:
first_name:
type: string
description: First name of the address holder.
maxLength: 255
last_name:
type: string
description: Last name of the address holder.
maxLength: 255
company:
type: string
description: Company or organization name at this address.
maxLength: 255
street_address:
type: string
description: Primary street address line.
maxLength: 255
extended_address:
type: string
description: Secondary address line such as apartment or suite number.
maxLength: 255
locality:
type: string
description: City or locality of the address.
maxLength: 255
region:
type: string
description: State, province, or region code of the address.
maxLength: 255
postal_code:
type: string
description: Postal or ZIP code of the address.
maxLength: 9
country_code_alpha2:
type: string
description: Two-letter ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
TransactionOptions:
type: object
description: Configuration options that modify transaction processing behavior.
properties:
submit_for_settlement:
type: boolean
description: If true, the transaction is automatically submitted for settlement after authorization. Defaults to false.
default: false
store_in_vault:
type: boolean
description: If true, the payment method is stored in the Braintree Vault after the transaction is created.
default: false
store_in_vault_on_success:
type: boolean
description: If true, the payment method is stored in the Vault only if the transaction is successfully authorized.
default: false
skip_avs:
type: boolean
description: Skip the address verification check for this transaction.
default: false
skip_cvv:
type: boolean
description: Skip the CVV verification check for this transaction.
default: false
hold_in_escrow:
type: boolean
description: If true, funds are held in escrow rather than disbursed immediately. Applicable to Braintree Marketplace transactions only.
default: false
CreditCardDetails:
type: object
description: Details of the credit or debit card used in a transaction, with sensitive fields masked.
properties:
bin:
type: string
description: First six digits of the card number identifying the issuing bank.
pattern: ^\d{6}$
last_4:
type: string
description: Last four digits of the card number.
pattern: ^\d{4}$
card_type:
type: string
description: The card network or type, such as Visa, MasterCard, American Express, or Discover.
expiration_month:
type: string
description: Two-digit expiration month of the card.
pattern: ^\d{2}$
expiration_year:
type: string
description: Four-digit expiration year of the card.
pattern: ^\d{4}$
cardholder_name:
type: string
description: Name of the cardholder as it appears on the card.
country_of_issuance:
type: string
description: Two-letter ISO 3166-1 country code of the card-issuing country.
Transaction:
type: object
description: Represents a payment transaction in the Braintree gateway. A transaction captures the full lifecycle from authorization through settlement, refund, or void.
properties:
id:
type: string
description: Unique identifier for the transaction assigned by Braintree.
status:
type: string
description: The current processing status of the transaction.
enum:
- authorization_expired
- authorized
- authorizing
- settlement_confirmed
- settlement_declined
- settlement_pending
- settled
- settling
- submitted_for_settlement
- voided
- processor_declined
- failed
- gateway_rejected
amount:
type: string
description: The transaction amount as a decimal string.
example: '10.00'
currency_iso_code:
type: string
description: ISO 4217 three-letter currency code for the transaction.
example: USD
type:
type: string
description: The type of transaction. "sale" for a charge, "credit" for a refund.
enum:
- sale
- credit
order_id:
type: string
description: Merchant-provided order identifier associated with this transaction.
merchant_account_id:
type: string
description: The merchant account used to process this transaction.
created_at:
type: string
format: date-time
description: Timestamp when the transaction was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
description: Timestamp when the transaction was last updated, in ISO 8601 format.
payment_method_nonce:
type: string
description: The payment method nonce used for the transaction, if applicable.
payment_method_token:
type: string
description: The token of the vaulted payment method used for the transaction, if applicable.
customer_id:
type: string
description: The identifier of the customer associated with this transaction, if applicable.
billing:
$ref: '#/components/schemas/Address'
shipping:
$ref: '#/components/schemas/Address'
customer_details:
$ref: '#/components/schemas/Customer'
credit_card_details:
$ref: '#/components/schemas/CreditCardDetails'
descriptor:
$ref: '#/components/schemas/Descriptor'
refund_ids:
type: array
description: List of transaction identifiers for refund transactions associated with this transaction.
items:
type: string
processor_response_code:
type: string
description: The processor-specific response code returned when the transaction was processed.
processor_response_text:
type: string
description: Human-readable text description of the processor response code.
tax_amount:
type: string
description: The tax amount included in this transaction.
shipping_amount:
type: string
description: The shipping amount included in this transaction.
Descriptor:
type: object
description: Dynamic descriptor fields that appear on the customer's bank or credit card statement to identify the merchant and transaction.
properties:
name:
type: string
description: Merchant name as it appears on the customer's statement. Maximum 22 characters total; name and phone combined must be 22 characters or less with an asterisk separator.
maxLength: 22
phone:
type: string
description: Merchant phone number as it appears on the customer's statement. Must be 10–14 digits.
maxLength: 14
url:
type: string
description: Merchant URL as it appears on the customer's statement. Maximum 13 characters.
maxLength: 13
Customer:
type: object
description: Represents a customer record stored in the Braintree Vault. Customers serve as containers for vaulted payment methods and provide a way to associate transaction history with individuals.
properties:
id:
type: string
description: Unique identifier for the customer assigned by Braintree.
first_name:
type: string
description: Customer's first name.
last_name:
type: string
description: Customer's last name.
email:
type: string
description: Customer's email address.
phone:
type: string
description: Customer's phone number.
company:
type: string
description: Customer's company or organization name.
website:
type: string
description: Customer's website URL.
created_at:
type: string
format: date-time
description: Timestamp when the customer was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
description: Timestamp when the customer was last updated, in ISO 8601 format.
payment_methods:
type: array
description: Collection of vaulted payment methods associated with this customer.
items:
$ref: '#/components/schemas/PaymentMethod'
addresses:
type: array
description: Collection of addresses associated with this customer.
items:
$ref: '#/components/schemas/Address'
custom_fields:
type: object
description: Custom key-value pairs associated with this customer.
additionalProperties:
type: string
CustomerRequest:
type: object
description: Request body for creating or updating a customer record in the Braintree Vault. All fields are optional.
properties:
id:
type: string
description: Custom customer identifier. If omitted, Braintree generates a unique ID. Alphanumeric, hyphens, and underscores only.
maxLength: 36
pattern: ^[a-zA-Z0-9_-]+$
first_name:
type: string
description: Customer's first name.
maxLength: 255
last_name:
type: string
description: Customer's last name.
maxLength: 255
email:
type: string
format: email
description: Customer's email address. ASCII characters only.
maxLength: 255
phone:
type: string
description: Customer's phone number.
maxLength: 255
company:
type: string
description: Customer's company or organization name.
maxLength: 255
website:
type: string
format: uri
description: Customer's website URL. Must be a well-formed URL.
maxLength: 255
fax:
type: string
description: Customer's fax number.
maxLength: 255
payment_method_nonce:
type: string
description: A one-time nonce representing a payment method to vault for the customer at creation time.
custom_fields:
type: object
description: Custom key-value pairs. Keys must be pre-configured in the Braintree Control Panel.
additionalProperties:
type: string
PaymentMethod:
type: object
description: Represents a payment method stored in the Braintree Vault. This is a polymorphic object that may represent a credit card, PayPal account, Venmo account, or other supported payment type.
properties:
token:
type: string
description: Unique token identifying this vaulted payment method. Used as a reference for future transactions.
customer_id:
type: string
description: The identifier of the customer who owns this payment method.
default:
type: boolean
description: Indicates whether this is the customer's default payment method.
image_url:
type: string
format: uri
description: URL of an image representing the payment method type.
created_at:
type: string
format: date-time
description: Timestamp when this payment method was vaulted, in ISO 8601 format.
updated_at:
type: string
format: date-time
description: Timestamp when this payment method was last updated, in ISO 8601 format.
TransactionRequest:
type: object
description: Request body for creating a new payment transaction. Either payment_method_nonce, payment_method_token, or customer_id is required.
properties:
amount:
type: string
description: The billing amount for the transaction as a decimal string. Must be greater than 0 and match the currency decimal format.
example: '10.00'
payment_method_nonce:
type: string
description: A one-time-use reference to payment information collected by the Braintree client SDK. Consumed upon transaction creation.
payment_method_token:
type: string
description: The token of a vaulted payment method to charge for this transaction.
customer_id:
type: string
description: The identifier of a customer whose default vaulted payment method will be used for this transaction.
maxLength: 36
order_id:
type: string
description: A merchant-defined order identifier associated with this transaction for reconciliation.
maxLength: 255
merchant_account_id:
type: string
description: The identifier of the merchant account to process this transaction. If omitted, the default merchant account is used.
device_data:
type: string
description: Customer device data string collected by the Braintree data collector for fraud prevention analysis.
descriptor:
$ref: '#/components/schemas/Descriptor'
billing:
$ref: '#/components/schemas/Address'
shipping:
$ref: '#/components/schemas/Address'
options:
$ref: '#/components/schemas/TransactionOptions'
tax_amount:
type: string
description: The tax amount included in the transaction total for Level 2 and Level 3 processing.
example: '1.00'
shipping_amount:
type: string
description: The shipping amount included in the transaction total for Level 3 processing.
example: '2.00'
customer:
$ref: '#/components/schemas/CustomerRequest'
line_items:
type: array
description: Line items for Level 3 processing. Up to 249 line items may be included.
maxItems: 249
items:
$ref: '#/components/schemas/LineItem'
transaction_source:
type: string
description: Indicates the origin of this transaction for network reporting.
enum:
- recurring
- recurring_first
- unscheduled
- moto
Error:
type: object
description: Standard error response returned by the Braintree API.
properties:
message:
type: string
description: Human-readable description of the error.
errors:
type: object
description: Nested object containing field-level validation errors organized by resource type.
additionalProperties: true
responses:
Unauthorized:
description: Unauthorized. Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnprocessableEntity:
description: Unprocessable entity. The request was well-formed but the transaction was declined or failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request. The request body or parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Not found. The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
TransactionId:
name: transactionId
in: path
required: true
description: The unique identifier of the transaction.
schema:
type: string
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Authentication using the merchant's public API key as the username and private API key as the password, Base64-encoded per RFC 7617.
externalDocs:
description: Braintree Payments API Reference
url: https://developer.paypal.com/braintree/docs/guides/overview