tray-checkout
Tray Checkout API
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"
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
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.checkout.tray.com.br/api/v1/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"?>
<transaction>
<data_response>
<transaction>
<order_number>F4326</order_number>
<free nil="true"/>
<transaction_id type="integer">632</transaction_id>
<status_name>Aguardando Pagamento</status_name>
<status_id type="integer">4</status_id>
<date_transaction>2012-12-27T10:26:21</date_transaction>
<split type="integer">1</split>
<price_payment type="decimal">37.86</price_payment>
<date_payment></date_payment>
<transaction_token>522045453u5uu32e0u8014f060uuu5uu</transaction_token>
<sub_store nil="true"/>
<available_payment_methods nil="true"/>
<url_notification>http://prodis.blog.br/tray_notification</url_notification>
<url_css nil="true"/>
<url_shipping nil="true"/>
<url_stock nil="true"/>
<url_success nil="true"/>
<url_process nil="true"/>
<url_cancel nil="true"/>
<schedule_credit></schedule_credit>
<price_seller type="decimal">35.05</price_seller>
<price_original type="decimal">37.86</price_original>
<price_additional type="decimal">0.0</price_additional>
<price_discount type="decimal">0.0</price_discount>
<shipping_price type="decimal">5.88</shipping_price>
<shipping_type>PAC</shipping_type>
<payment>
<price_payment type="decimal">37.86</price_payment>
<payment_response></payment_response>
<url_payment>http://checkout.sandbox.tray.com.br/payment/billet/u9uuu8731319u59u3073u9011uu6u6uu</url_payment>
<date_approval></date_approval>
<tid></tid>
<split type="integer">1</split>
<date_payment></date_payment>
<payment_method_id type="integer">6</payment_method_id>
<payment_method_name>Boleto Bancario</payment_method_name>
<card_id nil="true"/>
<number_proccess type="integer">869</number_proccess>
<linha_digitavel>34191.76007 00086.950144 50565.600009 1 55650000003786</linha_digitavel>
</payment>
<products type="array">
<product>
<code>LOGO-8278</code>
<description>Logo Prodis</description>
<extra nil="true"/>
<price_unit type="decimal">10.99</price_unit>
<quantity type="decimal">2.0</quantity>
<sku_code nil="true"/>
<url_img nil="true"/>
</product>
<product>
<code>877</code>
<description>Outro produto</description>
<extra nil="true"/>
<price_unit type="decimal">10.0</price_unit>
<quantity type="decimal">1.0</quantity>
<sku_code nil="true"/>
<url_img nil="true"/>
</product>
</products>
<transaction_affiliates type="array"/>
<customer>
<name>Pedro Bonamides</name>
<cpf>18565842673</cpf>
<email>[email protected]</email>
<addresses type="array">
<address>
<street>Avenida Pedro Alvares Cabral</street>
<number>123</number>
<neighborhood>Parque Ibirapuera</neighborhood>
<postal_code>04094050</postal_code>
<completion></completion>
<city>São Paulo</city>
<state>SP</state>
</address>
</addresses>
<contacts type="array">
<contact>
<contact_id type="integer">345</contact_id>
<value>1137654321</value>
<type_contact>H</type_contact>
<primary type="boolean">true</primary>
</contact>
</contacts>
</customer>
</transaction>
</data_response>
<message_response>
<message>success</message>
</message_response>
</transaction>
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.checkout.tray.com.br/api/v1/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"?>
<transaction>
<data_response>
<transaction>
<order_number>F4326</order_number>
<free nil="true"/>
<transaction_id type="integer">632</transaction_id>
<status_name>Aguardando Pagamento</status_name>
<status_id type="integer">4</status_id>
<date_transaction>2012-12-27T10:26:21</date_transaction>
<split type="integer">1</split>
<price_payment type="decimal">37.86</price_payment>
<date_payment></date_payment>
<transaction_token>522045453u5uu32e0u8014f060uuu5uu</transaction_token>
<sub_store nil="true"/>
<available_payment_methods nil="true"/>
<url_notification>http://prodis.blog.br/tray_notification</url_notification>
<url_css nil="true"/>
<url_shipping nil="true"/>
<url_stock nil="true"/>
<url_success nil="true"/>
<url_process nil="true"/>
<url_cancel nil="true"/>
<schedule_credit></schedule_credit>
<price_seller type="decimal">35.05</price_seller>
<price_original type="decimal">37.86</price_original>
<price_additional type="decimal">0.0</price_additional>
<price_discount type="decimal">0.0</price_discount>
<shipping_price type="decimal">5.88</shipping_price>
<shipping_type>PAC</shipping_type>
<payment>
<price_payment type="decimal">37.86</price_payment>
<payment_response></payment_response>
<url_payment>http://checkout.sandbox.tray.com.br/payment/billet/u9uuu8731319u59u3073u9011uu6u6uu</url_payment>
<date_approval></date_approval>
<tid></tid>
<split type="integer">1</split>
<date_payment></date_payment>
<payment_method_id type="integer">6</payment_method_id>
<payment_method_name>Boleto Bancario</payment_method_name>
<card_id nil="true"/>
<number_proccess type="integer">869</number_proccess>
<linha_digitavel>34191.76007 00086.950144 50565.600009 1 55650000003786</linha_digitavel>
</payment>
<products type="array">
<product>
<code>LOGO-8278</code>
<description>Logo Prodis</description>
<extra nil="true"/>
<price_unit type="decimal">10.99</price_unit>
<quantity type="decimal">2.0</quantity>
<sku_code nil="true"/>
<url_img nil="true"/>
</product>
<product>
<code>877</code>
<description>Outro produto</description>
<extra nil="true"/>
<price_unit type="decimal">10.0</price_unit>
<quantity type="decimal">1.0</quantity>
<sku_code nil="true"/>
<url_img nil="true"/>
</product>
</products>
<transaction_affiliates type="array"/>
<customer>
<name>Pedro Bonamides</name>
<cpf>18565842673</cpf>
<email>[email protected]</email>
<addresses type="array">
<address>
<street>Avenida Pedro Alvares Cabral</street>
<number>123</number>
<neighborhood>Parque Ibirapuera</neighborhood>
<postal_code>04094050</postal_code>
<completion></completion>
<city>São Paulo</city>
<state>SP</state>
</address>
</addresses>
<contacts type="array">
<contact>
<contact_id type="integer">345</contact_id>
<value>1137654321</value>
<type_contact>H</type_contact>
<primary type="boolean">true</primary>
</contact>
</contacts>
</customer>
</transaction>
</data_response>
<message_response>
<message>success</message>
</message_response>
</transaction>
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.