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 Creating 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 Creating 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 paymentMethodSnapshot field on a transaction contains details about the payment method used to create it at the time of creation. If the transaction was created from a payment method stored in the Vault, its paymentMethod field will contain the full vaulted payment method in its current state.

This second field exists because the underlying details of a vaulted PaymentMethod could change or be updated after the transaction has been created — for instance, a credit card might expire and be replaced by a new one with a new expiration date. In that case, the paymentMethodSnapshot field would have the old expiration date and card number, and the paymentMethod field would have the currently vaulted full payment method, with the new expiration date and number.

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.