Transactionsanchor

GraphQL
Refer to the corresponding information for using GraphQL.

Transactions represent attempts to transfer money between you and your customers. You can:

Statusanchor

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.

Transaction statuses flow

Settlementanchor

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

  1. 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
  1. 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, 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.

Validationsanchor

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.

note

For certain account setups, we recommend that merchants collect and pass billing address information when storing payment methods or creating transactions. Passing billing address details (at least the postal code) can help increase the likelihood of a successful authorization. To learn more about your specific account setup, contact us.

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.

Disputesanchor

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 moreanchor

See more documentation on transactions: