Transactions

RubySDK

• Current Braintree Languages
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

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.
• Take more advanced actions depending on your setup.

Status

The transaction status indicates the current stage in the transaction lifecycle. Refer to the following diagram, or see all possible statuses with their explanations in the reference.

Settlement

To collect money, you'll need to submit the sale transaction for settlement. You can do this in two ways:

• When creating a transaction, use the options.submit_for_settlement option:

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

• Use Transaction: Submit For Settlement:

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, you'll receive a Braintree::NotFoundError.

The transaction must be authorized 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 returns 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, you may get the same error code twice. Errors are scoped by parameter, so if you get an error such as Street address is too long, verify whether the error is on the billing street address or the 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 transaction response object has a disputes property that is an array of zero or more disputes.

You can also search for disputed transactions by the dispute date.

After you've located a disputed transaction, how you handle it depends on your banking partner. Learn more about chargebacks and retrievals in our support articles.

Learn more

See more documentation on transactions:

• Set up a basic PayPal 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.
• Sandbox testing details including test values for creating sandbox transactions.