Cobrança Recorrente

O TrayCheckout disponibiliza uma versão transparente para a integração de assinaturas, permitindo sejam enviadas cobranças recorrentes através de outra aplicação.

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/v1/billing_contracts/charge_recurrent
Ambiente de Produção https://api.checkout.tray.com.br/v1/billing_contracts/charge_recurrent
Protocolo Rest/HTTP

Para a integração com esta 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 da conta
customer_name Não Texto / 150 Nome do cliente que receberá a cobrança
customer_email Sim Texto / 150 E-mail do cliente que receberá a cobrança
description Sim Texto / 150 Descrição da cobrança
day_expiration Sim 1 Número / 11 Dia do vencimento da cobrança
date_expiration Sim 1 Data Data para vencimento da cobrança dd/mm/aaaa
periodicity Sim Número / 11 Periodicidade da cobrança
Ex: 1 = cobrança mensal
6 = cobrança semestral
quantity Sim Número / 11 Quantidade de cobranças geradas. O valor 0 indica tempo indeterminado
price Sim Decimal / 10,2 Valor da cobrança. Ex: 500.00
source_register Não Texto / 100 Parâmetro livre utilizado para relatórios

1 Caso o campo day_expiration seja preenchido, o campo date_expiration não é necessário e vice-versa.

Veja abaixo um exemplo do envio de uma cobrança mensal no valor de R$ 500,00, durante um período de 12 meses e com o vencimento para o dia 20 de cada mês:


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

        /* Dados do Assinante */
        $params['customer_name'] = 'Nome do Cliente';
        $params['customer_email'] = 'emaildo@cliente.com.br';

        /* Dados da Assinatura */
        $params['description'] = 'Descrição da Cobrança Recorrente';
        $params['day_expiration'] = '20';
        $params['periodicity'] = '1';
        $params['quantity'] = '12';
        $params['price'] = '500.00';
        $params['source_register'] = 'Criado por API';

        $urlPost = "http://api.sandbox.checkout.tray.com.br/v1/billing_contracts/charge_recurrent";

        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
        }
    ?>

Após o processamento, é retornado um XML de resposta com os detalhes da cobrança criada com sucesso. Segue abaixo 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>
        <billing_contract>
Nó que contém os dados da cobrança
<response>
    <data_response>
        <billing_contract>
            <id>
ID da cobrança
<response>
    <data_response>
        <billing_contract>
            <name>
Dado gerado automaticamente pelo sistema
<response>
    <data_response>
        <billing_contract>
            <costumer_name>
Nome do cliente
<response>
    <data_response>
        <billing_contract>
            <costumer_email>
Email do cliente
<response>
    <data_response>
        <billing_contract>
            <seller_token>
Token do vendedor
<response>
    <data_response>
        <billing_contract>
            <day_expiration>
Data de vencimento da cobrança
<response>
    <data_response>
        <billing_contract>
            <status_id>
ID de status da cobrança (Tabela 1)
<response>
    <data_response>
        <billing_contract>
            <status_name>
Status da cobrança (Tabela 1)
<response>
    <data_response>
        <billing_contract>
            <source_register>
Informação enviada no <source_register> de criação
<response>
    <data_response>
        <billing_contract>
            <billing_contract_token>
Token da cobrança gerada
<response>
    <data_response>
        <billing_contract>
            <url_confirmation>
URL de confirmação e pagamento da cobrançav
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
Nó que contém os planos inclusos
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
Nó que contém os dados do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <id>
ID do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <code>
Dados gerados automaticamente pelo sistema
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <description>
Descrição do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <periodicity>
Periodicidade do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <quantity>
Quantidade de vezes que será feita a cobrança
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <price_setup>
Valor de contratação do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <price_discount>
Valor de desconto do plano
<response>
    <data_response>
        <billing_contract>
            <billing_contract_plans>
                <billing_contract_plan>
                    <price_due>
Valor do plano

Exemplo do XML de resposta após a criação da cobrança recorrente com sucesso:

    
    <response> 
<message_response>
<message>success</message>
</message_response>
<data_response>
<billing_contract>
<id type="integer">4362</id>
<name>1368791435</name>
<customer_name>Nome do Cliente</customer_name>
<customer_email>emaildo@cliente.com.br</customer_email>
<seller_token>68b050ff82fe29c</seller_token>
<day_expiration type="integer">20</day_expiration>
<status_id type="integer">58</status_id>
<status_name>Pendente</status_name>
<source_register>Criado por API</source_register>
<billing_contract_token>9d30b3c246a68a487a35833e181095c6</billing_contract_token>
<url_confirmation>
http://checkout.tray.com.br/payment/billing/64e9ba070882d50cdde3c0f42d459ea2
</url_confirmation>
<billing_contract_plans type="array">
<billing_contract_plan>
<id type="integer">13770</id>
<code>1368791435</code>
<description>Descrição da Cobrança Recorrente</description>
<periodicity type="integer">1</periodicity>
<quantity type="integer">12</quantity>
<price_setup type="decimal">0.0</price_setup>
<price_discount type="decimal">0.0</price_discount>
<price_due type="decimal">500.0</price_due>
</billing_contract_plan>
</billing_contract_plans>
</billing_contract>
</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>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ódigo Mensagem
001001 Token inválido ou não encontrado
023029 Dia de vencimento inválido
023032 E-mail do cliente Inválido
023033 Descrição Inválida
023034 Valor Inválido
024007 Dia do primeiro vencimento inválido
024008 Data do Primeiro Vencimento Inválida

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 tabela com essas informações pré-definidas:

Tabela 1 – Status da Assinatura
Pendente 58
Ativo 56
Inativo 57
Inadimplente 59
Confirmado 65
Encerrado 109