Transparent Redirect

Creating Transactionsanchor

note

The integration method outlined below is to be sunset in early 2024. To prevent any disruptions to your payment processing; we recommend upgrading to Braintree’s Drop-in integration.

To create transactions using Transparent Redirect, you’ll need to build an HTML form that submits directly to Braintree.

Form action URLanchor

  1. HTML
<form method="POST" action="<%= Braintree::TransparentRedirect.url %>">

TR dataanchor

The form needs to include a hidden field named tr_data. It needs to include the URL that Braintree will redirect the user to after storing the form params. You should also include any parameter that you want to send to Braintree that you’re not asking your users to enter. For example, you will want to include the amount for the transaction in tr_data unless you’re asking the user to enter it, as in a donation site.

Generating the TR Data:

  1. Ruby
tr_data = Braintree::TransparentRedirect.transaction_data(
      :redirect_url => "http://example.com/url_to_redirect_to",
      :transaction => {
        :type => "sale",
        :amount => "10.00"
      }
    )

Then use a hidden field to add to your form:

  1. HTML
<input type="hidden" name="tr_data" value="<%= tr_data %>" />

TR form fieldsanchor

Create text fields for data parameters that you want to have your users enter. At minimum you will need to have the credit card number and expiration date.

  1. HTML
<input type="text" name="transaction[credit_card][number]" />
    <input type="text" name="transaction[credit_card][expiration_date]" />

You can also include customer, billing, and shipping fields. For example:

  1. HTML
<input type="text" name="transaction[customer][email]" />
    <input type="text" name="transaction[billing][postal_code]" />

See the full list of TR HTML fields.

TR confirmationanchor

Before the transaction is actually processed, you will need to confirm it. For the confirmation, you will need to use the query string from the URL on the redirect. Braintree will add parameters to the query string that identify the request, so the redirect URL will look something like:

  1. HTML
http://example.com/path?http_status=200&id=vgqssrhqhxfhgrwz&hash=0c3c641f1de3ed1c732c54cab367355350603b28

Use the query string to confirm. You’ll receive a result object just like if you created a transaction using a client library.

  1. Ruby
result = Braintree::TransparentRedirect.confirm(query_string)

Error handlinganchor

While confirming a transparent redirect transaction, you may encounter a Braintree::NotFoundError.

If you see this error, then this is what is most likely happening:

  • A user posts a form directly to Braintree
  • Braintree creates a Transparent Redirect Request
  • a token is generated to represent this request
  • The user is redirected to the passed URL along with the generated token
  • The code on the passed URL uses the token to ask Braintree for the response to the Transparent Redirect Request (this happens in the "confirm" method)
  • Braintree consumes the token representing the Transparent Redirect request.
  • Braintree sends you the response details.

If a user refreshes on your redirect URL page (or if they use the back button to return to it), your code might be calling the "confirm" method again with the same token, which has been already consumed by Braintree.

Solutions may include catching this exception upon confirmation, or storing details of the original successful confirmation in the user's session.