PLATAFORMA PAGADOR AUTORIZAÇÃO, CANCELAMENTO E CAPTURA.

Transcrição

1 PLATAFORMA PAGADOR AUTORIZAÇÃO, CANCELAMENTO E CAPTURA. Versão /05/2011

2 SUMÁRIO HISTÓRICO DE ALTERAÇÕES...3 INTRODUÇÃO AUTORIZAÇÃO Método Authorize Retorno do Método Authorize CAPTURA Método Capture Retorno do Método Capture CANCELAMENTO Método VoidTransaction Retorno do Método VoidTransaction CONSULTA Método GetDadosPedido Retorno do Método GetDadosPedido EXEMPLOS AUTHORIZE Linguagem C SHARP (C#) PHP EXEMPLOS CAPTURE Linguagem C SHARP (C#) PHP MÉTODO VOIDTRANSACTION Linguagem C SHARP (C#) PHP MÉTODO GETDADOSPEDIDO Linguagem C SHARP (C#) PHP...26 Telefone: (21) / (11) Página 2 de 26

3 HISTÓRICO DE ALTERAÇÕES MUDANÇAS MANUAL WEBSERVICE PAGADOR Versão Data Descrição Autor /06/2010 Versão inicial Bianca Barcelos /11/2010 Correção no método Capture Luís Félix /03/2011 Criação dos exemplos referente aos métodos Ivan Alexandre /04/2011 Alterações no método autorize: Número de caracteres da string enviados no merchantid, orderid. Alterações no método Capture: Número de caracteres da string retornados no message e status Alterações no método Void: Número de caracteres da string retornados no orderid; número de caracteres da string enviados no orderid; Alterações no método GetDadosPedido: Número de caracteres da string enviados no merchantid /04/2011 Menção à exceção de envio de parâmetro Cielo; Padronização Manual. Modificações e inclusões de textos. Rodrigo Andrade Rodrigo Andrade 2.3 Alteração método Capture Ivan Alexandre Telefone: (21) / (11) Página 3 de 26

4 INTRODUÇÃO Este manual descreve as quatro principais funcionalidades do Webservice da Plataforma Pagador: Autorização, Captura, Consulta e Cancelamento. Segue abaixo o link dos Métodos Webservice: Homologação: Para receber a url de produção, solicite à nossa equipe de implantação através da ferramenta Suporte ou verifique a FAQ 61 na ferramenta suporte (). Como fator de segurança é altamente indicado o envio dos IP s de seus servidores para que possamos fazer restringir os acessos. É necessário enviar também os IP s dos das máquinas dos desenvolvedores para que possam realizar testes. Existem outros métodos do Webservice: AuthorizeAvs Authorize an order using AVS AuthorizeAvsStatus Authorize an order using AVS AuthorizeExistingAvsStatusWithService Authorize an existing order using the transid AuthorizeMobile Authorize a Mobile order AuthorizeMobilePartial Authorize a Mobile order (Partial, Internal) Telefone: (21) / (11) Página 4 de 26

5 AuthorizeWithDateFirstInstallment Authorize an order with DateFirstInstallment AuthorizeWithServiceTax Authorize an order with service tax CapturePartial Capture Part of an order OneDollarAuth Authorize a credit card order and cancel the order right after confirmation VoidPartial Cancel Part of an order CreateBoleto Create a new boleto CancelarCaptura Este método cancela a captura de um pedido CancelarPedido Este método cancela um pedido GetDadosBoleto Este método retorna todos os dados relativos ao boleto utilizado na compra GetDadosCartao Este método retorna todos os dados relativos ao cartã o de crédito utilizado na compra GetDadosComprador Este método retorna todos os dados relativos ao comprador GetDadosEntrega Este método retorna todos os dados relativos à entrega Telefone: (21) / (11) Página 5 de 26

6 GetDadosExtras Este método retorna todos os campos extras relativos ao pedido GetDadosPedido Este método retorna todos os dados relativos ao pedido Caso algum destes métodos atenderem às suas necessidades, solicite o manual ao time de implementação pela Ferramenta Suporte (). Telefone: (21) / (11) Página 6 de 26

7 1. AUTORIZAÇÃO Para o envio dos pedidos de cartão de crédito, deve-se utilizar o método Authorize. 1.1 Método Authorize Para realizar autorizações deve-se chamar o método Authorize. Este método é utilizado para autorização de transações de cartão de crédito e recebe os parâmetros da tabela 1. Tabela 1 Parâmetros enviados pelo método Authorize Parâmetro Descrição Máx. Obrigatório merchantid Identificador único da loja. 38 Sim Fornecido pela Braspag. { } orderid Número do pedido 20 Sim customername Nome do comprador. 100 Sim amount Valor total do pedido no formato 10 Sim brasileiro: 0.000,00 paymentmethod Código do meio de pagamento - Sim (veja Tabela 10) holder Nome do portador do cartão 100 Sim crédito cardnumber Número do cartão de crédito - Sim expiration Data de validade do cartão de 7 Sim crédito (formato mm/aa) securitycode Código de segurança do cartão de 4 Sim crédito numberpayments Número de parcelas 2 Sim (para pagamento à vista o valor deve ser 01) typepayment Tipo (veja Tabela 1.1) 2 Sim Telefone: (21) / (11) Página 7 de 26

8 Todos os parâmetros devem ser enviados como string; OBS: As novas modalidades da plataforma CIELO não aceitam no orderid envio letras ou caracteres especiais como traços, vírgulas e etc. Tabela 1.1 Tipos de pagamento Códigos Tipo de Pagamento 0 À Vista 1 Parcelado pelo estabelecimento 2 Parcelado pelo emissor do cartão 3 Parcelado IATA pelo estabelecimento* 4 Parcelado IATA pelo emissor do cartão* 5 À Vista, com IATA vdvd * Tipo de pagamento para companhia aérea. Telefone: (21) / (11) Página 8 de 26

9 1.2 Retorno do Método Authorize O método Authorize retornará os parâmetros dos pedidos realizados no método Authorize; é obrigatório o armazenamento dos dados de retorno. Verifique a tabela abaixo que contém quais são os parâmetros. Tabela 2 Parâmetros retornados pelo método Authorize Parâmetro Descrição Máx. Tipo authorizationnum ber Número da autorização, caso tenha sido autorizado. - string amount Valor total do pedido no formato 10 string brasileiro: 0.000,00 transactionid Código de autorização da operadora 50 string message Mensagem da Operadora ou Banco 512 string returncode Código de retorno da Operadora ou 50 string Banco status Status da Transação ver Tabela int Tabela 2.1 Status de retorno dos métodos Authorize Status Código Descrição Autorizado 1 O pedido foi autorizado e aguarda captura.* Confirmado 0 O pedido foi Capturado. Negado 2 O pedido foi negado checar o campo mensagem Falha no AVS 8 Os dados do AVS não conferem Transação em Progresso Transação já realizada 12 Indica que um pedido com o mesmo número está em andamento, já foi iniciado pela loja junto à Braspag, mas ainda não foi finalizado junto à Operadora. Status Não Pago.** 13 Indica que um pedido com o mesmo número já foi feito anteriormente e o obteve sucesso. Status Pago.** Erro interno null Um erro aconteceu antes de o pedido ser enviado à operadora Telefone: (21) / (11) Página 9 de 26

10 ATENÇÃO! O pedido poderá ser tratado como pago apenas quando for retornado status 0 (Capturado). * A captura pode ocorrer de três maneiras: - após alguns minutos automaticamente. - após algumas horas, se houver um delay pré definido pelo estabelecimento. - enviando o WebService de captura. (para utilizar essa opção o estabelecimento deve estar com a opção captura manual ativada). **A Braspag disponibiliza uma opção para bloquear transações com número de pedido repetido. O Bloqueio ativo só funcionará para pedidos que consta na Braspag com o status Não Pago e Pago. Este bloqueio só funciona para pedidos efetuados com o mesmo meio de pagamento, ou seja, se um pedido for enviado via cartão de crédito e depois o mesmo pedido como boleto, a função habilitada NÃO bloqueará o pedido. Para habilitar essa funcionalidade é necessário solicitar à área de Relacionamento com Cliente através da ferramenta de suporte (). Telefone: (21) / (11) Página 10 de 26

11 2. CAPTURA Para realizar capturas deve-se chamar o método Capture. Este método é utilizado para capturar as transações de cartão de crédito depois de aprovadas. Este Webservice é útil para empresas que não trabalham com captura automática, ou seja, programam um delay nas capturas dos cartões de crédito. 2.1 Método Capture Os parâmetros recebidos pelo Método Capture estão na tabela abaixo. Tabela 3 Parâmetros enviados pelo método Capture Parâmetro Descrição Máx. Obrigatório merchantid Identificador único da loja. Fornecido 38 Sim pela Braspag. { } orderid Número do pedido. 20 Sim OBS: Todos os parâmetros devem ser enviados como string. Telefone: (21) / (11) Página 11 de 26

12 2.2 Retorno do Método Capture O método Capture retornará os parâmetros abaixo. Tabela 4 Parâmetros retornados pelo método Capture Parâmetro Descrição Máx. Tipo amount Valor total do pedido no formato 10 string brasileiro: 0.000,00 returncode Código de retorno da Operadora ou 50 string Banco status Status ver Tabela int message Mensagem da Operadora ou Banco 512 string transactionid Id da transação 255 string Tabela 4.1 Possíveis status de retorno do método Capture Status Código Descrição Capturado 0 O pedido foi capturado com Sucesso Negado 2 O pedido de captura foi negado checar campo message Erro interno null Um erro aconteceu antes de o pedido ser enviado à operadora Telefone: (21) / (11) Página 12 de 26

13 3. CANCELAMENTO Para realizar cancelamento de pedidos via WebService, deve-se chamar o método VoidTransaction. Este WebService poderá ser utilizado de duas maneiras: para cancelar uma venda antes da captura (para clientes que utilizam delay de captura); e cancela pedidos até às 23h59min59s (horário de Brasília) do mesmo dia da captura. Qualquer pedido que esteja fora deste prazo não poderá ser cancelado com este método, sendo necessário utilizar outra plataforma da Braspag (Refund). Entre em contato com nossa equipe comercial para maiores informações Método VoidTransaction Este método recebe os seguintes parâmetros: Tabela 5 Parâmetros recebidos pelo método VoidTransaction. Parâmetro Descrição Máx. Obrigatório order Número do pedido. 20 Sim merchantid Identificador único da loja. Fornecido pela Braspag { } 38 Sim OBS: Todos parâmetros devem ser enviados como string. Existem algumas particularidades para American Express e Redecard: Para American Express só poderá ser cancelado um pedido depois de sua captura; Para Redecard será necessário informar à equipe de implatantação, através da ferramenta Suporte (/) o usuário e senha de void. Entre em contato com o time de implantação para maiores informações. Telefone: (21) / (11) Página 13 de 26

14 3.2 Retorno do Método VoidTransaction O método VoidTransaction, retornará os parâmetros abaixo. Tabela 6 Parâmetros retornados pelo método VoidTransaction Parâmetro Descrição Max. Tipo orderid Identificador do pedido interno do 20 string estabelecimento message Mensagem da Operadora ou Banco 512 string returncode Código de retorno da Operadora 50 string status Status da Transação ver Tabela int transactionid Número da transação na Operadora ou Banco 50 string amount Valor total do pedido no formato brasileiro: 0.000,00 10 string Tabela 6.1 Possíveis status de retorno do método VoidTransaction Status Código Descrição VoidConfirmed 0 O pedido foi cancelado com sucesso VoidDenied 1 O pedido não foi cancelado InvalidTransaction 2 O pedido não foi encontrado ou já foi cancelado no sistema Telefone: (21) / (11) Página 14 de 26

15 4. CONSULTA As modalidades de consulta permitem realizar consultas de pedidos. 4.1 Método GetDadosPedido Este método permite realizar consultas dos status do pedido na Braspag via WebService. Este método recebe os seguintes parâmetros: Tabela 7 Parâmetros recebidos pelo método GetDadosPedido Parâmetro Descrição Máx. Obrigatório merchantid Identificador único da loja.fornecido pela 38 Sim Braspag. { } orderid Número do Pedido 20 Sim Telefone: (21) / (11) Página 15 de 26

16 4.2 Retorno do Método GetDadosPedido O método GetDadosPedido, retornará os parâmetros abaixo: Tabela 8 Parâmetros retornados pelo método GetDadosPedido Parâmetro Descrição Max. Tipo CodigoAutorizacao Código de autorização ou vazio caso o - string pedido não tenha sido autorizado CodigoErro Código do erro ou vazio caso não houve - string erro MensagemErro Mensagem de erro ou vazio caso não - string houve erro CodigoPagamento Código do meio de pagamento Tabela - string 10 FormaPagamento String contendo o nome do meio de - string pagamento NumeroParcelas Número de parcelas - string Status Status do pedido ver tabela int Valor Valor do pedido - float DataCancelamento Data e hora do cancelamento do - string pedido, caso tenha sido cancelado formato mm/dd/aaaa hh:mm:ss tt (tt = AM/PM) DataPagamento Data e hora do pagamento do pedido, - string caso tenha sido pago formato mm/dd/aaaa hh:mm:ss tt (tt = AM/PM) DataPedido Data e hora do pedido - formato - string mm/dd/aaaa hh:mm:ss tt (tt = AM/PM) TransId Número da transação no adquirente - string BraspagTid Identificador único da transação na Braspag - string Telefone: (21) / (11) Página 16 de 26

17 Tabela 8.1 Possíveis status de retorno do método GetDadosPedido Status Cód. Descrição Iniciado 1 O pedido foi enviado para o adquirente mas ainda não foi finalizado Finalizado 2 O pedido foi finalizado caso o mesmo tenha sido autorizado, o campo CodigoErro será vazio. Se foi recusado, o campo CodigoErro virá preenchido com o código retornado pelo adquirente Pago 3 O pedido foi autorizado e confirmado Cancelado 4 O pedido foi cancelado ATENÇÃO! O pedido poderá ser tratado como pago apenas quando for retornado status 3 (Pago). Telefone: (21) / (11) Página 17 de 26

18 Tabela 9 Meios de Pagamento: indica o meio de pagamento a ser utilizado na transação via WebService Meio de Pagamento (Brasil) [Brasil] American Express 2 party 18 Código [Brasil] Cielo Webservice Captura 71 Automática sem Autenticação Visa [Brasil] Cielo Webservice Preauth 73 sem autenticação Visa [Brasil] Cielo Webservice Captura 120 Automática sem Autenticação Mastercard [Brasil] Cielo Webservice Preauth 122 sem Autenticação Mastercard [Brasil] Redecard 20 Mastercard/Diners/Visa [Brasil] Redecard PreAuth - 42 Mastercard/Diners/Visa [Brasil] Cielo SITEF 57 [Brasil] Hipercard SITEF 62 [Brasil] Hipercard MOIP 90 [Brasil] OiPaggo 55 [Brasil] Amex SITEF 58 [Brasil] Aura - DTEF 37 [Brasil] Redecard SITEF - Mastercard/Diners Meio de Pagamento (Internacional) 44 [México] Amex 2Party 45 [México] Banorte Visa 50 [México] Banorte Diners 52 [México] Banorte Mastercard 53 [Colômbia] Visa 63 [Colômbia] Mastercard 64 [Colômbia] Amex 65 [Colômbia] Diners 66 PayPal Express Checkout 35 Código ATENÇÃO! A loja deverá ter o meio de pagamento previamente configurado no sistema Pagador. Telefone: (21) / (11) Página 18 de 26

19 5. EXEMPLOS AUTHORIZE 5.1 Linguagem C SHARP (C#) Exemplos utilizados em uma aplicação Console (pode ser utilizado em qualquer tipo de projeto). Funciona em ambos os ambientes, homologação e produção, necessitando apenas a troca da url. br.com.pagador.homologacao.pagador Pagador = new br.com.pagador.homologacao.pagador(); string merchantid = " "; string orderid = "123456"; string customername = "Teste"; string amount = "0,01"; string paymentmethod = "18"; string holder = "teste"; string cardnumber = " "; string expiration = "05/13"; string securitycode = "1234"; string numberpayments = "1"; string typepayment = "0"; br.com.pagador.homologacao.pagadorreturn PagadorReturn = Pagador.Authorize(merchantId, orderid, customername, amount, paymentmethod, holder, cardnumber, expiration, securitycode, numberpayments, typepayment); Console.WriteLine("Return Code: "+PagadorReturn.returnCode); Console.WriteLine("Message: " + PagadorReturn.message); Console.WriteLine("Amount: " + PagadorReturn.amount); Console.WriteLine("Authorisation Number: " +PagadorReturn.authorisationNumber); Console.WriteLine("Status: " + PagadorReturn.status); Console.WriteLine("Transaction Id: " + PagadorReturn.transactionId); Console.ReadLine(); Telefone: (21) / (11) Página 19 de 26

20 5.2 PHP Exemplo de como chamar o método Authorize (utilizando o SOAP), sua utilização pode ser nos dois ambientes, homologação e produção, necessitando apenas a troca da url. <?php ini_set("soap.wsdl_cache_enabled", "0"); $SoapClient = new SoapClient(" L"); $parametros = array(); $parametros["merchantid"] = " "; $parametros["orderid"] = "12345"; $parametros["customername"] = "Teste"; $parametros["amount"] = "0,01"; $parametros["paymentmethod"] = "18"; $parametros["holder"] = "teste"; $parametros["cardnumber"] = " "; $parametros["expiration"] = "05/13"; $parametros["securitycode"] = "1234"; $parametros["numberpayments"] = "1"; $parametros["typepayment"] = "0"; var_dump($soapclient->authorize($parametros));?> Telefone: (21) / (11) Página 20 de 26

21 6. EXEMPLOS CAPTURE 6.1 Linguagem C SHARP (C#) Exemplo utilizado em uma aplicação Console (pode ser utilizado em qualquer tipo de projeto). Funciona em ambos os ambientes, homologação e produção, necessitando apenas a troca da url. br.com.pagador.homologacao.pagador Pagador = new br.com.pagador.homologacao.pagador(); string merchantid = " "; string orderid = "123456"; br.com.pagador.homologacao.pagadorreturn PagadorReturn = Pagador.Capture(merchantId, orderid); Console.WriteLine("Return Code: "+PagadorReturn.returnCode); Console.WriteLine("Message: " + PagadorReturn.message); Console.WriteLine("Amount: " + PagadorReturn.amount); Console.WriteLine("Status: " + PagadorReturn.status); Console.ReadLine(); Telefone: (21) / (11) Página 21 de 26

22 6.2 PHP Exemplo de como chamar o método Capture (utilizando o SOAP), sua utilização pode ser nos dois ambientes, homologação e produção, necessitando apenas a troca da url. <?php ini_set("soap.wsdl_cache_enabled", "0"); $SoapClient = new SoapClient(" DL"); $parametros = array(); $parametros["merchantid"] = " "; $parametros["orderid"] = "123456"; var_dump($soapclient->capture($parametros));?> Telefone: (21) / (11) Página 22 de 26

23 7. MÉTODO VOIDTRANSACTION 7.1 Linguagem C SHARP (C#) Exemplo utilizado em uma aplicação Console (pode ser utilizado em qualquer tipo de projeto). Funciona em ambos os ambientes, homologação e produção, necessitando apenas a troca da url. br.com.pagador.homologacao.pagador Pagador = new br.com.pagador.homologacao.pagador(); string merchantid = " "; string order = "123456"; br.com.pagador.homologacao.pagadorvoidreturn PagadorReturn = Pagador.VoidTransaction(merchantId, order); Console.WriteLine("Return Code: "+PagadorReturn.returnCode); Console.WriteLine("Message: " + PagadorReturn.message); Console.WriteLine("Amount: " + PagadorReturn.amount); Console.WriteLine("Status: " + PagadorReturn.status); Console.WriteLine("Order Id: " + PagadorReturn.orderId); Console.WriteLine("Transanction Id: " + PagadorReturn.transactionId); Console.ReadLine(); Telefone: (21) / (11) Página 23 de 26

24 7.2 PHP Exemplo de como chamar o método VoidTransaction (utilizando o SOAP), sua utilização pode ser nos dois ambientes, homologação e produção, necessitando apenas a troca da url. <?php ini_set("soap.wsdl_cache_enabled", "0"); $SoapClient = new SoapClient(" DL"); $parametros = array(); $parametros["merchantid"] = " "; $parametros["order"] = "123456"; var_dump($soapclient->voidtransaction($parametros));?> Telefone: (21) / (11) Página 24 de 26

25 8. MÉTODO GETDADOSPEDIDO 8.1 Linguagem C SHARP (C#) Exemplo utilizado em uma aplicação Console (pode ser utilizado em qualquer tipo de projeto). Funciona em ambos os ambientes, homologação e produção, necessitando apenas a troca da url. br.com.pagador.homologacao.pedido Pedido = new br.com.pagador.homologacao.pedido(); string loja = " "; string numeropedido = "123456"; br.com.pagador.homologacao.dadospedido DadosPedidoReturn = Pedido.GetDadosPedido(loja, numeropedido); Console.WriteLine("Codigo Autorizacao: " + DadosPedidoReturn.CodigoAutorizacao); Console.WriteLine("Codigo Erro: " + DadosPedidoReturn.CodigoErro); Console.WriteLine("Mensagem Erro: " + DadosPedidoReturn.MensagemErro); Console.WriteLine("Codigo Pagamento: " + DadosPedidoReturn.CodigoPagamento); Console.WriteLine("Forma Pagamento: " + DadosPedidoReturn.FormaPagamento); Console.WriteLine("Numero Parcelas: " + DadosPedidoReturn.NumeroParcelas); Console.WriteLine("Status: " + DadosPedidoReturn.Status); Console.WriteLine("Valor: " + DadosPedidoReturn.Valor); Console.WriteLine("Data Cancelamento: " + DadosPedidoReturn.DataCancelamento); Console.WriteLine("Data Pagamento: " + DadosPedidoReturn.DataPagamento); Console.WriteLine("Data Pedido: " + DadosPedidoReturn.DataPedido); Console.WriteLine("Trans Id: " + DadosPedidoReturn.TransId); Console.WriteLine("Braspag Tid: " + DadosPedidoReturn.BraspagTid); Console.ReadLine(); Telefone: (21) / (11) Página 25 de 26

26 8.2 PHP Exemplo de como chamar o método GetDadosPedido (utilizando o SOAP), sua utilização pode ser nos dois ambientes, homologação e produção, necessitando apenas a troca da url. <?php ini_set("soap.wsdl_cache_enabled", "0"); $SoapClient = new SoapClient(" "); $parametros = array(); $parametros["loja"] = " "; $parametros["numeropedido"] = "123456"; var_dump($soapclient->getdadospedido($parametros));?> Telefone: (21) / (11) Página 26 de 26