A convenient Ruby wrapper for the Spreedly API.
This is an example Ruby integration with Spreedly. This version is no longer actively updated and will be superseded by a new version in the near future. Feature parity may lag behind, so please use this gem at your own risk.
- No global configuration of authentication credentials.
- No implicit calls to the Spreedly server.
- Don't be too clever. The real goal is for this to be a thin and simple layer over the API. The correlation between an API call and a ruby method should be as clear as possible.
- Avoid the approach of using a proxy that at some point gets filled in with data from the server.
- Avoid self-mutation and prefer value objects. This isn't ActiveRecord so we won't be doing things like gateway.update_attributes(attributes).
- Don't try to improve the interface of the API by doing cool Ruby things in the gem which fix or hide icky parts of the API. Instead, improve the underlying API to reflect the improvements and then adjust the gem to use the improved underlying API.
- Limit the number of dependencies on other gems to make it as easy possible to incorporate the gem into any project. Resist the temptation to use the goodness in gems like ActiveSupport or ActiveModel.
If you're using bundler, add the gem to your Gemfile:
gem 'spreedly'
Otherwise gem install:
$ gem install spreedly
Let's start with a simple purchase when you already have a gateway token and a payment method token:
env = Spreedly::Environment.new(environment_key, access_secret)
transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
transaction.succeeded? # => true
transaction.token # => "aGJlY5srn7TFeYKxO5pmwi3CyJd"The amount specified in that example was 4432. Amounts are always in cents so in this case, we're charging $44.32.
What if you don't have a gateway token yet? It's pretty easy to add a test gateway:
gateway = env.add_gateway(:test)
gateway.token # => "DnbEJaaY2egcVkCvg3s8qT38xgt"Need a payment method token to try things out? With Spreedly it's pretty straightforward to use a transparent redirect to give you a payment method token. A payment form in your application could look something like this:
<form action="<%= env.transparent_redirect_form_action %>" method="POST">
<fieldset>
<input name="redirect_url" type="hidden" value="http://yourdomain.com/transparent_redirect_done" />
<input name="environment_key" type="hidden" value="<%= env.key %>" />
<label for="credit_card_full_name">Name</label>
<input id="credit_card_full_name" name="credit_card[full_name]" type="text" />
<label for="credit_card_number">Card Number</label>
<input id="credit_card_number" name="credit_card[number]" type="text" />
<label for="credit_card_verification_value">Security Code</label>
<input 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>Notice that we can ask the environment for the form action url and that the environment knows its key to use in the hidden field.
Once Spreedly 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 your customer entered. This is the payment_method token you're looking for. In this case your customer would be sent to this url:
http://yourdomain.com/transparent_redirect_done?token=OEj2G2QJZM4C10AfTLYTrsKIsZH
Once you have the payment method token (OEj2G2QJZM4C10AfTLYTrsKIsZH in this case), you can remember it and use it whenever you'd like. These test cards will help.
Let's say you'd like some additional information about the payment method. You can find a payment method like so:
credit_card = env.find_payment_method(token)
credit_card.last_name # => "Jones"
credit_card.valid? # => false
credit_card.errors
# Returns => [
# { attribute: "first_name", key: "errors.blank", message: "First name can't be blank" },
# { attribute: "year", key: "errors.expired", message: "Year is expired" },
# { attribute: "year", key: "errors.invalid", message: "Year is invalid" },
# { attribute: "number", key: "errors.blank", message: "Number can't be blank" }
# ]auth_transaction = env.authorize_on_gateway(gateway_token, payment_method_token, 250)
if auth_transaction.succeeded?
capture_transaction = env.capture_transaction(auth_transaction.token)
endYou can also specify an optional amount to capture.
capture_transaction = env.capture_transaction(auth_transaction.token, amount: 100)Verify a card is legitimate so you can charge it at a later date.
env.verify_on_gateway(gateway_token, payment_method_token, retain_on_success: true)transaction = env.void_transaction(transaction_token)
# Refund the entire amount
transaction = env.refund_transaction(transaction_token)
# Specify an amount to be refunded
transaction = env.refund_transaction(transaction_token, amount: 104)transaction = env.retain_payment_method(payment_method_token)
transaction = env.redact_payment_method(payment_method_token)transaction = env.redact_gateway(gateway_token)When you instantiate an environment, you can specify a default currency code like so:
env = Spreedly::Environment.new(environment_key, access_secret, currency_code: 'EUR')If you don't specify a default currency code, we default to 'USD'. Calls requiring a currency code by default use the environment's currency code. And of course, you can always override it for a particular call like so:
env.purchase_on_gateway(gateway_token, payment_method_token, amount, currency_code: "GBP")For Purchase, Authorize, Capture, Refund, Verify, and Void calls, you can specify additional options:
env.purchase_on_gateway(gateway_token, payment_method_token, amount,
order_id: "123",
description: "The Description",
ip: "192.31.123.112",
merchant_name_descriptor: "SuperDuper Corp",
merchant_location_descriptor: "http://super.com"
)env.complete_transaction(transaction_token)Retain a payment method automatically if the purchase, verify, or authorize transaction succeeded. Saves you a separate call to retain:
env.purchase_on_gateway(gateway_token, payment_method_token, amount, retain_on_success: true)env.verify_on_gateway(gateway_token, payment_method_token, retain_on_success: true)gateways = env.list_gateways
# Iterate over the next chunk
next_set = env.list_gateways(gateways.last.token)payment_methods = env.list_payment_methods
# Iterate over the next chunk
next_set = env.list_payment_methods(payment_methods.last.token)transactions = env.list_transactions
# Iterate over the next chunk
next_set = env.list_transactions(transactions.last.token)transactions = env.list_transactions(nil, payment_method_token)
# Iterate over the next chunk
next_set = env.list_transactions(transactions.last.token, payment_method_token)gateway = env.find_gateway(token)
gateway.gateway_type # => 'paypal'transaction = env.find_transaction(token)
transaction.order_id # => '30-9904-31114'env.find_transcript(transaction_token)env.update_credit_card(credit_card_token, first_name: 'JimBob', last_name: 'Jones')gateway = env.add_gateway(:paypal, mode: 'delegate', email: '[email protected]')
gateway.token # => "2nQEJaaY3egcVkCvg2s9qT37xrb"The primary mechanism to add a credit card is to use the transparent redirect payment form. This allows all of the sensitive information to be captured without ever touching your servers.
There are times though when you may want to add a credit card in a more "manual" fashion with an API call.
PLEASE NOTE: Using this API call can significantly increase your PCI compliance requirements.
Here's how you can do it:
options = {
email: '[email protected]', number: '5555555555554444', month: 1, year: 2023, last_name: 'Aybara', first_name: 'Perrin', data: "occupation: Blacksmith"
}
transaction = env.add_credit_card(options)
transaction.token # => "2nQEJaaY3egcVkCvg2s9qT37xrb"
transaction.payment_method.token # => "7rbEKaaY0egcBkCrg2sbqTo7Qrb"
transaction.payment_method.last_name # => "Aybara"You can also retain the card immediately like so:
options = {
email: '[email protected]', number: '5555555555554444', month: 1, year: 2023, last_name: 'Aybara', first_name: 'Perrin', data: "occupation: Blacksmith", retained: true
}
transaction = env.add_credit_card(options)
transaction.payment_method.storage_state # => "retained"And you might want to specify a number of other details like the billing address, etc:
options = {
email: '[email protected]', number: '9555555555554444', month: 3, year: 2021, last_name: 'Smedry', first_name: 'Leavenworth', data: "talent: Late", address1: '10 Dragon Lane', address2: 'Suite 9', city: 'Tuki Tuki', state: 'Mokia', zip: '1122', country: 'Free Kingdoms', phone_number: '81Ab', retained: true
}
transaction = env.add_credit_card(options)
transaction.payment_method.last_name # => "Smedry"You can get the full list of supported gateways like so:
env.gateway_optionsYou can get the full list of supported receivers like so:
env.receiver_optionsYou can deliver a payment method to a third party using Payment Method Distribution. Once a receiver is set up and you have a payment method that you would like to share, you can use the following call:
env.deliver_to_receiver(
"receiver token goes here",
"payment method token goes here",
headers: { "Content-Type": "application/json" },
url: "https://spreedly-echo.herokuapp.com",
body: { card_number: "{{credit_card_number}}" }.to_json
)When you make a call to the API, there are times when things don't go as expected. For the most part, when a call is made, a Transaction is created behind the scenes at Spreedly. In general, you can inquire whether that transaction succeeded? or not and get it's message. There are times when a Transaction cannot be created, and in general, an exception is raised for these cases.
You can be as specific as you'd like in handling these exceptions or, you could simply rescue Spreedly::Error to handle all of them.
transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
transaction.succeeded? # => false
transaction.message # => "Unable to process the purchase transaction."transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
transaction.succeeded? # => false
transaction.message # => "The payment method is invalid."
transaction.payment_method.errors
transaction.payment_method.errors
# Returns => [
# { attribute: "last_name", key: "errors.blank", message: "Last name can't be blank" },
# { attribute: "number", key: "errors.blank", message: "Number can't be blank" }
# ]env.find_transaction("Some Unknown Token") # raises a Spreedly::NotFoundErrorenv = Spreedly::Environment.new(environment_key, "some bogus secret")
env.purchase_on_gateway(gateway_token, payment_method_token, 4432) # Raises Spreedly::AuthenticationErrorenv.purchase_on_gateway(gateway_token, "Some Unknown Token", 4432) # Raises Spreedly::TransactionCreationErrorYou're free to use test card data and a Test gateway to integrate Spreedly without having a paid Spreedly account. If you try to use a real card or a real gateway when your account isn't yet paid for, we'll raise an exception:
env.purchase_on_gateway(gateway_token, "Payment Method Token for a real card", 4432) # Raises Spreedly::PaymentRequiredErrorIf Spreedly is not responding, we'll raise an exception. Spreedly itself has a timeout so that if a gateway isn't responding, it'll reflect that in the response. The gem has its own timeout to handle the case of Spreedly itself not responding. Here's an example:
env.purchase_on_gateway(gateway_token, payment_method_token, 802) # Raises Spreedly::TimeoutErrorFor api calls that actually talk to a payment gateway, the timout is longer since some gateways can take longer to respond when under load.
There are some sample applications with source code using this gem. You can find them here.
We're happy to consider pull requests.
There are two rake tasks to help run the tests:
rake test:remote # Run remote tests that actually hit the Spreedly site
rake test:units # Run unit tests
To run remote tests you'll need to copy test/credentials/credentials.yml.example to test/credentials/credentials.yml and update the values of environment_key and access_secret.
When you're happy with your change, don't forget to add your contributions to CHANGELOG.md. We follow the changelog format found here.