Consulta de Transação

O TrayCheckout disponibiliza um recurso para a consulta da transação. Com este recurso, você poderá realizar a consulta para obter as informações detalhadas da transação, e assim comparar as informações e atualizar o status do pedido com segurança.

Para esta integração, deverá ser feito uso da API a seguir:

Endereço para Integração
Ambiente de Testes https://api.sandbox.traycheckout.com.br/v2/transactions/get_by_token
Ambiente de Produção https://api.traycheckout.com.br/v2/transactions/get_by_token
Protocolo Rest/HTTP

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

Dados de Entrada Obrig. Formato / Tam. Max Descrição
token_account Sim Texto / 15 Token de identificação do vendedor
token_transaction Sim Texto / 32 Token de identificação da transação

Veja abaixo uma chamada de exemplo da API de Consulta de Transação


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

        /* Token da Transação */
        $params['token_transaction'] = '### Token da Transação ###';

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

        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
        }
    ?>
        ...
    
    string URLAuth = "https://api.sandbox.traycheckout.com.br/v2/transactions/get_by_token";
    
    NameValueCollection queryParameters = new NameValueCollection();
    
    /* Token da Conta do Lojista */
    queryParameters.Add("token_account", "### Token do Cliente ###");

    /* Token da Transação */
    queryParameters.Add("token_transaction", "### Token da Transação ###");
    
    List<string> items = new List<string>();
    
    foreach (String name in queryParameters)
        items.Add(String.Concat(name, "=", System.Web.HttpUtility.UrlEncode(queryParameters[name])));
    
    string postString = String.Join("&", items.ToArray());
    
    const string contentType = "application/x-www-form-urlencoded";
    System.Net.ServicePointManager.Expect100Continue = false;
    
    CookieContainer cookies = new CookieContainer();
    HttpWebRequest webRequest = WebRequest.Create(URLAuth) as HttpWebRequest;
    webRequest.Method = "POST";
    webRequest.ContentType = contentType;   
    webRequest.CookieContainer = cookies;
    webRequest.ContentLength = postString.Length; 
    webRequest.Accept = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
    
    StreamWriter requestWriter = new StreamWriter(webRequest.GetRequestStream());
    requestWriter.Write(postString);
    requestWriter.Close();
    
    StreamReader responseReader = new StreamReader(webRequest.GetResponse().GetResponseStream());
    string responseData = responseReader.ReadToEnd();
    
    responseReader.Close();
    webRequest.GetResponse().Close();
    
    ... 
        ...
    String url = "https://api.sandbox.traycheckout.com.br/v2/transactions/get_by_token";
     
    HttpClient client = new HttpClient();
    PostMethod method = new PostMethod(url);
    
    method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, 
        new DefaultHttpMethodRetryHandler(3, false));
    byte[] responseBody = null;

    try {
        NameValuePair[] data = {
            /* Token da Conta do Lojista */
            new NameValuePair("token_account", "### Token do Cliente ###"),

            /* Token da Transação */
            new NameValuePair("token_transaction", "### Token da Transação ###")
        };

        method.setRequestBody(data);

        // Execute the method.
        int statusCode = client.executeMethod(method);

        if (statusCode != HttpStatus.SC_OK) {
            System.err.println("Method failed: " + method.getStatusLine());
        }
        
        responseBody = method.getResponseBody();
        
    } catch (HttpException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    } finally {
        method.releaseConnection();
    }

    String xmlResposta = new String(responseBody);

    ... 
    

A API de Consutar 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 3)
<response>
    <data_response>
        <transaction>
            <status_id type="integer">
Id do status da transação (Tabela 3)
<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 (Tabela 2)
<response>
    <data_response>
        <transaction>
            <payment>
                <payment_method_name>
Nome da forma de pagamento escolhida (Tabela 2)
<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
<response>
    <data_response>
        <transaction>
            <customer>
Nó com informações do comprador
<response>
    <data_response>
        <transaction>
            <customer>
                <name>
Nome do comprador
<response>
    <data_response>
        <transaction>
            <customer>
                <cpf>
Cpf do comprador
<response>
    <data_response>
        <transaction>
            <customer>
                <email>
Email do comprador
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
Nó com array de endereços utilizados
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
Nó de um endereço
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <street>
Logradouro do Comprador
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <number>
Número
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <neighborhood>
Bairro
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <postal_code>
CEP
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <completion>
Complemento
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <city>
Cidade
<response>
    <data_response>
        <transaction>
            <customer>
                <addresses type="array">
                    <address>
                        <state>
Estado
<response>
    <data_response>
        <transaction>
            <customer>
                <contacts type="array">
Array com telefones utilizados
<response>
    <data_response>
        <transaction>
            <customer>
                <contacts type="array">
                    <contact>
Nó com telephone
<response>
    <data_response>
        <transaction>
            <customer>
                <contacts type="array">
                    <contact>
                        <value>
Número do Telefone
<response>
    <data_response>
        <transaction>
            <customer>
                <contacts type="array">
                    <contact>
                        <type_contact>
Tipo do contato (Tabela 1)

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


    <response>
<message_response>
<message>success</message>
</message_response>
<data_response>
<transaction>
<order_number>89568398</order_number>
<free> </free>
<transaction_id type="integer">64997</transaction_id>
<status_name>Reprovada</status_name>
<status_id type="integer">89</status_id>
<token_transaction>d2c4c6fa6272f4c5f9156185602e9b08</token_transaction>
<payment>
<price_payment type="decimal">24009.0</price_payment>
<payment_response>Autorização Negada</payment_response>
<url_payment/>
<tid>1233</tid>
<split type="integer">1</split>
<payment_method_id type="integer">4</payment_method_id>
<payment_method_name>Mastercard</payment_method_name>
<linha_digitavel nil="true"/>
</payment>
<customer>
<name>Nome do Cliente</name>
<cpf>12312312332</cpf>
<email>nomedo@cliente.com.br</email>
<addresses type="array">
<address>
<street>Av Paulista</street>
<number>123</number>
<neighborhood>Jardim Paulistano</neighborhood>
<postal_code>04001000</postal_code>
<completion>Sala 1020 </completion>
<city>São Paulo</city>
<state>SP</state>
</address>
</addresses>
<contacts type="array">
<contact>
<value>1434065858</value>
<type_contact>H</type_contact>
</contact>
</contacts>
</customer>
</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>error</message>
</message_response>
<error_response>
<general_errors type="array">
<general_error>
<code>001001</code>
<message>Token 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:

CódigoMensagem
001001 Token inválido ou não encontrado
003041 O Token da Transação não pode ficar em branco
003042 Transação não encontrada

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 - 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
Transferências Online
Itaú Shopline 7
Peela 14
Transf. Online Bradesco 22
Transf. Online Banco do Brasil 23
Boleto Bancário
Boleto Bancário 6
Tabela 3 - 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