Pagamento

O TrayCheckout disponibiliza uma versão transparente para a integração de transações, permitindo que o usuário efetue o processamento dos pedidos sem necessitar o redirecionamento para outra aplicação e preenchimento de novos formulários.

Fluxo Api de pagamento

Através do CPF do cliente é feita a consulta pela existência do seu cadastro e então as transações são atreladas ao mesmo. Caso não exista uma conta, o sistema irá criar uma nova conta com os dados que forem submetidos na integração. Para esta integração, deverá ser feito uso da API a seguir:

Para a integração com a API de Transação, é necessário incluir um script após o processamento da transação, no início da página de finalização da compra. Segue abaixo código do script:


    <script src="https://static.traycheckout.com.br/js/finger_print.js" type="text/javascript"></script>
    

Além de incluir o script, é necessário realizar a chamada do plugin, no final da mesma página, conforme código javascript abaixo:


    jQuery(document).FingerPrint({token_account: 'Token de Integração do Vendedor',
                                  order_number: 'Número do pedido',
                                  production: 'true'});
    
Endereço para Integração
Ambiente de Testes https://api.sandbox.traycheckout.com.br/v2/transactions/pay_complete
Ambiente de Produção https://api.traycheckout.com.br/v2/transactions/pay_complete
Protocolo Rest/HTTP

Para a integração via POST, segue abaixo os dados necessários para envio:

Dados de Entrada Obrig. Formato / Tam. Max Descrição
token_account Sim Texto /20 Token de identificação do vendedor
customer[name] Sim Texto /100 Nome do Comprador
customer[cpf] Sim Texto /14 CPF do Comprador
customer[email] Sim Texto /100 E-mail do Comprador
customer[trade_name] Não Texto /100 Nome Fantasia do Comprador
customer[company_name] Não Texto /100 Razão Social do Comprador
customer[cnpj] Não Texto /18 CNPJ do Comprador
customer[inscricao_municipal] Não Texto /20 Inscrição Municipal do Comprador
customer[contacts][][type_contact] Sim Texto /1 Tipo do Contato 1 (Tabela 1)
customer[contacts][][number_contact] Sim Texto /11 Número do telefone do Comprador
customer[addresses][][type_address] Sim Texto /1 Tipo do Endereço 1 (Tabela 2)
customer[addresses][][postal_code] Sim Texto /8 CEP do endereço do Comprador
customer[addresses][][street] Sim Texto /120 Nome da rua do Comprador
customer[addresses][][number] Sim Texto /10 Número do endereço do Comprador
customer[addresses][][neighborhood] Sim Texto /100 Bairro do endereço do Comprador
customer[addresses][][completion] Não Texto /100 Complemento do endereço do Comprador
customer[addresses][][city] Sim Texto /120 Cidade do endereço do Comprador
customer[addresses][][state] Sim Texto /2 Estado do endereço do Comprador
customer[birth_date] Não Data / 10 Data de aniversário do Comprador
transaction[available_payment_methods] Não Texto /20 Meios de Pagamento disponíveis 2 (Tabela 3)
transaction[order_number] Não Texto /2 Número do pedido
transaction[customer_ip] Sim Texto /15 IP do Comprador
transaction[shipping_type] Não Texto /100 Tipo do envio
transaction[shipping_price] Não Decimal / 11 Preço de Envio. Formato: 0.00
transaction[price_discount] Não Decimal / 11 Valor do desconto. Formato: 0.00
transaction[price_additional] Não Decimal / 11 Valor adicional. Formato: 0.00
transaction[url_notification] Não Texto /255 URL de Notificação Automática de Status
transaction[free] Não Texto /200 Campo Livre
transaction_product[][description] Sim Texto /100 Nome do produto 1
transaction_product[][quantity] Sim Número / 3 Quantidade do item do produto
transaction_product[][price_unit] Sim Decimal / 11 Valor unitário. Formato: 0.00
transaction_product[][code] Não Texto /10 Código do produto
transaction_product[][sku_code] Não Texto /50 Código SKU do produto
transaction_product[][extra] Não Texto /100 Campo Livre do produto
payment[payment_method_id] Sim Texto /2 Forma de Pagamento
payment[split] Sim Texto /2 Número de parcelas (01 a 12)
payment[card_name] Não Texto /100 Nome impresso no cartão
payment[card_number] Não Número /20 Número do cartão
payment[card_expdate_month] Não Número /2 Mês de vencimento do cartão
payment[card_expdate_year] Não Número / 4 Ano de vencimento do cartão
payment[card_cvv] Não Número / 3 Código de segurança do cartão
payment[billet_date_expiration] Não Data / 10 Data de Vendimento do Boleto
affiliates[][email] Não Texto / 100 Email do afiliado da transação
affiliates[][percentage] Não Número / 3 Percentual de repasse ao afiliado 3
affiliates[][commission_amount] Não Decimal / 11 Valor de repasse ao afiliado 3
sub_store Não Texto /20 Sub-Loja

1 Note que nas informações acima que alguns dados possuem uma característica diferente, tendo um elemento [] dentro de sua formatação. Isso ocorre justamente para permitir que sejam enviados diversos itens na mesma requisição.

2 O parâmetro transaction[available_payment_methods] permite que sejam enviados os códigos de meios de pagamento que poderão ser disponibilizados no processo de recobrança de transações. Os códigos deverão ser enviados separados por vírgula (,). Esse campo é útil quando a loja oferece uma condição especial de pagamento, por exemplo Desconto de 10% no Boleto Bancário. Assim deve-se enviar apenas o código do boleto bancário para que seja disponibilizada somente esta forma de pagamento no processo de recobrança.

3 Pode ser enviado o parâmetro affiliates[][commission_amount] ou affiliates[][percentage] para realizar o repasse ao afiliado da transação, onde deve ser informado somente um desses campos.

Veja abaixo uma chamada de API de exemplo com 2 produtos e 2 telefones:

    
    <?php
        /* Token da Conta do Lojista */
        $params['token_account'] = '### Token do Cliente ###';

        /* Dados do Comprador */
        $params['customer[name]'] = 'Nome do Cliente';
        $params['customer[cpf]'] = '98489882380';
        $params['customer[email]'] = 'emaildo@cliente.com.br';
        $params['customer[birth_date]'] = '21/12/1985';
        $params['customer[contacts][][type_contact]'] = 'H';
        $params['customer[contacts][][number_contact]'] = '1133120001';
        $params['customer[contacts][][type_contact]'] = 'M';
        $params['customer[contacts][][number_contact]'] = '11999120002';
        $params['customer[addresses][][type_address]'] = 'B';
        $params['customer[addresses][][postal_code]'] = '04001001';
        $params['customer[addresses][][street]'] = 'Av Paulista';
        $params['customer[addresses][][number]'] = '112';
        $params['customer[addresses][][completion]'] = 'A';
        $params['customer[addresses][][neighborhood]'] = 'Centro';
        $params['customer[addresses][][city]'] = 'São Paulo';
        $params['customer[addresses][][state]'] = 'SP';

        /* Dados da Transação */
        $params['transaction[available_payment_methods]'] = '2,3,4,5,6,7,14,15,16,18,19,21,22,23';
        $params['transaction[order_number]'] = '0001';
        $params['transaction[customer_ip]'] = '200.200.200.200';
        $params['transaction[shipping_type]'] = 'Sedex';
        $params['transaction[shipping_price]'] = '19.80';
        $params['transaction[price_discount]'] = '7.80';
        $params['transaction[price_additional]'] = '6.00';
        $params['transaction[url_notification]'] = 'http://www.loja.com.br/notificacao/';
        $params['transaction[free]'] = 'Campo de livre digitação';
        $params['transaction[sub_store]'] = 'LOJA_1';

        /* Dados do Produto 1 - Notebook Preto */
        $params['transaction_product[][description]'] = 'Notebook Preto';
        $params['transaction_product[][quantity]'] = '1';
        $params['transaction_product[][price_unit]'] = '321.99';
        $params['transaction_product[][code]'] = '1';
        $params['transaction_product[][sku_code]'] = '0001';
        $params['transaction_product[][extra]'] = 'Dados extra do Notebook Preto';

        /* Dados do Produto 2 - Notebook Branco */
        $params['transaction_product[][description]'] = 'Notebook Branco';
        $params['transaction_product[][quantity]'] = '1';
        $params['transaction_product[][price_unit]'] = '321.98';
        $params['transaction_product[][code]'] = '2';
        $params['transaction_product[][sku_code]'] = '0002';
        $params['transaction_product[][extra]'] = 'Dados extra do Notebook Branco';

        /* Dados para Pagamento */
        $params['payment[payment_method_id]'] = '3';
        $params['payment[split]'] = '12';
        $params['payment[card_name]'] = 'Nome Impresso no Cartão';
        $params['payment[card_number]'] = '1234123412341234';
        $params['payment[card_expdate_month]'] = '01';
        $params['payment[card_expdate_year]'] = '2016';
        $params['payment[card_cvv]'] = '123';

        $urlPost = "https://api.sandbox.traycheckout.com.br/v2/transactions/pay_complete";

        ob_start();

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $urlPost);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
        curl_exec($ch);

        /* XML de retorno */ 
        $resposta = simplexml_load_string(ob_get_contents());

        ob_end_clean();
        curl_close($ch);

        if($resposta->message_response->message == "success"){
            //Tratamento dos dados de resposta da consulta.
        }else{
            //Tratamento das mensagens de erro
        }
    ?>
    

A API de Processamento de Transações retorna a resposta em XML.

Abaixo um detalhamento de cada nó do XML de resposta:

XML de Resposta
<response> Nó principal da resposta
<response>
    <message_response>
Nó que contém o resultado da resposta
<response>
    <message_response>
        <message>
Resposta sobre a solicitação
Em caso de sucesso: success
Em caso de erro: error
<response>
    <data_response>
Nó que contém os dados da resposta
<response>
    <data_response>
        <transaction>
Nó que contém as informações sobre a transação
<response>
    <data_response>
        <transaction>
            <order_number>
Número do pedido enviado pela loja na solicitação
<response>
    <data_response>
        <transaction>
            <free>
Texto livre enviado pela loja na solicitação
<response>
    <data_response>
        <transaction>
            <transaction_id type="integer">
Id da transação
<response>
    <data_response>
        <transaction>
            <status_name>
Descrição do status da transação (Tabela 4)
<response>
    <data_response>
        <transaction>
            <status_id type="integer">
Id do status da transação (Tabela 4)
<response>
    <data_response>
        <transaction>
            <token_ transaction>
Token da transação. Deve ser armazenado para ser utilizado nas consultas posteriores.
<response>
    <data_response>
        <transaction>
            <payment>
Nó com informações sobre o pagamento
<response>
    <data_response>
        <transaction>
            <payment>
                <price_payment type="decimal">
Preço pago pelo cliente
<response>
    <data_response>
        <transaction>
            <payment>
                <payment_response>
Resposta de pagamento da operadora para ser exibida na página de recibo de compra
<response>
    <data_response>
        <transaction>
            <payment>
                <url_payment>
Url para exibir o boleto ou ambiente externo do banco. Apenas para formas de pagamento que não são fechadas online, como por exemplo o Boleto Bancário e Itau Shopline
<response>
    <data_response>
        <transaction>
            <payment>
                <tid>
Número único que identifica a transação na operadora
<response>
    <data_response>
        <transaction>
            <payment>
                <split type="integer">
Número de parcelas da transação
<response>
    <data_response>
        <transaction>
            <payment>
                <payment_method_id type="integer">
Id da forma de pagamento escolhida
<response>
    <data_response>
        <transaction>
            <payment>
                <payment_method_name>
Nome da forma de pagamento escolhida
<response>
    <data_response>
        <transaction>
            <payment>
                <linha_digitavel nil="true"/>
Linha digitável para pagamento via Internet Banking. Apenas no caso da escolha por Boleto Bancário

Exemplo de resposta com sucesso baseando no envio do exemplo acima:

    <response>
<message_response>
<message>success</message>
</message_response>
<data_response>
<transaction>
<order_number>123456</order_number>
<free>Texto Interno</free>
<transaction_id type="integer">999999</transaction_id>
<status_name>Aprovada</status_name>
<status_id type="integer">6</status_id>
<token_transaciton>3a2a84aa09d4ff8320f940070bcdb3fa</transaction_token>
<payment>
<price_payment type="decimal">4199.98</price_payment>
<payment_response>Autorização aprovada</payment_response>
<url_payment></url_payment>
<tid>10347871500026BF1001</tid>
<split type="integer">12</split>
<payment_method_id type="integer">3</payment_method_id>
<payment_method_name>Visa</payment_method_name>
<linha_digitavel nil="true"/>
</payment>
</transaction>
</data_response>
</response>

Mensagens de Erro

No caso de erro, a API retorna uma mensagem de erro. Assim é possível identificar o erro ocorrido e realizar o tratamento através do código e/ou mensagem retornada.

Abaixo segue os detalhes de cada nó do XML de resposta:

XML de Resposta
<response> Nó principal da resposta
<response>
    <message_response>
Nó que contém o resultado da resposta
<response>
    <message_response>
        <message>
Resposta sobre a solicitação
Em caso de sucesso: success
Em caso de erro: error
<response>
    <error_response>
Nó que contém os erros encontrados
<response>
    <error_response>
        <general_errors>
Nó que contém os erros encontrados
<response>
    <error_response>
        <general_errors>
            <general_error>
Nó que contém o detalhamento de um erro
<response>
    <error_response>
        <general_errors>
            <general_error>
                <code>
Código do erro
<response>
    <error_response>
        <general_errors>
            <general_error>
                <message>
Mensagem do erro

Exemplo de um retorno com erro:

        <response>
<message_response>
<message>success</message>
</message_response>
<error_response>
<general_errors type="array">
<general_error>
<code>003039</code>
<message>Vendedor inválido ou não encontrado</message>
</general_error>
</general_errors>
</error_response>
</response>

As mensagens de erros retornados pela API estão listadas na tabela abaixo:

009007Valor da transação menor que o permitido009008Vendedor não aceita essa forma de pagamento
Código Mensagem
001001 Token inválido ou não encontrado
003001 O vendedor não pode ser igual ao comprador
003003 Forma de Pagamento Inválido
003004 Número da Parcela Inválido
003010 Forma de pagamento inválida
003011 Numero do cartão inválido
003012 Nome do cartão em branco
003014 Código de segurança inválido
003015 Mês de vencimento do cartão inválido
003016 Número de parcelas inválido
003020 Ano de vencimento do cartão inválido
003021 O vendedor não pode ser igual ao comprador
003029 Código de segurança inválido
003039 Vendedor inválido ou não encontrado
003065 Valor menor que mínimo permitido
003081 Não foi possível finalizar sua compra. Entre em contato através do telefone (11)3136-0070 ou e-mail atendimento@traycheckout.com.br, informando o código '003081'
009006 Número da parcela maior que o permitido
037001 Percentual não pode ficar em branco
037003 Afiliado não encontrado
037010 E-mail do afiliado informado deve ser diferente do vendedor
037012 Porcentagem ou valor da comissão deve ser maior que zero
058001 Revendedor inválido.

Tabelas Auxiliares

Na integração existem alguns campos com informações pré-definidas, onde deverão ser enviadas conforme o padrão existente, se for necessário enviar o campo na requisição, ou poderá tratar a informação conforme retorno recebido.

Abaixo segue tabelas com essas informações pré-definidas:

Tabela 1 – Contato
Residencial H
Celular M
Comercial W
Tabela 2 – Tipos de Endereço
Cobrança B
Entrega D
Tabela 3 – Formas de Pagamento
Cartões de Crédito
Diners Club 2
Visa 3
Mastercard 4
American Express 5
Discover 15
Elo 16
Aura 18
JCB 19
Hipercard 20
Hiper (Itaú) 25
Transferências Online
Itaú Shopline 7
Peela 14
Transf. Online HSBC 21
Transf. Online Bradesco 22
Transf. Online Banco do Brasil 23
Boleto Bancário
Boleto Bancário 6
Tabela 4 – Status da Transação
Aguardando Pagamento 4
Em Processamento 5
Aprovada 6
Cancelada 7
Em Contestação 24
Em Monitoramento 87
Em Recuperação 88
Reprovada 89