tray-checkout
Library to provide access to TrayCheckout’s API.
Note: This version is not compatible with the 0.2.1, for the new API version (v2) is not compatible with the old (v1).
Installing
Gemfile
gem 'tray-checkout'
Direct installation
$ gem install tray-checkout
Using
require 'tray-checkout'
transaction = Tray::Checkout::Transaction.new
Getting an existing transaction:
response = transaction.get("522045453u5uu32e0u8014f060uuu5uu")
response.success? # => true
# Transaction
response.transaction[:token] # => "522045453u5uu32e0u8014f060uuu5uu"
response.transaction[:id] # => 501
response.transaction[:status] # => :waiting_payment
response.transaction[:status_name] # => "Aguardando Pagamento"
response.transaction[:price_payment] # => 213.21
response.transaction[:price_seller] # => 199.19
response.transaction[:split] # => 1
response.transaction[:date_transaction].strftime("%d/%m/%Y") # => "03/12/2012"
# Payment
response.payment[:method] # => :boleto
response.payment[:method_name] # => "Boleto Bancario"
response.payment[:price] # => 213.21
response.payment[:split] # => 1
response.payment[:url] # => "http://checkout.sandbox.tray.com.br/payment/billet/u9uuu8731319u59u3073u9011uu6u6uu"
# Customer
response.customer[:name] # => "Pedro Bonamides"
response.customer[:email] # => "[email protected]"
response.customer[:cpf] # => "18565842673"
When the transaction is not found:
response = transaction.get("xxxxx00000yyyy")
response.success? # => false
response.transaction[:id] # => nil
response.errors.first[:code] # => "003042"
response.errors.first[:message] # => "Transação não encontrada"
Creating a successful transaction:
response = transaction.create(
token_account: "123u5uu9ef36f7u",
customer: {
name: "Pedro Bonamides",
cpf: "18565842673",
email: "[email protected]",
sex: :male,
marital_status: :single,
contacts: [
{ type: :home,
number: "1142360873"
}
],
addresses: [
{ type: :billing,
street: "Avenida Pedro Alvares Cabral",
number: "123",
neighborhood: "Parque Ibirapuera",
postal_code: "04094050",
city: "São Paulo",
state: "SP"
}
]
},
transaction: {
order_number: "R1245",
shipping_type: "Sedex",
shipping_price: 13.94,
url_notification: "http://prodis.blog.br/tray_notification"
products: [
{ code: "LOGO-8278",
quantity: 2,
price_unit: 100.99,
description: "Logo Prodis"
},
{ code: "877",
quantity: 1,
price_unit: 10.00,
description: "Outro produto"
}
]
},
payment: {
method: :mastercard,
split: 3,
card: {
name: "ZEFINHA NOCEGA",
number: "5105105105105100",
expdate_month: "09",
expdate_year: "2015",
cvv: "123"
}
}
)
response.success? # => true
# Transaction
response.transaction[:token] # => "87654321u5uu92e4u09876543uuu5uu"
response.transaction[:id] # => 503
response.transaction[:status] # => :approved
response.transaction[:status_name] # => "Aprovada"
response.transaction[:price_payment] # => 213.21
response.transaction[:price_seller] # => 199.19
response.transaction[:split] # => 3
response.transaction[:date_transaction].strftime("%d/%m/%Y") # => "05/12/2012"
# Payment
response.payment[:method] # => :mastercard
response.payment[:method_name] # => "Mastercard"
response.payment[:price] # => 213.21
response.payment[:split] # => 3
response.payment[:url] # => "http://checkout.sandbox.tray.com.br/payment/billet/u9uuu8731319u59u3073u9011uu6u6uu"
# Customer
response.customer[:name] # => "Pedro Bonamides"
response.customer[:email] # => "[email protected]"
response.customer[:cpf] # => "18565842673"
Temp Transactions (Carts)
You can create or update carts through the Tray::Checkout::TempTransaction class:
temp_transaction = Tray::Checkout::TempTransaction.new
temp_transaction.add_to_cart(
token_account: "8bfe5ddcb77107b",
postal_code_seller: "18524698",
transaction: {
order_number: "1234567",
free: "Texto Interno",
url_notification: "http://prodis.blog.br/tray_notification",
products: [
{
code: "teste",
description: "Notebook Branco",
quantity: "1",
price_unit: "2199.99",
weight: "300",
url_img: "http://catnross.com/wp-content/uploads/2011/08/product1.jpg"
}
]
}
)
response.success? # => true
response[:token] # => a906bf32cb59060dfc90769524f99d4a
response[:url_car] # => http://checkout.sandbox.tray.com.br/payment/car/v1/
# Products
response[:products].first[:code] # => teste
response[:products].first[:img] # => http://catnross.com/wp-content/uploads/2011/08/product1.jpg
response[:products].first[:sku_code] # => nil
response[:products].first[:description] # => Notebook Branco
response[:products].first[:extra] # => nil
response[:products].first[:price_unit] # => 2199.99
response[:products].first[:quantity] # => 1.0
response[:products].first[:weight] # => 300.0
response[:products].first[:id] # => 4502
response[:products].first[:type_product] # => nil
After creating a cart you can forward your client using the cart_url method:
temp_transaction = Tray::Checkout::TempTransaction.new
temp_transaction.cart_url # => http://checkout.sandbox.tray.com.br/payment/car/v1/a906bf32cb59060dfc90769524f99d4a
Account
You can check the existence as well as the info of an account through its token using the Account class:
account = Tray::Checkout::Account.new
response = account.get_by_token("8bfe5ddcb77107b")
When account is found
response.success? # => true
response.people[:name] # test
response.people[:email] # [email protected]
response.service_contact[service_phone] # (55) 5555-5555
response.service_contact[email_service] # [email protected]
response.seconds_redirect # seconds_redirect
When account is not found
response.success? # => false
response.people # => nil
response.errors.first[:code] # => "XXXXXX"
response.errors.first[:message] # => "<Error Message>"
Configurations
Environment
Tray Checkout API works with two environments: production and sandbox. To config the environment use Tray::Checkout module. Default environment is :production.
Tray::Checkout.configure do |config|
config.environment = :sandbox
end
Token Account
To create transactions is necessary to provide a token account. You can supply it in Tray::Checkout::Transaction#create method params, for each method call, or to config token account once using Tray::Checkout module.
Tray::Checkout.configure do |config|
config.token_account = "123u5uu9ef36f7u"
end
Timeout
For default, the timeout for a request to Tray Checkout API is 5 seconds. If Tray Checkout API does not respond, a Timeout::Error exception will be raised. You can configure this timeout using Tray::Checkout module.
Tray::Checkout.configure do |config|
config.request_timeout = 3 # It configures timeout to 3 seconds
end
HTTP Proxy
If you need to use an HTTP proxy to make Tray Checkout API, configure the HTTP proxy URL on Tray::Checkout module.
Tray::Checkout.configure do |config|
config.proxy_url = "http://10.20.30.40:8888"
end
Log
For default, each request to Tray Checkout API is logged to STDOUT, with :info log level, using the gem LogMe.
Log example:
I, [2013-01-11T00:55:10.531780 #22692] INFO -- : Tray-Checkout Request:
POST http://api.sandbox.traycheckout.com.br//v2/transactions/get_by_token
token=522045453u5uu32e0u8014f060uuu5uu
I, [2013-01-11T00:55:10.750308 #22692] INFO -- : Tray-Checkout Response:
HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data_response>
<transaction>
<order_number>1234567</order_number>
<free>Texto Interno</free>
<transaction_id type="integer">3856</transaction_id>
<status_name>Em Recupera\xC3\xA7\xC3\xA3o</status_name>
<status_id type="integer">88</status_id>
<token_transaction>522045453u5uu32e0u8014f060uuu5uu</token_transaction>
<payment>
<price_original type="decimal">2199.99</price_original>
<price_payment type="decimal">2199.99</price_payment>
<payment_response></payment_response>
<url_payment>http://gtw.sandbox.checkout.tray.com.br/api/print/0b525e9dbef558690477b815118aa033</url_payment>
<tid nil="true"/>
<split type="integer">1</split>
<payment_method_id type="integer">6</payment_method_id>
<payment_method_name>Boleto Bancario</payment_method_name>
<linha_digitavel>34191.76007 00536.260144 50565.600009 6 58630000219999</linha_digitavel>
</payment>
<customer>
<name>Nome do Cliente</name>
<cpf>98489882380</cpf>
<email>[email protected]</email>
<company_name></company_name>
<trade_name></trade_name>
<cnpj></cnpj>
<addresses type="array">
<address>
<street>Av Paulista</street>
<number>1001</number>
<neighborhood>Centro</neighborhood>
<postal_code>04001001</postal_code>
<completion></completion>
<city>S\xC3\xA3o Paulo</city>
<state>SP</state>
</address>
<address>
<street>Av Paulista</street>
<number>1001</number>
<neighborhood>Centro</neighborhood>
<postal_code>04001001</postal_code>
<completion></completion>
<city>S\xC3\xA3o Paulo</city>
<state>SP</state>
</address>
</addresses>
<contacts type="array">
<contact>
<value>11998761234</value>
<type_contact>M</type_contact>
</contact>
</contacts>
</customer>
</transaction>
</data_response>
<message_response>
<message>success</message>
</message_response>
</response>
If you configure log level to :debug, request and response HTTP headers will be logged too.
D, [2013-01-11T00:58:56.226742 #22692] DEBUG -- : Tray-Checkout Request:
POST http://api.sandbox.traycheckout.com.br//v2/transactions/get_by_token
accept: */*
user-agent: Ruby
token=522045453u5uu32e0u8014f060uuu5uu
D, [2013-01-11T00:58:56.495131 #22692] DEBUG -- : Tray-Checkout Response:
HTTP/1.1 200 OK
content-type: application/xml; charset=utf-8
transfer-encoding: chunked
connection: close
status: 200
x-powered-by: Phusion Passenger (mod_rails/mod_rack) 3.0.18
x-ua-compatible: IE=Edge,chrome=1
etag: "f5466d3294e177f5bb5331d326283294"
cache-control: max-age=0, private, must-revalidate
x-request-id: 9d8b635650e69237a6a875971ead3bbb
x-runtime: 0.238734
date: Fri, 11 Jan 2013 03:58:56 GMT
x-rack-cache: invalidate, pass
server: nginx/1.2.5 + Phusion Passenger 3.0.18 (mod_rails/mod_rack)
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data_response>
<transaction>
<order_number>1234567</order_number>
<free>Texto Interno</free>
<transaction_id type="integer">3856</transaction_id>
<status_name>Em Recupera\xC3\xA7\xC3\xA3o</status_name>
<status_id type="integer">88</status_id>
<token_transaction>522045453u5uu32e0u8014f060uuu5uu</token_transaction>
<payment>
<price_original type="decimal">2199.99</price_original>
<price_payment type="decimal">2199.99</price_payment>
<payment_response></payment_response>
<url_payment>http://gtw.sandbox.checkout.tray.com.br/api/print/0b525e9dbef558690477b815118aa033</url_payment>
<tid nil="true"/>
<split type="integer">1</split>
<payment_method_id type="integer">6</payment_method_id>
<payment_method_name>Boleto Bancario</payment_method_name>
<linha_digitavel>34191.76007 00536.260144 50565.600009 6 58630000219999</linha_digitavel>
</payment>
<customer>
<name>Nome do Cliente</name>
<cpf>98489882380</cpf>
<email>[email protected]</email>
<company_name></company_name>
<trade_name></trade_name>
<cnpj></cnpj>
<addresses type="array">
<address>
<street>Av Paulista</street>
<number>1001</number>
<neighborhood>Centro</neighborhood>
<postal_code>04001001</postal_code>
<completion></completion>
<city>S\xC3\xA3o Paulo</city>
<state>SP</state>
</address>
<address>
<street>Av Paulista</street>
<number>1001</number>
<neighborhood>Centro</neighborhood>
<postal_code>04001001</postal_code>
<completion></completion>
<city>S\xC3\xA3o Paulo</city>
<state>SP</state>
</address>
</addresses>
<contacts type="array">
<contact>
<value>11998761234</value>
<type_contact>M</type_contact>
</contact>
</contacts>
</customer>
</transaction>
</data_response>
<message_response>
<message>success</message>
</message_response>
</response>
To disable the log, change log level and configure other log output, use Tray::Checkout module:
Tray::Checkout.configure do |config|
config.log_enabled = false # It disables the log
config.log_level = :debug # It changes log level
config.logger = Rails.logger # It uses Rails logger
end
A configuration example
Tray::Checkout.configure do |config|
config.environment = :sandbox
config.token_account = "123u5uu9ef36f7u"
config.request_timeout = 3
config.log_level = :debug
config.logger = Rails.logger
end
Author
Contributing to tray-checkout
-
Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
-
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
-
Fork the project.
-
Start a feature/bugfix branch.
-
Commit and push until you are happy with your contribution.
-
Don’t forget to rebase with branch master in main project before submit the pull request.
-
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Copyright
(The MIT License)
Prodis a.k.a. Fernando Hamasaki
Copyright © 2012-2013 Prodis
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.