Transparent Redirect Basics

The Scenario

You want to collect credit card or echeck payment information from your customers without having the information touch your servers.

The Transparent Redirect authentication method with the Payment Processing API allows the card holder to directly post payment information to the Braintree Payment Gateway and responds to the customer’s browser with a redirect back to the merchant’s application to parse the response and return a final response to the customer.

This is accomplished by passing several hidden values with the POST action to the payment gateway, which I’ll cover below. The key to communicating with the gateway via Transparent Redirect is that you need to generate a security hash using the MD5 algorithm.

The Setup

To generate a form on your website that will use the transparent redirect method, you’ll need to collect a couple of pieces of information from the Virtual Terminal. You can find them in the Terminal under Options -> Security Keys. You’ll need the key and the key_id.

You can always use the Default Key that gets generated by Braintree when your account is created, but I always create my own key and generally name it ‘api’. For extra security, changes your key and key id once a month. Your key_id could be seen if the customer looks at the generated HTML of the form, but that’s not really a concern as long as you don’t allow anyone to see your key. A compromised key will mean that someone could potentially refund money from your account. Refunds are turned off by default, but it’s something to be aware of if they are enabled.

While I’m talking about security, it’s also a good idea to setup IP Restrictions in the Virtual Terminal. This means that even if someone gets your key, they’ll have to make requests from your server to make any transactions. IP Restrictions can be set in the Virtual Terminal under Options -> IP Restrictions.

You can configure by IP or hostname. Look for an in-depth article that deals IP restrictions in the future. With those 2 pieces of information in hand, we can begin to setup our forms.

How To Do It

I’m going to show you how to craft the form now. I’m going to try to keep it as language agnostic as possible, so you’ll need to figure out how your application framework would generate this HTML. Braintree is committed to superior customer support, so if you run into troubles, please try the Braintree Developer Forums, or send us an email to support AT getbraintree.com.

Generating the Proper Hash

The first thing that we need to do is to ensure that we’re generating the proper hash. This is often the biggest hurdle to overcome when trying to authenticate with transparent redirect authentication. The inbound hash requires several variables to be hashed, delimited by pipes(|). This hash is what protects several pieces of valuable information, namely the amount and the orderid. In addition to that, you’ll also need your key from the Virtual Terminal and a time value.

orderid – This is the order id from your application, you can generate it in any manner you choose. It can be in any format you, for this example I’ll use 123456-xfj.
amount – This is the amount of the order in X.XX format. For this example, I’ll be billing for $10.00, so 10.00.
time – This is the time that the form is generated in YYYYMMDDHHMMSS format, based on UTC (Coordinated Universal Time). This value is associated with the hash to protect a form from being used over an extended period of time. The gateway will reject times that are over 15 minutes old. For this example, I’m going to use 20080516190549.
key – This is the value that you copied from the Virtual Terminal. Make sure this is the key, and not the key_id. For this example, I’m going to use the key, XaE9eAYQdpr3cJp33G9rq24rKX2Mhkuh.

The final string to hash will be this:

123456-xfj|10.00|20080516190549|XaE9eAYQdpr3cJp33G9rq24rKX2Mhkuh

If you choose to leave orderid blank, you may, but remember to include an extra pipe(|) at the beginning. You can test your generated hash at our Tools site. This can be used to check your hash. Generate a hash using your application of choice. Enter the same values in the Hasher tool, and check the values.

Your response will look similar:

If the values match, we’re ready to move on to the next step. If not, you should check to make sure that you don’t have any non-ASCII characters in your orderid.

Generating the Form HTML

Now that we know that our hash is correct we can start to create our form. We’re going to start with an empty form with the action set to the Braintree Payment Gateway and a submit button.

   1  
   2  <form method="post" action="https://secure.braintreepaymentgateway.com/api/transact.php>
   3    <p><input type="submit" value="Submit" name="commit"/></p>
   4  </form>

From there we’re going to add the hidden fields that are necessary to help authenticate the hash. We need to add the orderid, amount, time, hash, and key_id. We need to pass these values as hidden inputs so we can generate a matching hash based upon the values that you send us. NOTE We use the key_id that gets sent to look up your key value to hash so make sure your key is never visible. From we’ve got above and our hidden inputs will make the form look like this:

   1  
   2  <form method="post" action="https://secure.braintreepaymentgateway.com/api/transact.php>
   3    <input id="key_id" type="hidden" value="532515" name="key_id"/>
   4    <input id="orderid" type="hidden" value="123456-xfj" name="orderid"/>
   5    <input id="amount" type="hidden" value="10.00" name="amount"/>
   6    <input id="time" type="hidden" value="20080516190549" name="time"/>
   7    <input id="hash" type="hidden" value="21bd7e62a8cbdddf84457702c71a4568" name="hash"/>
   8    <p><input type="submit" value="Submit" name="commit"/></p>
   9  </form>

The next thing to add is a transaction type, in this case type=sale. This is the default value for transactions, but it’s always a good practice to include it.

   1  
   2  <form method="post" action="https://secure.braintreepaymentgateway.com/api/transact.php>
   3    <input id="type" type="hidden" value="sale" name="type"/>
   4    <input id="key_id" type="hidden" value="532515" name="key_id"/>
   5    <input id="orderid" type="hidden" value="123456-xfj" name="orderid"/>
   6    <input id="amount" type="hidden" value="10.00" name="amount"/>
   7    <input id="time" type="hidden" value="20080516190549" name="time"/>
   8    <input id="hash" type="hidden" value="21bd7e62a8cbdddf84457702c71a4568" name="hash"/>
   9    <p><input type="submit" value="Submit" name="commit"/></p>
  10  </form>

Now we need to add the fields for the customer to input their credit card information into. The bare minimum required with Braintree is ccnumber and ccexp. You could also include any number of other values supported by Braintree, see the API Documention for more information.

   1  
   2  <form method="post" action="https://secure.braintreepaymentgateway.com/api/transact.php>
   3    <input id="type" type="hidden" value="sale" name="type"/>
   4    <input id="key_id" type="hidden" value="532515" name="key_id"/>
   5    <input id="orderid" type="hidden" value="123456-xfj" name="orderid"/>
   6    <input id="amount" type="hidden" value="10.00" name="amount"/>
   7    <input id="time" type="hidden" value="20080516190549" name="time"/>
   8    <input id="hash" type="hidden" value="21bd7e62a8cbdddf84457702c71a4568" name="hash"/>
   9    <p>
  10     <label for="ccnumber">Credit Card Number</label><br/>
  11     <input id="ccnumber" type="text" name="ccnumber"/>
  12    </p>
  13    <p>
  14      <label for="ccexp">Credit Card Expiration</label>
  15      <em>MMYY format, ie. 1010 for October, 2010</em><br/>
  16      <input id="ccexp" type="text" name="ccexp"/>
  17    </p>
  18    <p><input type="submit" value="Submit" name="commit"/></p>
  19  </form>

The last item we’re going to add is the response URL for the transparent redirect to point to. This hidden value should be the URL in your application that is capable of accepting and parsing a response from the gateway. You need to include the full domain for this value. NOTE You can append any other values such as a session id or some such other identifier. For this example, I’m going to use the response url of http://example.tld/gateway_response.

   1  
   2  <form method="post" action="https://secure.braintreepaymentgateway.com/api/transact.php>
   3    <input id="type" type="hidden" value="sale" name="type"/>
   4    <input id="key_id" type="hidden" value="532515" name="key_id"/>
   5    <input id="orderid" type="hidden" value="123456-xfj" name="orderid"/>
   6    <input id="amount" type="hidden" value="10.00" name="amount"/>
   7    <input id="time" type="hidden" value="20080516190549" name="time"/>
   8    <input id="hash" type="hidden" value="21bd7e62a8cbdddf84457702c71a4568" name="hash"/>
   9    <input id="redirect" type="hidden" value="http://example.tld/gateway_response" name="redirect"/>
  10    <p>
  11     <label for="ccnumber">Credit Card Number</label><br/>
  12     <input id="ccnumber" type="text" name="ccnumber"/>
  13    </p>
  14    <p>
  15      <label for="ccexp">Credit Card Expiration</label>
  16      <em>MMYY format, ie. 1010 for October, 2010</em><br/>
  17      <input id="ccexp" type="text" name="ccexp"/>
  18    </p>
  19    <p><input type="submit" value="Submit" name="commit"/></p>
  20  </form>

This is all we need to make a Transparent Redirect request with Braintree. When POSTed, this form will hit our gateway, where it will be processed and a response will be returned through the customer’s browser to your servers. NOTE At this time, you cannot include any other values outside of information that will either be inserted into the SecureVault, or part of a transaction. Please consult the documentation for more information on the response that is returned and how to use the Transparent Redirect to insert customer information into the SecureVault.

Discussion

Please ask any questions on this article in the Articles Discussion Forum.

Developer Community