The Braintree Vault API provides secure, PCI-compliant long-term storage of customer payment method data. It allows merchants to store credit card numbers, PayPal accounts, and other payment methods so that returning customers do not need to re-enter their information. The Vault supports customer records that can hold multiple payment methods, billing addresses, and associated transaction history.
openapi: 3.1.0
info:
title: Braintree Payments 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
externalDocs:
description: Braintree Payments API Reference
url: https://developer.paypal.com/braintree/docs/guides/overview
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
tags:
- name: Client Tokens
description: >-
Operations for generating client tokens used to initialize Braintree
client SDKs on web and mobile.
- name: Customers
description: >-
Operations for creating, retrieving, updating, and deleting customer
records in the Braintree Vault.
- name: Disputes
description: >-
Operations for retrieving and managing payment disputes and chargebacks.
- name: Payment Methods
description: >-
Operations for creating, retrieving, updating, and deleting vaulted
payment methods associated with customers.
- name: Transactions
description: >-
Operations for creating, capturing, voiding, refunding, and retrieving
payment transactions.
security:
- basicAuth: []
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'
/client_token:
post:
operationId: generateClientToken
summary: Generate a client token
description: >-
Generates a time-limited client token used to initialize the Braintree
client-side SDK on web or mobile. The client token contains all
authorization and configuration information the client SDK needs to
communicate with Braintree. An optional customer_id may be provided
to include that customer's vaulted payment methods in the Drop-in UI
or to facilitate returning customer flows.
tags:
- Client Tokens
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: >-
Existing customer identifier to include the customer's
vaulted payment methods in the generated token. Enables
returning customer payment selection flows.
maxLength: 36
merchant_account_id:
type: string
description: >-
The merchant account to use when generating this token.
If omitted, the default merchant account is used.
version:
type: integer
description: >-
The version of the client token format. Defaults to 2.
enum: [1, 2]
default: 2
responses:
'201':
description: Client token generated successfully.
content:
application/json:
schema:
type: object
properties:
client_token:
type: string
description: >-
A Base64-encoded client token string used to initialize
the Braintree client SDK.
'401':
$ref: '#/components/responses/Unauthorized'
/customers:
post:
operationId: createCustomer
summary: Create a customer
description: >-
Creates a new customer record in the Braintree Vault. A customer record
can optionally include a payment method nonce to simultaneously vault
a payment method for the customer. No fields are strictly required;
a blank customer may be created and updated later. Customer records
serve as containers for vaulted payment methods and associated
transaction history.
tags:
- Customers
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'201':
description: Customer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/customers/{customerId}:
get:
operationId: getCustomer
summary: Get a customer
description: >-
Retrieves a customer record from the Braintree Vault by its unique
identifier. Returns the customer's profile information and all
associated vaulted payment methods, billing addresses, and transaction
history summary.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: Customer retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCustomer
summary: Update a customer
description: >-
Updates an existing customer record in the Braintree Vault. Only fields
provided in the request body are updated; omitted fields retain their
current values. A new payment method nonce may be provided to add
an additional payment method to the customer's vault.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'200':
description: Customer updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCustomer
summary: Delete a customer
description: >-
Permanently deletes a customer record from the Braintree Vault along
with all associated payment methods and addresses. This action is
irreversible. Historical transaction records associated with the
customer remain accessible but the customer profile is removed.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: Customer deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/payment_methods:
post:
operationId: createPaymentMethod
summary: Create a payment method
description: >-
Creates a new vaulted payment method for an existing customer using
a payment method nonce obtained from the Braintree client SDK.
The nonce is consumed and the underlying payment details are stored
securely in the Braintree Vault. Returns a payment method object with
a token that can be used for future transactions without requiring the
customer to re-enter payment details.
tags:
- Payment Methods
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodRequest'
responses:
'201':
description: Payment method created and vaulted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/payment_methods/any/{paymentMethodToken}:
get:
operationId: getPaymentMethod
summary: Get a payment method
description: >-
Retrieves a vaulted payment method by its unique token. Returns the
payment method details including type, masked card number or account
details, expiration information, and the customer it is associated with.
The token uniquely identifies the payment method across all types.
tags:
- Payment Methods
parameters:
- $ref: '#/components/parameters/PaymentMethodToken'
responses:
'200':
description: Payment method retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updatePaymentMethod
summary: Update a payment method
description: >-
Updates an existing vaulted payment method. Supports updating billing
address details, cardholder name, and other mutable fields. A new
payment method nonce may be provided to replace the underlying payment
details while preserving the existing token value.
tags:
- Payment Methods
parameters:
- $ref: '#/components/parameters/PaymentMethodToken'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodUpdateRequest'
responses:
'200':
description: Payment method updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deletePaymentMethod
summary: Delete a payment method
description: >-
Permanently removes a vaulted payment method from the Braintree Vault.
The associated customer record is retained but the payment method
token is invalidated. Active subscriptions using this payment method
token will fail on the next billing cycle unless updated to use a
different payment method.
tags:
- Payment Methods
parameters:
- $ref: '#/components/parameters/PaymentMethodToken'
responses:
'200':
description: Payment method deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/disputes:
get:
operationId: listDisputes
summary: List disputes
description: >-
Returns a list of disputes for the merchant account, optionally
filtered by dispute status, received date range, amount range, or
reason. Disputes represent chargebacks or retrievals initiated by
cardholders or their issuing banks. Each dispute includes the
associated transaction, amounts, deadlines, and current status.
tags:
- Disputes
parameters:
- name: status
in: query
required: false
description: Filter disputes by current status.
schema:
type: string
enum:
- open
- lost
- won
- accepted
- disputed
- expired
- name: received_date
in: query
required: false
description: >-
Filter disputes received on or after this date in YYYY-MM-DD
format.
schema:
type: string
format: date
- name: page
in: query
required: false
description: Page number for paginated results, starting at 1.
schema:
type: integer
minimum: 1
default: 1
responses:
'200':
description: List of disputes retrieved successfully.
content:
application/json:
schema:
type: object
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/Dispute'
total_items:
type: integer
description: Total number of disputes matching the query filters.
total_pages:
type: integer
description: Total number of pages of dispute results.
'401':
$ref: '#/components/responses/Unauthorized'
/disputes/{disputeId}:
get:
operationId: getDispute
summary: Get a dispute
description: >-
Retrieves the full details of a specific dispute by its unique
identifier. Returns all dispute information including the associated
transaction, evidence submitted, status history, amounts, deadlines,
and any chargeback reason codes provided by the card network.
tags:
- Disputes
parameters:
- $ref: '#/components/parameters/DisputeId'
responses:
'200':
description: Dispute retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dispute'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/disputes/{disputeId}/accept:
put:
operationId: acceptDispute
summary: Accept a dispute
description: >-
Accepts a dispute without contesting it. Accepting a dispute is a
final action that acknowledges the chargeback and surrenders the
disputed funds to the cardholder. This action cannot be undone. Use
this when you agree with the dispute or choose not to contest it.
tags:
- Disputes
parameters:
- $ref: '#/components/parameters/DisputeId'
responses:
'200':
description: Dispute accepted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dispute'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
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.
parameters:
TransactionId:
name: transactionId
in: path
required: true
description: The unique identifier of the transaction.
schema:
type: string
CustomerId:
name: customerId
in: path
required: true
description: The unique identifier of the customer record.
schema:
type: string
PaymentMethodToken:
name: paymentMethodToken
in: path
required: true
description: The unique token identifying the vaulted payment method.
schema:
type: string
DisputeId:
name: disputeId
in: path
required: true
description: The unique identifier of the dispute.
schema:
type: string
responses:
BadRequest:
description: Bad request. The request body or parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized. Authentication credentials are missing or 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'
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'
schemas:
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
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
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.
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. Alphanu
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/braintree/refs/heads/main/openapi/braintree-payments-openapi.yml