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.

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.

Transaction statuses flow

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.submitForSettlement option:

    PHP
    Click to copy
    Copied
    $result = Braintree_Transaction::sale([
      'amount' => '10.00',
      'paymentMethodNonce' => nonceFromTheClient,
      'options' => [
        'submitForSettlement' => True
      ]
    ]);
  • Separately, using Braintree_Transaction::submitForSettlement():

    PHP
    Click to copy
    Copied
    $result = Braintree_Transaction::submitForSettlement('the_transaction_id');
    
    if ($result->success) {
        $settledTransaction = $result->transaction;
    } else {
        print_r($result->errors);
    }

If the transaction cannot be found, you'll receive a Braintree_Exception_NotFound exception.

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:

Still have questions?

If you can’t find an answer, contact our Support team.