Transactions represent customer payments. Use the transaction API to:

  • Create a transaction using payment information, optionally saving a new customer at the same time
  • Find a transaction, or search for transactions that match specific criteria
  • Check a transaction's status
  • Submit a transaction for settlement to get paid
  • Void a transaction to cancel it before it settles
  • Refund a settled transaction to return funds to the customer
  • Retrieve disputes for a transaction


Use to create a transaction.

For example, you can create a transaction with just an amount and a payment_method_nonce relayed from your client and immediately submit it for settlement:

result ={
    "amount": "10.00",
    "payment_method_nonce": nonce_from_the_client,
    "options": {
        "submit_for_settlement": True

See the complete reference and examples.

Sale with vaulted payment methods

You can also create a transaction using payment method records already stored in the Vault with the payment_method_token:

result ={
    "payment_method_token": "the_token",
    "amount": "10.00"

Or use customer_id, which will use the customer's default payment method:

result ={
    "customer_id": "the_customer_id",
    "amount": "10.00"

You can also create a new customer in the Vault upon a successful transaction with the options.store_in_vault_on_success option.

Specify merchant account

To specify which merchant account to use, pass the merchant_account_id when creating the transaction.

result ={
    "amount": "100.00",
    "merchant_account_id": "your_merchant_account",
    "payment_method_nonce": nonce_from_the_client

If you don't specify the merchant account to use to process a transaction, Braintree will process it using your default merchant account.

If you would like to change which merchant account is default, contact our Support team.


Once created, each transaction goes through a series of stages. The transaction status indicates the current stage of the transaction in its lifecycle. Check out the simplified diagram below, and see all possible statuses here.

Transaction statuses flow


If you want to collect funds, you must submit transactions for settlement. You can do this in two ways:

  1. When creating a transaction, using the options.submit_for_settlement option.
  2. Separately, using Transaction.submit_for_settlement():
result = braintree.Transaction.submit_for_settlement("the_transaction_id")

if result.is_success:
  settled_transaction = result.transaction

If the transaction cannot be found, it will throw a NotFoundError exception.

The transaction must be authorized in order to settle. You can also settle only a portion of the total authorization amount.

Learn more about submitting authorized transactions for settlement within our Managing Authorizations support article.


Use Transaction.void() to cancel a transaction before it is settled:

result = braintree.Transaction.void("the_transaction_id")

If the transaction is successfully voided, the result will return true. Otherwise, check for validation errors.

if result.is_success:
    # transaction successfully voided
    p result.errors.deep_errors

If the transaction cannot be found, it will throw a NotFoundError exception.

See the reference for details.


If you want to refund a customer for a transaction that has already settled, use Transaction.refund():

result = braintree.Transaction.refund("the_transaction_id")

If the transaction cannot be found, it will throw a NotFoundError exception.

If the refund fails, then the result will be unsuccessful and will include either validation errors indicating which parameters were invalid, or a processor settlement response code indicating the type of settlement failure.

# False


You can also issue a partial refund by specifying an amount.


Depending on your account setup, when a customer disputes a transaction with their bank or card network you can retrieve those details from the transaction object.

Each Transaction response has a disputes property that is an array of zero or more disputes.

You can also search for disputed transactions.


Use Transaction.find() to look up a single transaction by its ID:

transaction = braintree.Transaction.find("the_transaction_id")

If the transaction cannot be found, it will throw a NotFoundError exception.

Escrow status on Braintree Marketplace transactions

Use the transaction's id to find the escrow_status on Braintree Marketplace transactions:

transaction = braintree.Transaction.find("the_transaction_id")
# "held"

The return value for both of these calls will be a Transaction response object.

You can also search for transactions matching specific criteria using See the transaction search reference and examples to get started.


In addition to errors on the transaction directly, credit card, customer, and address validations also apply.

Because transactions have both a billing and a shipping address, it's possible to get the same error code twice. Errors are scoped by parameter so if you get an error like "Street address is too long" you can determine whether it's on the billing street address or shipping street address. See validation errors for more information.

Still have questions?

If you can’t find an answer, contact our Support team.