braintree Payment Methods API
Operations for creating, retrieving, updating, and deleting vaulted payment methods associated with customers.
OpenAPI Specification
openapi: 3.1.0
info:
title: Braintree Payments Add-Ons Payment Methods 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: Payment Methods
description: Operations for creating, retrieving, updating, and deleting vaulted payment methods associated with customers.
paths:
/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'
components:
schemas:
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}$
PaymentMethodUpdateRequest:
type: object
description: Request body for updating an existing vaulted payment method.
properties:
payment_method_nonce:
type: string
description: A new one-time nonce to replace the underlying payment details while preserving the existing token.
billing_address:
$ref: '#/components/schemas/Address'
options:
type: object
description: Options for the payment method update.
properties:
make_default:
type: boolean
description: If true, this payment method becomes the customer's default.
update_existing_token:
type: string
description: Token of an existing payment method to update rather than creating a new one.
PaymentMethodRequest:
type: object
required:
- customer_id
- payment_method_nonce
description: Request body for vaulting a new payment method for an existing customer.
properties:
customer_id:
type: string
description: The identifier of the customer to associate this payment method with.
maxLength: 36
payment_method_nonce:
type: string
description: A one-time-use reference to payment information provided by the Braintree client SDK. Consumed upon vaulting.
token:
type: string
description: Custom token to assign to this payment method. If omitted, Braintree generates a unique token.
maxLength: 36
billing_address:
$ref: '#/components/schemas/Address'
options:
type: object
description: Options that modify the payment method vaulting behavior.
properties:
make_default:
type: boolean
description: If true, this payment method becomes the customer's default payment method.
default: false
fail_on_duplicate_payment_method:
type: boolean
description: If true, the request fails if a duplicate payment method already exists in the customer's vault.
default: false
verify_card:
type: boolean
description: If true, runs a card verification before vaulting the payment method.
default: false
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.
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:
PaymentMethodToken:
name: paymentMethodToken
in: path
required: true
description: The unique token identifying the vaulted payment method.
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