Skip to main content

Payment API Concepts

This guide contains additional context on the main types in the Braintree API and their behavior. Check out the API Explorer for a full list and documentation of all possible fields on each object type covered here.

The Lifecycle of a Payment

Braintree offers APIs and SDKs to collect payment from customer checkout all the way to funds settling in your bank account. The typical payment lifecycle looks something like this:

  1. Your app or web front-end requests a client token from your server in order to initialize the client SDK
  2. Your server generates a client token and sends it back to your client
  3. Once the client SDK is initialized and the customer has submitted payment information, the SDK communicates that information to the Braintree servers and returns a single-use payment method
  4. You then send the payment method ID (called a "nonce" by the client code) to your server
  5. Your server code receives the payment method ID from your client and then uses the GraphQL API to do any of the following things:
    • Vault the single-use payment method information, permanently storing it for future use; this results in a new multi-use payment method
    • Charge the single-use payment method

Payment Methods

A PaymentMethod is how Braintree represents any single thing a customer could use to pay for something, such as a credit card (either directly or via a wallet like Apple Pay or Google Pay), a PayPal account, a Venmo account, or a bank account.

Every payment method points back to raw payment details provided by a customer, securely stored with Braintree, and has details that reflect that underlying funding source. For instance:

  • A credit card payment method will have a CreditCardDetails object that includes an expiration date
  • A PayPal account payment method will have a PayPalAccountDetails that includes the account's email address
  • A Venmo account payment method will have a VenmoAccountDetails that includes a Venmo username

...among many other details.

See also Transactions and How to Vault a Payment Method, for actions you can take with payment methods, and How to Collect Payment Information, for a guide on creating payment methods directly from customer input with the Braintree client SDKs.

The Braintree Vault

Your Vault is where we securely store your customers' payment data long-term, allowing you to charge repeat customers without making them re-enter their payment information. When you first collect payment information from a customer and send it to Braintree, you receive back a single-use payment method (if you're using our client SDK, the "nonce" string returned is its ID). Single-use payment methods expire 3 hours after being created or after they are used once.

If you have returning customers, subscriptions, or any other use case that requires you to make multiple charges on a single PaymentMethod, we recommend that you vault the single-use PaymentMethod. Vaulting consumes the initial single-use payment method, stores the underlying payment information, and creates a multi-use PaymentMethod. Store the ID of this new Payment Method and you can make unlimited charges against it in the future. Multi-use payment methods never expire.

Transactions

Transactions are produced when you charge a payment method. A Transaction represents the (attempted) movement of money from a customer to you to pay for something.

See Transactions for details.

If successful, as money moves over time towards your bank account, the transaction will change status as it moves through the payment lifecycle. If unsuccessful, the transaction's status will tell you what went wrong.

Once created, you can reverse a transaction, which will either cancel it before funds are actually debited from the customer, or refund them if money has already changed hands. If you need more granular control over sending funds back to a customer, you can directly refund it.

Transactions and Payment Methods

The Transaction type has two fields to represent the payment method transacted against: paymentMethodSnapshot and paymentMethod. As its name implies, paymentMethodSnapshot represents a snapshot of the payment method details at the time of the transaction, and therefore will stay the same on subsequent queries for the transaction. paymentMethod on the other hand fetches an up-to-date representation of the vaulted payment method at the time of the query (or null if the transaction wasn't created with a vaulted payment method). So if the expiration date of a vaulted payment method changes, any transaction against that payment method will have a paymentMethodSnapshot with the old expiration date, and a paymentMethod with the new one.

Another difference between paymentMethodSnapshot and paymentMethod is their return types. paymentMethodSnapshot returns a member of the PaymentMethodSnapshot union, and paymentMethod returns a PaymentMethod type. The PaymentMethod type is essentially a container for id (the vaulted payment method ID), and details (a member of the PaymentMethodDetails union representing the specific payment method type, e.g. CreditCardDetails, PayPalAccountDetails). The paymentMethodSnapshot union is similar to the PaymentMethodDetails union (in fact they share many members), but with a few differences. Namely, some payment methods can have additional information attached to them that is specific to a particular transaction, and thus are represented as a different type. For instance, credit card transactions have a snapshot type of CreditCardTransactionDetails, which contains a networkTransactionId field in addition to the credit card details. See our Transaction, PaymentMethod, and PaymentMethodSnapshot references for more details.

Customers

Customers are an optional component of the API that provide a way to store personal information about anyone who holds a vaulted payment method or initiates a transaction. Customers can be used to group payment methods and transactions, and have a one-to-many relationship with both.

When vaulting a new payment method, you can optionally choose an existing customer to associate the payment method with. Otherwise, an empty customer will be created that can later be updated.

A payment method cannot be transferred to a different customer.

If you want to link a transaction to a particular Customer, but that customer has elected not to store their payment method with you, you can also pass a customerId into the chargePaymentMethod or authorizePaymentMethod mutations with a single-use payment method.

The transactions field on a customer will hold all transactions made with

  • multi-use payment methods currently belonging to that customer,
    • in other words, paymentMethod.transactions for each payment method on customer.paymentMethods
  • multi-use payment methods that belonged to that customer, but have now been deleted from the Vault,
  • single-use payment methods if the customer ID was passed when that payment method was charged/authorized

A transaction cannot be associated with a different customer after the fact.