Documentation

Quick Start

So you want to start processing transactions via Spreedly Core? Well, you’ve come to the right place. The Quick Start walks you through the whole process of using Spreedly Core to run a transaction. And yet it’s still a quick guide, since Spreedly Core (hereafter referred to as simply “Core”) simplifies everything related to processing transactions.

Sign up and create an environment

The first step is to sign up for a test account and create an environment. To do that, just sign up, go to the Environments area, and “Create Environment”. You can name the environment whatever you’d like; “Test” is probably a good choice for testing out the API.

Once you have an environment, grab its “Environment Key” for later use. This key will be passed as the username when you’re authenticating to the API.

Grab your Access Secret

The Access Secret will be passed as the password when you’re authenticating to the API. Every user in Spreedly has their own Access Secret; you can also create and manage named Access Secrets in the Organization settings (handy for production, or shared dev environments). For now just grab your personal Access Secret from your User profile page and use that.

Authenticating to the API

Core leverages standard HTTP Basic Authentication for API requests. To use it, simply pass the Environment Key for the environment you want to use as the username, and an Access Secret as the password. With curl it looks something like this:

$ curl -u 'environment-key:access-secret' <options> <url>

That’s all there is to it! You’ll see real examples with real options and appropriate urls in the remainder of the docs.

We demonstrate how to use the API with curl, but know that you can connect to the Spreedly API using any language you’d like.

Add payment gateway

Before you can start running transactions you need to add a payment gateway to Core to run transactions against. Since you probably don’t have a real gateway ready to go yet, and you want to test Core out before adding it anyhow, just add a Test Gateway for now:

$ curl https://core.spreedly.com/v1/gateways.xml \
    -u 'Ll6fAtoVSTyVMlJEmtpoJV8Shw5:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSylzM2ZzTWFwVH4ucG' \
    -H 'Content-Type: application/xml' \
    -d '<gateway>
          <gateway_type>test</gateway_type>
        </gateway>'

If it’s successful, the response will look like this:

<gateway>
  <token>HqHC9sjxbkac2tfgYgnDNqrt1r1</token>
  <gateway_type>test</gateway_type>
  <name>Spreedly Test</name>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_reference_purchase type="boolean">true</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_specific_fields/>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>sprel</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>bank_account</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="datetime">2014-04-23T18:30:23Z</created_at>
  <updated_at type="datetime">2014-04-23T18:30:23Z</updated_at>
</gateway>

Note the token field - grab the contents of that and save it somewhere handy, as we’ll use it momentarily to run transactions.

Once you have a payment gateway token, you can use it for future transactions. You don’t need to create a gateway each time you’d like to run a payment transaction; just use the token you’ve saved.

Submit payment form

The next step is where things get really magical - you’re going to collect a credit card and pass it to Core without ever touching any of the sensitive information. This works via a process called a “transparent redirect”. First, build a payment form:

<form accept-charset="UTF-8" action="https://core.spreedly.com/v1/payment_methods" method="POST">
    <fieldset>
        <input name="redirect_url" type="hidden" value="http://example.com/transparent_redirect_complete" />
        <input name="environment_key" type="hidden" value="Ll6fAtoVSTyVMlJEmtpoJV8Shw5" />
        <input name="utf8" type="hidden" value="✓">

        <label for="credit_card_first_name">First name</label>
        <input id="credit_card_first_name" name="credit_card[first_name]" type="text" />

        <label for="credit_card_last_name">Last name</label>
        <input id="credit_card_last_name" name="credit_card[last_name]" type="text" />

        <label for="credit_card_number">Card Number</label>
        <input autocomplete="off" id="credit_card_number" name="credit_card[number]" type="text" />

        <label for="credit_card_verification_value">Security Code</label>
        <input autocomplete="off" id="credit_card_verification_value" name="credit_card[verification_value]" type="text" />

        <label for="credit_card_month">Expires on</label>
        <input id="credit_card_month" name="credit_card[month]" type="text" />
        <input id="credit_card_year" name="credit_card[year]" type="text" />

        <button type='submit'>Submit Payment</button>
    </fieldset>
</form>

The names of the input fields are critical, but other than that you have complete control - you can style, layout, and beautify your payment form however you’d like.

Notice the autocomplete="off" attribute on the card number and verification value fields. This is a way to tell browsers to not store these fields in plaintext somewhere on the computer, which is even more important for customers using public computers.

The utf8 hidden field ensures that older versions of Internet Explorer will correctly encode the strings it sends as UTF-8.

NOTE: you do still need to have an SSL certificate for your payment form page. This gives customers confidence in your payment process, and prevents a malicious middle man from tampering with your payment form before it gets to the customer.

Notice the action attribute - this form POST`s directly to Core. Once Core has recorded the information, it will redirect the browser to the url specified in the redirect_url field, tacking on a token that represents the credit card the customer entered. You should then save that returned token - you’ll use it to actually run the payment. In this case the user would be sent to this url:

http://example.com/transparent_redirect_complete?token=X0scBRLPXH1dScb5LGMIcv2qNlE

Of course you don’t have to add a real credit card in order to test this out: Core has a set of test cards you can use against a Test Gateway, as well as a simple means of triggering specific errors for testing purposes.

You can also collect other fields such as the billing address and email if you’d like. We have details here.

We also have an API method to directly add a payment method if you’d prefer to avoid the transparent redirect.

Process payment

Submitting the payment form to Core doesn’t do anything except store that payment method - regardless of whether it’s valid or not - for later usage. Now that you have a token representing the payment method in hand, you can actually run a charge:

$ curl https://core.spreedly.com/v1/gateways/HqHC9sjxbkac2tfgYgnDNqrt1r1/purchase.xml \
  -u 'Ll6fAtoVSTyVMlJEmtpoJV8Shw5:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSylzM2ZzTWFwVH4ucG' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <payment_method_token>X0scBRLPXH1dScb5LGMIcv2qNlE</payment_method_token>
      </transaction>'

The amount is always given as an integer number of cents. So if you’d like to run a purchase of $83.45, you’d pass an amount of 8345.

Core will return a response that looks like this:

<transaction>
  <amount type="integer">100</amount>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="datetime">2014-04-23T18:30:23Z</created_at>
  <updated_at type="datetime">2014-04-23T18:30:23Z</updated_at>
  <currency_code>USD</currency_code>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>Uq4GcgfHI8Sp5gYEH7fT3lsIY2V</token>
  <transaction_type>Purchase</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <gateway_specific_fields nil="true"/>
  <gateway_specific_response_fields nil="true"/>
  <gateway_transaction_id>49</gateway_transaction_id>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>HqHC9sjxbkac2tfgYgnDNqrt1r1</gateway_token>
  <response>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <error_code></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <created_at type="datetime">2014-04-23T18:30:23Z</created_at>
    <updated_at type="datetime">2014-04-23T18:30:23Z</updated_at>
  </response>
  <payment_method>
    <token>X0scBRLPXH1dScb5LGMIcv2qNlE</token>
    <created_at type="datetime">2014-04-23T18:30:23Z</created_at>
    <updated_at type="datetime">2014-04-23T18:30:23Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>used</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Bob</first_name>
    <last_name>Smith</last_name>
    <month type="integer">1</month>
    <year type="integer">2020</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <full_name>Bob Smith</full_name>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
  </payment_method>
  <api_urls>
  </api_urls>
</transaction>

And once you have that you can show a success page to your customer - you’ve successfully collected payment!

Error handling

But of course, things don’t go exactly right all the time. Often, trying to run a transaction will generate an error. It might be that the payment information is invalid, the bank thinks the transaction looks fishy, or the payment gateway is temporarily unavailable. Core makes it easy to handle all of these errors by giving you a very consistent set of information on a failed transaction.

Wrap-up

Now you’ve seen how to go end-to-end with a complete purchase, as well as handling any errors that come up along the way. The next step is to work through the other guides in the sidebar to the left. And of course, don’t hesitate to drop us a line at support@spreedly.com - we’re happy to help any time!