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

Sale

Use Braintree::Transaction.sale() 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:

Ruby
result = Braintree::Transaction.sale(
  :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:

Ruby
result = Braintree::Transaction.sale(
  :payment_method_token => "the_token",
  :amount => "10.00"
)

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

Ruby
result = Braintree::Transaction.sale(
  :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.

Ruby
result = Braintree::Transaction.sale(
  :amount => "10.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.

Status

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

Settlement

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 Braintree::Transaction.submit_for_settlement():
Ruby
result = Braintree::Transaction.submit_for_settlement("the_transaction_id")

if result.success?
  settled_transaction = result.transaction
else
  puts(result.message)
end

If the transaction cannot be found, it will raise a Braintree::NotFoundError.

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

Void

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

Ruby
result = Braintree::Transaction.void("the_transaction_id")

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

Ruby
if result.success?
  # transaction successfully voided
else
  p result.errors
end

If the transaction cannot be found, it will raise a Braintree::NotFoundError.

See the reference for details.

Refund

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

Ruby
result = Braintree::Transaction.refund("the_transaction_id")

If the transaction cannot be found, it will raise a Braintree::NotFoundError.

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.

Ruby
result.success?
#=> false

p result.errors

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

Disputes

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.

Find

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

Ruby
transaction = Braintree::Transaction.find("the_transaction_id")

If the transaction cannot be found, it will raise a Braintree::NotFoundError.

Escrow status on Braintree Marketplace transactions

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

Ruby
transaction = Braintree::Transaction.find("the_transaction_id")
transaction.status
# "settled"
transaction.escrow_status
# "held"

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

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

Validations

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, give us a call at 877.434.2894 or email our Support team.