Manual de Integração

Transcrição

1 Manual de Integração API v Pagamento recorrente com cartão de crédito e boleto bancário

2 1 Introdução Conta de Recebimento é um gateway facilitador de pagamentos recorrentes para cartão de crédito e boletos bancários. Os sistemas de re-tentativa, antifraude, segurança e toda parametrização junto aos adquirentes foram idealizados para funcionar especificamente para empresas de serviço com faturamento recorrente, não sendo indicado para o varejo ou para o e-commerce em geral. Este manual o ajudará a integrar a Conta de Recebimento ao seu sistema usando API. 1.1 Suporte Dúvidas sobre a API devem ser enviadas para api@superlogica.com. 1.2 Arquitetura de Integração A integração é realizada através de serviços disponibilizados como Web Services. O modelo empregado é simples: há uma URL (endpoint) para cada operação, que recebe os POSTs via HTTPS. Os dados e mensagens são retornados em formato JSON codificados com UTF-8, data no formato MM/DD/AAAA e números com. como separadores decimais, sem separadores milhares e com o sinal - representando valores negativos. Um status code é retornado sempre que necessário. É importante uma correta validação deste status considerando que um valor maior ou igual a 300 sempre representa um erro. o status 200 significa processamento realizado com sucesso sem ressalvas.

3 2 Cartão de crédito Tokenizar: Transforma um número de cartão de crédito em um token que pode ser armazenado em qualquer banco de dados sem representar riscos de segurança ou de conformidade com PCI; Pagar: realiza um pagamento usando o token; Cancelar: cancela um pagamento; Extrato: lista as transações (realizadas e negadas) de um período. Útil para realizar a conciliação. 2.1 Credenciamento e ambiente de teste O credenciamento para utilização de cartão de crédito deve ser feito pelo site Você receberá um par credencial/chave secreta que o habilitará a usar nossa API em produção. Para ambiente de teste usar: credencial: 1264e7bea04bb1c24b07ace759f64a1bd65c8560 chave: ef947cf f744b82744dd3a8fc4852e529f Cartões de teste (Número, vencimento e CVV): / / / / / / / / / Tokenizando um cartão de crédito O primeiro passo para receber de seus cliente é converter o número do cartão de crédito para uma representação armazenável, o token. Este processo é chamado de tokenização do número do cartão. O token é válido apenas para sua empresa/cartão então é inútil se for roubado. Desta forma, é possível armazena-lo em qualquer banco de dados sem representar risco de segurança ou de

4 conformidade com PCI. O token deve ser armazenado para futuramente efetivar o pagamento Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório credencial nome_cartao Número de credenciamento fornecido pela Conta de Recebimento. Nome do portador do cartão de crédito. numero_cartao Número do cartão de credito. mes_vencimento ano_vencimento Mês de vencimento do cartão de crédito ente Ano de vencimento do cartão de crédito com 4 dígitos. cpf_cartao CPF do portador do cartão. * _cartao do cliente. * celular_cartao Celular do cliente. * codigo_cvv Código de segurança do cartão de credito. * * Apesar de algumas informações não serem obrigatórias elas impactam o sucesso da aprovação pois ajudam a correta analise do risco no processo de antifraude Retorno token_cartao representação armazenável do cartão com 40 caracteres.

5 msg status Mensagem de erro, quando houver. Status 200 sucesso, 403 credencial inválida. Status >= 300 erro. 2.3 Pagar utilizando um cartão O endpoint pagar é responsável por efetivamente realizar o pagamento. É possível informar os dados do cartão ou o seu token (vide item 3 e 5). É recomendado usar o endpoint pagar com token ou com o cartão apenas no primeiro pagamento. Nunca armazene o cartão não tokenizado! Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório credencial chave Número de credenciamento fornecido pela Conta de Recebimento no momento da afiliação. Chave privada fornecido pela Conta de Recebimento no momento da afiliação. nome_cartao Nome do portador do cartão de crédito. numero_cartao Número do cartão de credito. mes_vencimento ano_vencimento Mês de vencimento do cartão de crédito entre 1 e 12. Ano de vencimento do cartão de crédito com 4 dígitos.

6 cpf_cartao CPF do portador do cartão. * _cartao do cliente. * celular_cartao Celular do cliente. * codigo_cvv valor parcelas Código de segurança do cartão de credito. Valor a ser cobrado em reais. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto. usar separadores de milhares. Exemplo: Se maior que 1, faz um pagamento parcelado. No máximo em 12x, consultar taxas praticadas. * (padrão é 1) descricao_pagamento Descrição do pagamento de até 1024 caracteres. * * Apesar de algumas informações não serem obrigatórias elas impactam o sucesso da aprovação pois ajudam a correta analise do risco no processo de antifraude Retorno status Status 200 sucesso, 403 credencial inválida. Status >= 300 erro. tid tid_conciliacao token_cartao Identificação da transação. Deve ser armazenada para possível cancelamento. Identificação da transação no adquirente, armazenamento opcional, útil apenas para conciliação. Representação armazenável do cartão com 40 caracteres. Para futuros pagamentos, armazene este token em vez do número do

7 cartão. cartao_truncado bandeira autorizacao msg Número do cartão truncado. Bandeira do cartão. Número da autorização no adquirente. Este número é o número visível na fatura pelo cliente. Mensagem de erro, se houver Status Status Descrição 200 Sucesso. 403 Credencial inválida. 501 Cartão vencido. 502 Falha permanente no cartão. Normalmente por estar cancelado. 503 Falha temporária no cartão. Normalmente por saldo insuficiente. 504 Falha temporária com necessidade de retentar imediatamente. Normalmente houve uma falha temporária na comunicação com banco, adquirente ou antifraude. Recomendado não enviar mensagens para o cliente. 2.4 Pagar utilizando um token de cartão No item anterior o endpoint pagar foi usado com o número do cartão de crédito. Neste veremos como realizar o mesmo procedimento passando apenas o token criado no item 3 ou 4.

8 2.4.1 Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório credencial chave Número de credenciamento fornecido pela Conta de Recebimento no momento da afiliação. Chave privada fornecido pela Conta de Recebimento no momento da afiliação. token_cartao valor parcelas Token do cartão de crédito fornecido pela função tokenizar Valor a ser cobrado em reais. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto. usar separadores de milhares. Exemplo: Se maior que 1, faz um pagamento parcelado. No máximo em 12x, consultar taxas praticadas. (padrão é 1) descricao_pagamento Descrição do pagamento de até 1024 caracteres. * * Apesar de algumas informações não serem obrigatórias elas impactam o sucesso da aprovação pois ajudam a correta analise do risco no processo de antifraude.

9 2.4.2 Retorno status Status 200 sucesso, 403 credencial inválida. Status >= 300 erro; tid tid_conciliacao cartao_truncado bandeira autorizacao msg Identificação da transação. Deve ser armazenada para possível cancelamento. Identificação da transação no adquirente, armazenamento opcional, útil apenas para conciliação. Número do cartão truncado. Bandeira do cartão. Número da autorização no adquirente. Este número é o número visível na fatura pelo cliente. Mensagem de erro, se houver Status Status Descrição 200 Sucesso. 403 Credencial inválida. 501 Cartão vencido. 502 Falha permanente no cartão. Normalmente por estar cancelado. 503 Falha temporária no cartão. Normalmente por saldo insuficiente. 504 Falha temporária com necessidade de retentar imediatamente. Normalmente houve uma falha temporária na comunicação com banco, adquirente ou antifraude. Recomendado não enviar mensagens para o cliente.

10 2.5 Cancelar pagamento O cancelamento de um pagamento também pode ser feito por esta API. No entanto, existem regras dos adquirentes, bandeiras e banco que podem impactar no sucesso da operação. Quanto antes for feito, maior a chance de sucesso Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório tid credencial chave Identificação da transação, retornada pela função de pagar. Número de credenciamento fornecido pela Conta de Recebimento no momento da afiliação. Chave privada fornecido pela Conta de Recebimento no momento da afiliação. sim sim sim Retorno msg status Mensagem de erro, quando houver. Status 200 sucesso, 403 credencial inválida. Status >= 300 erro;

11 2.6 Extrato Lista todas as requisições realizadas em um determinado período. Mostra a atual previsão de crédito, se foram canceladas ou se houve charge-back. Formato ideal para realizar conciliações Requisição Método: GET Endpoint: Parâmetro Descrição Obrigatório credencial Número de credenciamento fornecido pela Conta de Recebimento no momento da afiliação. sim chave Chave privada fornecido pela Conta de Recebimento no momento da afiliação. sim data_inicio Primeiro dia do período do extrato no formato MM/DD/AAAA. não data_fim Ultimo dia do período do extrato no formato MM/DD/AAAA. não pagina Inteiro, começando por 1. Retorna 50 itens por página. (padrão é 1).

12 2.6.2 Retorno Array dados do extrato. status 403 credencial inválida. Status >= 300 erro;

13 3 Boletos bancários Credenciar: Cadastra o software como um cliente do conta de recebimento. Pagar: emite o boleto; Extrato: contém informações sobre as liquidações. Modo de uso: o Credencie uma empresa usando o endpoint credenciar e armazene a credencial e secret para realizar as outras operações; o Gere os boletos chamando o endpoint pagar. Envie o link do boleto ao cliente e armazene o campo nosso número para identificar quando aquele boleto foi pago; o Chame o endpoint extrato uma vez ao dia para saber quais boletos foram pagos no dia anterior. Use o campo nosso número para fazer este relacionamento. 3.1 Credenciamento e ambiente de teste O credenciamento deve ser feito via API e é imediatamente liberado. Porém, por questões de segurança, no primeiro repasse um contato telefônico do nosso time será necessário pra confirmar a conta bancária de repasse (aquela na qual os créditos serão feitos). O CNPJ deve ser o mesmo da razão social e da conta de repasse. É possível fazer o repasse para uma conta bancaria pertencente a uma pessoa física (CPF). No entanto, nesta chamada é necessário informar todos os dados da empresa e não da pessoa física. Para o repasse ser realizado em outra conta, informe a conta e CPF quando receber a ligação do nosso time e siga o procedimento solicitado Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório

14 nome_empresa conta_repasse agencia_repasse Razão social da empresa. Será usado no campo beneficiário do boleto. Número da conta bancaria que será feito o repasse, com dígito. Formato: , Número da agência que será feito o repasse, com ou sem dígito dependendo do banco. Formato: 99999, banco_repasse Número do banco que será feito o repasse, com 3 dígitos. cnpj CNPJ da empresa, somente números. O CNPJ deve ser o mesmo da razão social e da conta de repasse. Será exposto no boleto bancário. DDD DDD do telefone da empresa, somente números. telefone Telefone da empresa, sem DDD. Somente números. Para uso interno. da empresa. Para uso interno. agencia Opcionalmente é possível passar o código de identificação do parceiro, fornecido pela Conta de Recebimento Retorno credencial chave msg status Número da credencial que deve ser armazenada (e mantido em confidencialidade) para futuras requisições. Chave privada que deve ser armazenada (e mantido em confidencialidade) para futuras requisições. Usada, por enquanto, apenas no extrato. Mensagem de erro, quando houver. Status 200 sucesso, Status >= 300 erro;

15 3.3. Pagar Emite um boleto bancário Requisição Método: POST Endpoint: Parâmetro Descrição Obrigatório credencial Número fornecido no credenciamento. vencimento Vencimento da cobrança no formato MM/DD/AAAA. valor juros multa desconto Valor a ser cobrado em reais. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto. usar separadores de milhares. Exemplo: Taxa de juros ao dia por atraso. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto. Exemplo: 0.98 Taxa de multa por atraso. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto. Exemplo: 0.98 Valor do desconto por pontualidade, em Reais. Casas decimais devem ser separadas por ponto, máximo de 2 casas decimais, não enviar caracteres diferentes de número ou ponto.

16 Exemplo: 9.80 nome_cliente Nome completo do pagador. cpf_cliente CPF ou CNPJ do pagador., por enquanto. Porém por determinação da Febraban será obrigatório em breve. endereco_cliente Endereço do pagador. numero_cliente Número do endereço do pagador. complemento_cliente Complemento do endereço do pagador. bairro_cliente Bairro do endereço do pagador. cidade_cliente Cidade do endereço do pagador. estado_cliente Estado do endereço do pagador, com 2 caracteres. Exemplo: SP cep_cliente logo_url pedido_numero texto CEP do endereço do pagador. Apenas números. URL do logo da empresa. Será cacheado de forma agressiva, portanto, para mudar o logo altere a url. Numero do pedido da cobrança. Este número é importante se você precisar editar o boleto sem necessidade de duplica-lo. O sistema não vai gerar outro boleto se o número do pedido existir. Importante: para relacionar os boletos pagos não use o pedido e sim o campo nosso número, que será retornado nesta requisição. Texto que ficará no topo dos boletos. Será impresso com fonte fixa. Limite de 120 Obrigatório em caso de alterações de dados da cobrança.

17 credencial grupo linhas e 65 colunas. Credencial da empresa fornecida no credenciamento. Identificação do grupo. É uma string que identifica um grupo de boletos. Quando um valor é passado neste campo, é retornado um link adicional para impressão de todos os boletos do mesmo grupo de uma vez. Recomendado para imprimir carnês, por exemplo Retorno mensagem nossonumero linkboleto linkgrupo linhadigitavel Status mensagem de sucesso ou erro. Nosso número da cobrança. Deve ser armazenado para futura identificação da baixa(pagamento) do boleto em conjunto com a chamada ao endpoint extrato. Link do boleto bancário que deve ser repassado para o pagador. Link dos boletos bancários de um grupo que deve ser repassado para o pagador. É retornado quando, na requisição, foi enviado o grupo. A representação numérica do código de barras, conhecida como linha digitável. Normalmente não será necessário armazena-la. Por causa do risco de fraude (com vírus no computador do pagador) recomendamos não apresentar a linha digitavel diretamente para o pagador, pois se o cliente estiver infectado, a linha poderá ser alterada pelo vírus. Use o link do boleto, pois monitoramos as tentativas de alteração da linha, avisamos o pagador e as autoridades competentes. Status 200 sucesso, Status >= 300 erro.

18 3.4 Extrato Lista os pagamentos em um determinado dia em formato ideal para realizar as baixas Requisição Método: GET Endpoint: Parâmetro Descrição Obrigatório credencial Número fornecido no credenciamento. sim chave Chave privada fornecido no momento da afiliação. sim pago Valor fixo 1 sim data_inicio Primeiro dia do período do extrato no formato MM/DD/AAAA. Padrão hoje., padrão é hoje. data_fim Ultimo dia do período do extrato no formato MM/DD/AAAA., padrão é hoje. pagina Inteiro, começando por 1. Retorna 50 itens por página. Sempre obter a próxima página quando o sistema retornar 50 itens na página atual., padrão é 1.

19 3.4.2 Retorno Array dados do extrato. status 403 credencial inválida. Status >= 300 erro;