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] # => "pedro@bo.com.br"
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: "pedro@bo.com.br",
    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] # => "pedro@bo.com.br"
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]                 # test@test.com

response.service_contact[service_phone] # (55) 5555-5555
response.service_contact[email_service] # test@test.com

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>emaildo@cliente.com.br</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>emaildo@cliente.com.br</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¶ ↑

Fernando Hamasaki (prodis)

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

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.

tray-checkout

Development

Runtime