Payment API Concepts

This guide contains additional context on the main types in the Braintree API and their behavior. Check out the 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 How to Charge a Payment Method 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.

To charge a payment method and create a transaction, use the chargePaymentMethod mutation.

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.