Transactions
Transactions represent attempts to transfer money between you and your customers. You can:
- get authorization to collect money from a customer by creating a sale
- collect the money from an authorized sale by submitting the transaction for settlement
- undo a transaction before it settles by creating a void
- return previously collected money to a customer by creating a refund
- search for or find transactions you've created
- depending on your setup, take more advanced actions detailed in the reference
Once created, each transaction goes through a series of stages, which are reflected in the transaction's status.
Status
The transaction status indicates the current stage of the transaction in its lifecycle. Check out the simplified diagram below, or see all possible statuses with their explanations in the reference.

Settlement
If you want to collect funds, you must submit sale transactions for settlement. You can do this in two ways:
- When creating a transaction, using the options.submit_for_settlement option:
- Ruby
result = gateway.transaction.sale(
:amount => "10.00",
:payment_method_nonce => nonce_from_the_client,
:device_data => device_data_from_the_client,
:options => {
:submit_for_settlement => true
}
)
if result.success?
# See result.transaction for details
else
# Handle errors
end
- Separately, using
Transaction: Submit For Settlement
:
- Ruby
result = gateway.transaction.submit_for_settlement("the_transaction_id")
if result.success?
settled_transaction = result.transaction
else
puts(result.message)
end
If the transaction can't be found, it will raise a Braintree::NotFoundError
.
The transaction must be authorized in order to submit for settlement. Learn more about submitting authorized transactions for settlement in our Managing Authorizations support article.
Validations
If you provide invalid or malformed transaction details, the gateway will return validation errors on the transaction. You may also receive other types of validation errors on any additional information associated with the transaction, including the payment method, customer, and address.
Because transactions can 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 the validation errors overview for more information.
Disputes
Depending on your account setup, when a customer files a chargeback or other dispute with their bank or card network, you can retrieve those details from the transaction response object. Each one has a disputes property that is an array of zero or more disputes.
You can also search for disputed transactions by the dispute date.
Once you've located a disputed transaction, how you handle it depends on your banking partner. Read more about chargebacks and retrievals in our support articles.
Learn more
See more documentation on transactions:
- Set up a basic Braintree integration to create a sale transaction using our Get Started guide
- Processor responses on authorization and settlement requests
- Gateway rejections and how to check the reason for a rejection
- Supporting sales in multiple currencies by specifying a merchant account ID
- Differences between refund, void, and detached credit transactions
- Transactions with 3D Secure
- Transactions with Braintree Marketplace
- Sandbox testing details including test values for creating sandbox transactions