Transaction

Transaction: Search

Returns a collection of Transaction response objects.

For operators available on search fields, see the search fields page.

  1. Ruby
collection = gateway.transaction.search do |search|
  search.customer_id.is "the_customer_id"
end

collection.each do |transaction|
  puts transaction.amount
end
Parameters
:amountrange
The amount of the transaction. The amount must be formatted like xx or x.xx.
:authorization_expired_atrange
The date/time the transaction's authorization expired.
:authorized_atrange
The date/time the transaction was authorized.
:billing_companytext
The company name on the billing address used for the transaction.
:billing_country_nametext
The country name on the billing address used for the transaction.
:billing_extended_addresstext
The extended address on the billing address used for the transaction.
:billing_first_nametext
The first name on the billing address used for the transaction.
:billing_last_nametext
The last name on the billing address used for the transaction.
:billing_localitytext
The locality (e.g. city) on the billing address used for the transaction.
:billing_postal_codetext
The postal code on the billing address used for the transaction.
:billing_regiontext
The region (e.g. state) on the billing address used for the transaction.
:billing_street_addresstext
The street address on the billing address used for the transaction.
:created_atrange
The date/time at which the transaction was created.
:created_usingmultiple

The data used to create the transaction. Possible values:

  • Braintree::Transaction::CreatedUsing::Token
  • Braintree::Transaction::CreatedUsing::FullInformation
:credit_card_card_typemultiple

The type of credit card used in the transaction. Possible values:

  • "American Express"
  • "Discover"
  • "Maestro"
  • "JCB"
  • "MasterCard"
  • "UnionPay"
  • "Visa"
:credit_card_cardholder_nametext
The cardholder name in the transaction. This only applies to credit card transactions.
:credit_card_customer_locationmultiple

The location of the customer in the transaction. Possible values:

  • international
  • us
:credit_card_expiration_datetext
The expiration date of the card used in the transaction. This only applies to credit card transactions.
:credit_card_numbertext

The number of the card used in the transaction.

Card number search is restricted: starts with searches up to the first 6 digits, ends with searches last 4 digits, and contains is not allowed.

:credit_card_unique_identifiertext

The unique identifier of the card number. See the transaction response reference for more details.

:currencytext
The currency of the transaction.
:customer_companytext
The customer's company associated with the transaction.
:customer_emailtext
The customer's email address associated with the transaction.
:customer_faxtext
The customer's fax number associated with the transaction.
:customer_first_nametext
The customer's first name associated with the transaction.
:customer_idtext
A string value representing an existing customer in your Vault that is associated with the transaction.
:customer_last_nametext
The customer's last name associated with the transaction.
:customer_phonetext
The customer's phone number associated with the transaction.
:customer_websitetext
The customer's website associated with the transaction.
:debit_networkmultiple
The debit network to search for.
:disbursement_daterange

Only available for certain account types; contact us for details.

The date the transaction was disbursed to your bank account. This field does not include a time value.

:dispute_daterange

Only available for certain account types; contact us for details.

The date the transaction was disputed. This field does not include a time value.

:failed_atrange
The date/time the transaction failed.
:gateway_rejected_atrange
The date/time the transaction was rejected by the gateway.
:idtext
The ID of the transaction.
:idsmultiple
The list of transaction IDs to search for.
:merchant_account_idmultiple

The merchant account IDs associated with transactions.

:merchant_account_id_fragment

A fragment of the merchant account ID to search for.

:containstext
A part of the merchant account ID to search for.
:ends_withtext
A postfix for the merchant account ID to search for.
:istext
An exact merchant account ID to search for.
:is_nottext
A merchant account ID to be excluded from the search.
:starts_withtext
A prefix for the merchant account ID to search for.
:order_idtext
The order ID of the transaction. On PayPal transactions, this field maps to the PayPal invoice number. PayPal invoice numbers are unique in your PayPal business account. Maximum 255 characters or 127 for PayPal transactions.
:payment_method_tokentext
The payment method token used in the transaction.
:paypal_authorization_idtext
The Authorization ID for a PayPal transaction.
:paypal_payer_emailtext
The PayPal account holder's email for a PayPal transaction.
:paypal_payment_idtext
The identification value of the payment in PayPal's API for a PayPal transaction.
:processor_authorization_codetext
The authorization code returned by the processor for the transaction.
:processor_declined_atrange
The date/time the transaction was declined by the processor
:refundmultiple

Whether or not the transaction is a refund. The value may be either true or false. This parameter must be used in conjunction with type.

:settled_atrange
The date/time the transaction finished settling.
:settlement_batch_idtext
ID of the batch the transaction was submitted for settlement under.
:shipping_companytext
The company name on the shipping address used for the transaction.
:shipping_country_nametext
The country name on the shipping address used for the transaction.
:shipping_extended_addresstext
The extended address on the shipping address used for the transaction.
:shipping_first_nametext
The first name on the shipping address used for the transaction.
:shipping_last_nametext
The last name on the shipping address used for the transaction.
:shipping_localitytext
The locality (e.g. city) on the shipping address used for the transaction.
:shipping_postal_codetext
The postal code on the shipping address used for the transaction.
:shipping_regiontext
The region (e.g. state) on the shipping address used for the transaction.
:shipping_street_addresstext
The street address on the shipping address used for the transaction.
:sourcemultiple

How a transaction was created. Possible values:

  • Api
  • ControlPanel
  • Recurring
  • OAuth application client ID of the transaction facilitator
:statusmultiple

The list of statuses to search for. Possible statuses:

  • Authorizing
  • Authorized
  • AuthorizationExpired
  • SubmittedForSettlement
  • Settling
  • SettlementPending
  • SettlementDeclined
  • Settled
  • Voided
  • ProcessorDeclined
  • GatewayRejected
  • Failed
:submitted_for_settlement_atrange
The date/time the transaction was submitted for settlement.
:typemultiple

Possible values:

  • Sale
  • Credit
:usermultiple
A list of user IDs used to create the transaction. Specifically refers to Control Panel users and/or API users.
:voided_atrange
The date/time the transaction was voided.

Examplesanchor

Credit cardanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.credit_card_cardholder_name.is "Patrick Smith"
  search.credit_card_expiration_date.is "05/2012"
  search.credit_card_number.ends_with "1111"
end

Searching On Customer Detailsanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.customer_company.is "Braintree"
  search.customer_email.is "smith@example.com"
  search.customer_fax.is "5551231234"
  search.customer_first_name.is "Tom"
  search.customer_last_name.is "Smith"
  search.customer_phone.is "5551231234"
  search.customer_website.is "http://example.com"
end

See search fields for a list of available operators. They allow you to do nice things like this:

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.customer_email.ends_with "example.com"
end

Billing addressanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.billing_first_name.is "Paul"
  search.billing_last_name.is "Smith"
  search.billing_company.is "Braintree"
  search.billing_street_address.is "123 Main St"
  search.billing_extended_address.is "Suite 123"
  search.billing_locality.is "Chicago"
  search.billing_region.is "IL"
  search.billing_postal_code.is "12345"
  search.billing_country_name.is "United States of America"
end

Shipping addressanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.shipping_first_name.is "Paul"
  search.shipping_last_name.is "Smith"
  search.shipping_company.is "Braintree"
  search.shipping_street_address.is "123 Main St"
  search.shipping_extended_address.is "Suite 123"
  search.shipping_locality.is "Chicago"
  search.shipping_region.is "IL"
  search.shipping_postal_code.is "12345"
  search.shipping_country_name.is "United States of America"
end

Other top-level attributesanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.order_id.is "myorder"
  search.processor_authorization_code.is "123456"
end

Vault associationsanchor

You can search for transactions associated to a payment method token.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.payment_method_token.is "the_token"
end

How the transaction was createdanchor

You can search for transactions that were created using a token.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.created_using.is Braintree::Transaction::CreatedUsing::Token
end

Or transactions that were created using full credit card information.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.created_using.is Braintree::Transaction::CreatedUsing::FullInformation
end

Those are the only two choices for created_using.

Customer locationanchor

Customers in the US.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.credit_card_customer_location.is Braintree::CreditCard::CustomerLocation::US
end

Or international customers.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.credit_card_customer_location.is Braintree::CreditCard::CustomerLocation::International
end

Merchant accountanchor

A specific one.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.merchant_account_id.is "my_merchant_account"
end

Or any of several.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.merchant_account_id.in "account_1", "account_2"
end

Credit card typeanchor

A specific one.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.credit_card_card_type.is Braintree::CreditCard::CardType::Visa
end

Or any of several.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.credit_card_card_type.in(
    Braintree::CreditCard::CardType::Visa,
    Braintree::CreditCard::CardType::MasterCard,
    Braintree::CreditCard::CardType::Discover
  )
end

Transaction statusanchor

Another one or many search field.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.status.in(
    Braintree::Transaction::Status::ProcessorDeclined,
    Braintree::Transaction::Status::GatewayRejected
  )
end

Transaction sourceanchor

API, Control Panel, or Recurring Billing.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.source.in(
    Braintree::Transaction::Source::Api,
    Braintree::Transaction::Source::ControlPanel,
    Braintree::Transaction::Source::Recurring
  )
end

Transaction typeanchor

The two types of transactions are sale and credit. Refunds are a special kind of credit, so there are some extra options around them.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.type.is Braintree::Transaction::Type::Sale
end

This will return all credits, regardless of whether they're refunds, or standalone credits.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.type.is Braintree::Transaction::Type::Credit
end

If you only want the refunds:

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.type.is Braintree::Transaction::Type::Credit
  search.refund.is true
end

And if you only want the credits that aren't refunds:

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.type.is Braintree::Transaction::Type::Credit
  search.refund.is false
end

Amountanchor

It's a range field.

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.amount.between "100.00", "200.00"
end

search_results = gateway.transaction.search do |search|
  search.amount >= "100.00"
end

search_results = gateway.transaction.search do |search|
  search.amount <= "100.00"
end

Status changesanchor

You can search for transactions that entered a given status at a certain date and time. For instance, you can find all transactions which were submitted for settlement in the past 3 days.

You can search on these statuses:

  • created_at
  • authorized_at
  • submitted_for_settlement_at
  • settled_at
  • voided_at
  • processor_declined_at
  • gateway_rejected_at
  • failed_at
  • authorization_expired_at

A few examples:

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.created_at >= Time.now - 60*60*24 # a day ago
end
  1. Ruby
search_results = gateway.transaction.search do |search|
  search.settled_at >= Time.now - 60*60*24 # a day ago
end
  1. Ruby
search_results = gateway.transaction.search do |search|
  search.processor_declined_at >= Time.now - 60*60*24 # a day ago
end

Dispute date rangeanchor

  1. Ruby
search_results = gateway.transaction.search do |search|
  search.dispute_date >= Time.now - 60*60*24 # a day ago
end
note

Time zones specified in the time value will be respected in the search; if you do not specify a time zone, the search will default to the time zone associated with your gateway account. Results will always be returned with time values in UTC.

See also