Transactionsanchor

GraphQL
Click here to view the corresponding information using GraphQL.

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

Once created, each transaction goes through a series of stages, which are reflected in the transaction's status.

Statusanchor

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.

Transaction statuses flow

Settlementanchor

If you want to collect funds, you must submit sale transactions 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, 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.

Validationsanchor

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.

note

For certain account setups, it is recommended that merchants collect and pass billing address information when storing payment methods and/or creating transactions. Passing billing address details (postal code at minimum) 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, 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.

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 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 moreanchor

See more documentation on transactions: