API PAGAMENTOS. Todas requisições devem ser feitas para o endpoint

Transcrição

1 INTRODUÇÃO Para efetuar pagamentos, você deverá enviar os pedidos para a API REST da BelaViagem. Essa API ainda está em desenvolvimento, mas estamos trabalhando duro para melhorá-la! Se você tiver qualquer dúvida, por favor entre em contato conosco: desenvolvimento@belaviagem.com ou (54) Todas requisições devem ser feitas para o endpoint ÍNDICE Página 1 Página 2 Página 3 Página 4 Página 5 Introdução Autenticação Retornos Erros Nova transação (prepare) Consulta transação (check) Cancelamento FAQ Glossário AUTENTICAÇÃO 1. Você deve entrar no painel de controle de sua empresa e cadastrar os IPs dos seus servidores que farão acesso à API. Se preferir, peça para cadastrarmos para você, por desenvolvimento@belaviagem.com. 2. Pegue seu IDEMPRESA e sua CHAVE DE ACESSO no seu painel de controle. Se preferir, peça para enviarmos para você, por desenvolvimento@belaviagem.com. RETORNOS Todos os retornos virão em uma string JSON. Exemplo de retorno: {"status":"75","msg_erro":"server not allowed"} [status] => 75 [msg] => server not allowed ERROS Todos os erros virão em uma string JSON. 'msg_erro' virá a descrição do erro encontrado Exemplo de erros: {"status":"75","msg_erro":"server not allowed"} {"status":"75","msg_erro":"refpedido not found"} {"status":"75","msg_erro":"refpedido numbers e letters only"} {"status":"75","msg_erro":"server not allowed,refpedido not found"} /* mais de um erro pode vir no

2 mesmo retorno*/ CRIAR TRANSAÇÕES Agora vamos mostrar como deve ser criada uma transação para gerar um pagamento para seu site. Deve usar o Method POST sempre. // PREPARE Com o path para a ação /prepare. ex.: Os campos que devem ser enviados ao servidor por POST para /prepare são: idempresa chave refpedido valor* nome celular maxparcelas aceitapgto* datahora tempo_limite* obs url_retorno 'integer NNN ' string 'string DDNNNNNNNN[N] ' 'integer NN ' 'string [ CARTAO,BOLETO, CARTAO, BOLETO ] ' 'string "Y-m-d H:i:s" ' 'integer "minute" ' use 60 para uma hora, 1440 para 1 dia, // Retorno PREPARE O retorno virá em uma string JSON. Se tudo der certo, sua Loja vai receber o retorno: {"token_venda":"pg ", "chave_secreta":"2dfef2c82d745341fa caf6438", "status":0, "msg":"ok", "url_checkout":" [token_venda] [chave_secreta] [status] [msg] [url_checkout] * aceitapgto default [CARTAO,BOLETO]. * valor mande o valor em centavos, para DEZ REAIS envie "1000", para UM REAL mande 100, envie UM REAL e DEZ CENTAVOS envie 110 (sem aspas). * tempo_limite define o tempo que o usuário tem para acessar o link e poder pagar, caso ele escolha boleto, o vencimento do boleto expira no mesmo dia do tempo_limite mas até as 23:59:59. Use tempo limite maiores que 10 para dar tempo do cliente pagar. Caso o cliente acesse o link após o tempo_limite a API não permitirá mais o pagamento por cartão, ou baixar o boleto.

3 CONSULTA TRANSAÇÕES // CHECK Com o path para a ação /check. ex.: Agora vamos consultar o status da transação para tomar a decisão de concluir ou não o pedido do cliente da Loja ecommerce. Esta consulta deve ser principalmente usada quando o cliente retornar à sua Loja através da URL_RETORNO informada na criação da transação. Mas também pode ser usada a qualquer momento após a criação de uma transação para consultar seu STATUS. Os campos que devem ser enviados ao servidor por POST para /check são: idempresa chave token_venda refpedido // Retorno CHECK O retorno virá em uma string JSON. Exemplos de Retorno: 1. Neste exemplo, status 0 (zero) SUCESSO. A sua loja já pode confirmar o pagamento com o cliente e enviar os produtos e/ou serviços para ele. {"token_venda":"pg ","chave_secreta":"2dfef2c82d745341fa caf6438","refpedido": "TESTE ","status":"1","status_msg":"Aguardando pagamento","tempo_limite":"1233","data_compra":" :15:52","valor":"3600","obs":"Minha compra de TESTE","url_checkout":" gramadosite.com.br/pagretorno.php"} 2. Neste exemplo, o status ainda é aguardando pagamento do pedido e a loja ecommerce ainda não pode confirmar o pedido junto com o cliente. {"token_venda":"pg ","refpedido":"teste ","status":"1","status_msg":"aguardando pagamento","tempo_limite":"1233","data_compra":" :15:52","valor":"3600","obs":"Minha compra de TESTE","url_checkout":" gramadosite.com.br/pagretorno.php"} Dica prática: Em PHP pode-se usar as funções fsockopen ou file_get_contents para executar as transações/consultas. Dica prática 2: Retornos de status do pagamento: 0=Pago, 1=Aguardando pagamento, 8=Pagamento expirado!, 9=Cancelada

4 CANCELAMENTO Agora vamos mostrar como deve ser cancelada uma transação. Transações com status 0 (Pago) podem ser canceladas. A transação pode ser cancelada Total ou Parcialmente. O campo valor somente é obrigatório se o cancelamento for parcial - se omitido, será feito um cancelamento total da transação. O cancelamento Parcial manterá o status atual da transação (Pago ou Pendente). Deve usar o Method POST sempre. //CANCEL Com o path para a ação /cancel. ex.: Os campos que devem ser enviados ao servidor por POST para /cancel são: idempresa chave token_venda // Retorno CANCEL {"status":"0","status_msg":"cancelamento efetuado"} FAQ. 1. Posso usar o mesmo refpedido em todas as minhas transações? R.: Não é recomendado, já que o campo pode ser usado para consulta (/check). Caso seja usado o mesmo refpedido em outro pedido, o sistema vai trazer o último enviado em uma consulta /check por refpedido, o que pode causar confusão em seu sistema. 2. Cancelei um pagamento antes do Cliente pagar. Tem como reativar? R.: Não. Instrua seu cliente a fazer novo pedido no seu site. 3. Meu cliente pagou o pedido, e eu (logista) cancelei erroneamente o pagamento. Posso descancelar? R.: Não. No momento que um cancelamento é pedido, imediatamente devolvemos os valores e não temos como reavê-los novamente. Neste caso instrua seu cliente a fazer novo pedido no seu site. 4. Não recebi o retorno de um /prepare. O que faço? R.: As vezes por momentos de instabilidade na internet podemos não receber a resposta de uma transação. Mas você pode fazer uma consula /check usando o refpedido para saber se seu pedido foi ou não recebido com sucesso. Por isso o 'refpedido' deve ser único! 5. Não tenho o token_venda, como faço para cancelar? R.: Simples. Faça uma consulta /check usando o refpedido, você vai receber os dados da transação, pronto agora você tem o token_venda para cancelar.

5 6. Meu sistema não é em PHP. Tem exemplos em minha linguagem de programação? R.: Ainda não temos. Mas o que usamos são webservices do tipo REST e retornamos strings JSON, o que torna a comunicação uma tarefa muito simples. Existe amplo material na internet sobre como comunicar com webservices REST em várias linguagens como: PHP, JAVA, PHYTON, C#, etc... GLOSSÁRIO IDEMPRESA - tipo: string - obrigatório É o ID da sua empresa na BelaViagem CHAVE tipo: string - obrigatório Sua chave de acesso para permitir as transações e consultas REFPEDIDO tipo: string Código do pedido da loja (seu site) para conferência. É permitido somente números e letras, não é permitido acentos. Pode ser usado para consulta se por algum motivo o token_venda não tiver sido recuperado após o prepare, por este motivo refpedido não deve ser repetido pela loja e-commerce e ter um único para cada chamada /prepare VALOR tipo: integer - obrigatório Valor deve ser enviado em centavos, pontuação de decimal e milhar serão ignoradas. Exemplos: R$ 10,00 (dez reais): envie 1000 / R$ 2,14 (dois reais e quatorze centavos): envie 214. NOME tipo: string Nome do cliente tipo: string do cliente CELULAR tipo: string Para envio de aviso via SMS MAXPARCELAS tipo: integer - obrigatório Máximo de parcelas para pagamento com cartão. DATAHORA tipo: string - "Y-m-d H:i:s" obrigatório Data e hora atual do servidor de origem no formato ano-mes-dia hora:minutos:segundos. Exemplo: :59:59 TEMPO_LIMITE tipo: integer - minute Prazo para pagamento em minutos. Default é 60 minutos. Antes de cancelar uma compra por timeout faça uma consulta (check) na API para saber o status do pagamento. OBS tipo: string Uma curta descrição do que ta sendo pago TOKEN_VENDA tipo: integer ID do pagamento junto à BelaViagem. Deve ser usado para as próximas etapas de consulta e cancelamento. CHAVE_SECRETA tipo: string Chave para confirmação do pagamento; esta chave virá no retorno de uma consulta caso a compra tenha sido paga com sucesso. URL_RETORNO tipo: string URL de retorno da sua Loja quando o pagamento tiver sido concluído.

6 Exemplo: " URL_CHECKOUT tipo: string URL que a loja deve redirecionar o browser do cliente para o cliente da Loja poder efetuar o pagamento STATUS tipo: integer Código do retorno. Status 0 (zero) virá em caso de sucesso. Na consulta (check), poderá vir s status: 0=Pago, 1=Aguardando pagamento, 8=Pagamento expirado!, 9=Cancelada MSG_ERRO tipo: string - Mensagem de retorno. Retorno ok em caso de sucesso.