Transactions

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 Transaction.Sale() to create a transaction.

For example, you can create a transaction with just an Amount and a PaymentMethodNonce relayed from your client and immediately submit it for settlement:

var request = new TransactionRequest
{
    Amount = 100.00M,
    PaymentMethodNonce = nonceFromTheClient,
    Options = new TransactionOptionsRequest
    {
        SubmitForSettlement = true
    }
};

Result<Transaction> result = gateway.Transaction.Sale(request);
C♯

You can also create a transaction using payment method records already stored in the Vault with the PaymentMethodToken:

var result = gateway.Transaction.Sale(
    new TransactionRequest
    {
        PaymentMethodToken = "the_token",
        Amount = 10.00M
    });
C♯

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

var result = gateway.Transaction.Sale(
    new TransactionRequest
    {
        CustomerId = "the_customer_id",
        Amount = 10.00M
    });
C♯

You can also create a new customer in the Vault upon a successful transaction with the Options.storeInVaultOnSuccess option.

See the complete reference and examples.

Specify merchant account

To specify which merchant account to use, pass the MerchantAccountId when creating the transaction.

TransactionRequest request = new TransactionRequest
{
    Amount = 100.00M,
    MerchantAccountId = "your_merchant_account",
    PaymentMethodNonce = nonceFromTheClient
};

Result<Transaction> result = gateway.Transaction.Credit(request);
C♯

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 Braintree Support.

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.submitForSettlement option.
  2. Separately, using Transaction.SubmitForSettlement():
Result<Transaction> result = gateway.Transaction.SubmitForSettlement("the_transaction_id");
C♯

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

Void

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

Result<Transaction> result = gateway.Transaction.Void("the_transaction_id");
C♯

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

if (result.IsSuccess())
{
    // transaction successfully voided
}
else
{
    foreach (ValidationError error in result.Errors.DeepAll())
    {
        Console.WriteLine(error.Message);
    }
}
C♯

See the reference for details.

Refund

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

Result<Transaction> result = gateway.Transaction.Refund("the_transaction_id");
C♯

If the refund fails, then the result will be unsuccessful and will include validation errors indicating which parameters were invalid.

if (!result.IsSuccess())
{
    List<ValidationError> errors = result.Errors.DeepAll();
}
C♯

You can also issue a partial refund by specifying an Amount. See the reference for details.

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 & Search

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

Transaction transaction = gateway.Transaction.Find("the_transaction_id");
C♯

Escrow status on Marketplace transactions

Use the transaction's Id to find the EscrowStatus on Marketplace transactions:

transaction = gateway.Transaction.Find("the_transaction_id");
transaction.EscrowStatus;
// "held"
C♯

You can also search for transactions matching specific criteria using 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.