guia de implementação - documentation payzen · [email protected]. entrar em contato com o...

Pagamento por token -Pagamento por assinatura

Guia de implementação

Versão do documento 3.9

Conteúdo

1. HISTÓRICO DO DOCUMENTO........................................................................................................4

2. OBTER AJUDA.....................................................................................................................................6Consultar a documentação..................................................................................................................................6Entrar em contato com o suporte.......................................................................................................................6

3. GERENCIAR OS PAGAMENTOS POR TOKEN CARTÃO............................................................7

4. MEIOS DE PAGAMENTO COMPATÍVEIS..................................................................................... 8

5. O COMPARTILHAMENTO DE TOKEN CARTÃO......................................................................10

6. GERENCIAR OS TOKEN CARTÕES A PARTIR DO FORMULÁRIO DE PAGAMENTO......116.1. Criação de um Token Cartão sem pagamento..........................................................................................126.2. Modificação das informações associadas ao Token Cartão......................................................................136.3. Criação de um Token Cartão durante um pagamento.............................................................................. 146.4. Criação de um Token Cartão na contratação de uma assinatura.............................................................. 156.5. Criação de um Token Cartão na contratação de uma assinatura seguida de um pagamento.....................176.6. Pagamento por Token Cartão....................................................................................................................18

Pagamento por Token Cartão e Garantia de Pagamento..................................................................... 186.7. Uso de um Token Cartão para contratar uma assinatura..........................................................................196.8. Pagamento com proposta ao portador de criar um Token Cartão............................................................ 206.9. Modificação de informações associadas a um Token Cartão durante um pagamento.............................. 21

7. CICLO DE VIDA DE UM PAGAMENTO RECORRENTE........................................................... 22

8. CICLO DE VIDA DE UM PAGAMENTO RECORRENTE COM AUTORIZAÇÃOPRÉVIA............................................................................................................................................... 23

8.1. Lista dos códigos retorno da solicitação de autorização...........................................................................258.2. Notificação por e-mail quando uma parcela foi recusada........................................................................ 26

9. ESTABELECER O DIÁLOGO COM A PLATAFORMA DE PAGAMENTO.............................. 279.1. Similaridades com o pagamento unitário..................................................................................................27

10. CONFIGURAR AS NOTIFICAÇÕES............................................................................................ 2810.1. Configurar a notificação no final do pagamento.................................................................................... 2910.2. Configurar a notificação se o comprador desistir ou cancelar................................................................3010.3. Configurar a notificação em uma operação procedente do Back Office................................................ 3110.4. Configurar a notificação durante a criação de uma assinatura............................................................... 3210.5. Configure a notificação em autorização por batch................................................................................. 3310.6. Re-chamada automática em caso de falha.............................................................................................. 3410.7. Configurar os e-mails enviados para o comprador................................................................................. 36

11. CRIAR UM FORMULÁRIO DE PAGAMENTO......................................................................... 3711.1. Criar um formulário "Criação do Token Cartão sem pagamentos"........................................................ 3911.2. Criar um formulário “Modificação das informações associadas ao Token Cartão”............................... 3911.3. Criar um formulário "Criação do Token Cartão durante um pagamento".............................................. 4111.4. Criar um formulário “Criação de um Token Cartão na contratação de uma assinatura”........................ 4211.5. Criar um formulário “Criação de um Token Cartão na contratação de uma assinatura seguida de

um pagamento”............................................................................................................................................4411.6. Criar um formulário "Pagamento por Token Cartão "............................................................................4611.7. Criar um formulário “Uso de um Token Cartão para contratar uma assinatura”....................................4711.8. Criar um formulário “Pagamento com proposta ao portador de criação de Token Cartão”....................4911.9. Criar um formulário “Modificação de informações associadas a um Token Cartão durante um

pagamento”.................................................................................................................................................. 50

12. USAR FUNÇÕES COMPLEMENTARES......................................................................................5112.1. Definir um valor diferente para as x primeiras parcelas.........................................................................5212.2. Definir a moeda para criar ou a atualizar um Token Cartão.................................................................. 52

13. CALCULAR A ASSINATURA........................................................................................................54

14. ENVIAR A SOLICITAÇÃO DE PAGAMENTO...........................................................................5614.1. Redirecionar o comprador para a página de pagamento.........................................................................5614.2. Gerenciar os erros....................................................................................................................................5614.3. Gerenciar os timeout............................................................................................................................... 58

15. IMPLEMENTAR A IPN................................................................................................................. 5915.1. Preparar seu ambiente............................................................................................................................. 6015.2. Recuperar os dados devolvidos na resposta............................................................................................6115.3. Calcular a assinatura do IPN...................................................................................................................6215.4. Comparar as assinaturas.......................................................................................................................... 6315.5. Analisar a natureza da notificação.......................................................................................................... 6415.6. Tratar os dados da resposta.....................................................................................................................65

Criação de um Token Cartão............................................................................................................... 65Modificação das informações associadas ao Token Cartão.................................................................68Criação de um Token Cartão durante um pagamento..........................................................................70Criação de um Token Cartão na contratação de uma assinatura......................................................... 73Criação de um Token Cartão na contratação de uma assinatura seguida de um pagamento................76Pagamento por Token Cartão............................................................................................................... 79Contratação de uma assinatura............................................................................................................. 81Pagamento com proposta ao portador de criar um Token Cartão........................................................82Modificação de informações associadas a um Token Cartão durante um pagamento......................... 85

15.7. Teste e troubleshooting........................................................................................................................... 88

16. ANEXOS............................................................................................................................................9116.1. Criar automaticamente uma assinatura por Web services...................................................................... 9116.2. Rescindir automaticamente uma assinatura por Web services............................................................... 91

Pagamento por token - Pagamento por assinatura - Versão do documento 3.9

Todos os direitos reservados - 4 / 91

1. HISTÓRICO DO DOCUMENTO

Versão Autor Data Comentário

3.9 Lyra Network 05/05/2020 • Adição de uma precisão sobre o fim das tentativas realizadaspela plataforma de pagamento quando ativar as autorizaçõesantecipadas.

• Precisões adicionadas na criação dos pagamentos no caso deum meio de pagamento vencido ou de dados do meio depagamento apagados.

• Atualização da configuração das regras de notificações.

3.8 Lyra Network 21/10/2019 • Atualização dos meios de pagamento compatíveis.

• Adição de um capítulo sobre a garantia de pagamento no casode um pagamento por Token Cartão.

• Atualização da descrição do campo vads_sub_desc no capítuloGerar um formulário de pagamento.

3.7 Lyra Network 05/08/2019 • O algoritmo de hash está agora disponível no menuConfiguração > Loja, aba Chaves.

• Adição do campo vads_identifier em parâmetro de entrada nacriação de um Token Cartão.

• Adição da categoria Informações sobre a análise de riscos noDicionário de dados.

• vads_threeds_auth_type: o campo consta sempre na respostae pode estar vazio.

• O algoritmo de hash está agora disponível no menuConfiguração > Loja, aba Chaves.

• Precisões adicionadas no cálculo de assinatura do IPN.

• Precisão adicionada sobre o formato dos camposvads_trans_date evads_presentation_date.

• Precisão adicionada sobre o formato doscampos vads_product_label, vads_cust_zip, vads_order_id,vads_cust_first_name, vads_cust_last_name,vads_cust_phone, vads_cust_cell_phone, vads_cust_id,vads_cust_city, vads_cust_address

• vads_auth_result: correção do formato do campo (an..11)

• vads_contracts: Pode-se forçar o Terminal ID a ser usado.

3.6 Lyra Network 22/05/2019 Precisões sobre os métodos de criação e de rescisão deassinatura via os web servicesDicionário de dados: Atualização do campo vads_trans_date

3.5 Lyra Network 26/03/2019 • Adição de uma precisão sobre o expurgo dos dados no capítuloGerenciar os pagamentos por Token Cartão.

• Adição das horas de criação dos pagamentos recorrentes nocapítulo Gerenciar os pagamentos por Token Cartão.

• Atualização das capturas nos capítulos Criar um Token Cartãoem modo Test e Criar um Token Cartão em modo Production

• Atualização das capturas em Criar uma assinatura no BackOffice Estabelecimento Comercial

• Adição do capítulo Definir a moeda para criar ou a atualizarum Token Cartão.

• Atualização do quadro de parâmetro no capítulo Criar umformulário "Pagamento com proposta ao portador de criarum Token Cartão"



Versão Autor Data Comentário• Dicionário de dados:

• Adição de uma precisão sobre o formato do campovads_product_qty

• Adição do campo vads_presentation_date na seçãoInformações sobre a transação

• Adição de uma precisão sobre o formato do campovads_identifier

• Adição de uma precisão sobre o formato do campovads_subscription

• Exclusão dos campos vads_ext_info_donation,vads_ext_info_donation_recipient,vads_ext_info_donation_recipient_name,vads_ext_info_donation_merchant,vads_ext_info_donation_contributionevads_risk_primary_warranty

3.4 Lyra Network 19/12/2018 • Reformulação do capítulo Analisar o resultado do pagamento.

• Dicionário de dados:

• Adição do campo vads_bank_label

• Adição do campo vads_tax_rate

• Adição do campo vads_pretax_amount

• Adição do campo vads_totalamount_vat

• Adição do campo vads_wallet

• Atualização da descrição do campovads_ship_to_legal_name

• Atualização da descrição do campo vads_payment_src

• Atualização dos valores do campovads_bank_product

• Atualização da descrição do campo vads_tax_amount

Este documento e o seu conteúdo são estritamente confidenciais. Ele não é contratual. Qualquerreprodução e/ou distribuição de todo ou parte deste documento ou seu conteúdo a terceiros é

estritamente proibida ou sujeita a uma autorização prévia de Lyra Network. Todos os direitos reservados.



2. OBTER AJUDA

Consultar a documentação

Você está procurando ajuda? Consulte nossos sites de documentações e suporte

Na Europa https://payzen.io/en-EN/faq/sitemap.htmlNa América Latina (salvo Brasil) https://payzen.io/lat/faq/sitemap.htmlNo Brasil https://payzen.io/pt-BR/faq/sitemap.htmlNa Índia https://payzen.io/in/faq/sitemap.html

Procuramos sempre aperfeiçoar o entendimento e o uso das documentações de nossos produtos. Damossempre valor às observações de nossos clientes.

Favor enviar seus comentários e sugestões sobre a documentação para o endereç[email protected].

Entrar em contato com o suporte

Para perguntas técnicas ou solicitação de assistência, nossos serviços estão abertos de segunda à sexta-feira, das 8h às 17h

Por telefone Por e-mail

Na França [email protected]

Na Europa [email protected]

Na América Latina (salvo Brasil) N/A [email protected]

No Brasil+55 (11) 3336-9217+55 (11) 3336-9209

[email protected]

Na Índia +91 (022) 33864910 / 932 [email protected] via seu Back Office Estabelecimento Comercial, menu Ajuda > Entrar em contato com o suporte

Para facilitar o atendimento das suas solicitações, você deverá informar seu código de loja (número com8 dígitos).

Esta informação está disponível no e-mail de cadastro da sua loja ou no Back Office EstabelecimentoComercial (menu Configuração > Loja > Configuração).

https://payzen.io/en-EN/faq/sitemap.html

https://payzen.io/lat/faq/sitemap.html

https://payzen.io/pt-BR/faq/sitemap.html

https://payzen.io/in/faq/sitemap.html

mailto:[email protected]








3. GERENCIAR OS PAGAMENTOS POR TOKEN CARTÃO

Gerenciador de pagamentos por Token Cartão

O serviço de Gerenciamento dos pagamentos por Token Cartão possibilita aos EstabelecimentosComerciais propor aos seus clientes associar um Token Cartão com um meio de pagamento, com afinalidade de facilitar pagamentos posteriores no site (não é mais preciso digitar toda vez o número decartão bancário).

Os Token Cartão possibilitam:

• pagamentos rápidos e seguros.

O comprador não precisa mais digitar seus dados bancários nos pagamentos posteriores (pagamentoem 1 clique).

Os dados bancários estão armazenados pela plataforma em um ambiente altamente seguro, conformeo padrão PCI-DSS. Somente o Token Cartão é enviado durante as trocas.

• efetuar pagamentos recorrentes (assinatura).

O serviço permite também:

• identificar os cartões próximos ao vencimento, para avisar o Estabelecimento Comercial enviando umarquivo com os Token Cartões cujo cartão chega ao vencimento.

• atualizar os dados bancários associados a um Token Cartão na página de pagamento, ou manualmenteno Back Office Estabelecimento Comercial.

• gerenciar a modificação dos outros dados relativos ao comprador.

Conforme as regras de segurança e de proteção dos dados bancários exigidos pelo PCI DSS, os dados domeio de pagamento são expurgados após 15 meses de não uso do Token Cartão associado.

O Token Cartão será sempre exibido Back Office Estabelecimento Comercial e poderá ser atualizado comnovos dados.

Gerenciamento dos pagamentos recorrentes (assinatura)

O serviço de Gerenciamento dos pagamentos recorrentes permite aos Estabelecimentos Comerciais criarassinaturas, chamados também pagamentos recorrentes, com ou sem datas de fim, e limitados à data devencimento do cartão.

Na criação de um pagamento recorrente, o Estabelecimento Comercial define a data de inicio e a regrade recorrência para aplicar.

Em modo TEST, as transações são criadas a cada hora para que o Estabelecimento Comercial possa testarfacilmente o tratamento do IPN.

Em modo PRODUCTION, as transações são criadas uma vez por dia entre meia-noite e 05h00.



4. MEIOS DE PAGAMENTO COMPATÍVEIS

Lista dos meios de pagamento compatíveis com o serviço de Gerenciamento dos pagamentos por TokenCartão:

Código Rede Meio de pagamentoTipo de cartões

(vads_payment_cards)Suporta o pagamento

por Token Cartão

BOLETO Boleto Bancário BOLETO

BONSUCESSO Cartão de Crédito Hipercard HIPERCARD

BONSUCESSO Cartão ELO ELO

BONSUCESSO Cartão Maestro MAESTRO

BONSUCESSO Cartão Mastercard MASTERCARD

BONSUCESSO Cartão Visa VISA

BONSUCESSO Cartão Visa Electron VISA_ELECTRON

BRADESCO_IB Boleto Bradesco BRADESCO_BOLETO

CIELOV3 AURA

CIELOV3 ELO

CIELOV3 Cartão de Crédito Hipercard HIPERCARD

CIELOV3 Cartão American Express AMEX

CIELOV3 Cartão Diners Club DINERS

CIELOV3 Cartão Discover DISCOVER

CIELOV3 Cartão JCB JCB

CIELOV3 Cartão Maestro MAESTRO

CIELOV3 Cartão Mastercard MASTERCARD

CIELOV3 Cartão Visa VISA

CIELOV3 Cartão Visa Electron VISA_ELECTRON

CIELOV3 Cartão Visa Vpay VPAY

FIRSTDATA_IPG Cartão American Express AMEX

FIRSTDATA_IPG Cartão Cabal CABAL

FIRSTDATA_IPG Cartão ELO ELO

FIRSTDATA_IPG Cartão Hiper HIPER

FIRSTDATA_IPG Cartão Hipercard HIPERCARD

FIRSTDATA_IPG Cartão Maestro MAESTRO

FIRSTDATA_IPG Cartão Mastercard MASTERCARD

FIRSTDATA_IPG Cartão Mastercard Cordobesa MC_CORDOBESA

FIRSTDATA_IPG Cartão Mastercard Débito MASTERCARD_DEBIT

FIRSTDATA_IPG Cartão Sorocred SOROCRED

FIRSTDATA_IPG Cartão Visa VISA

FIRSTDATA_IPG Cartão Visa Débito VISA_DEBIT

FIRSTDATA_IPG Cartão Visa Electron VISA_ELECTRON

GETNET Carte Hipercard HIPERCARD

GETNET Cartão American Express AMEX

GETNET Cartão ELO ELO

GETNET Cartão Maestro MAESTRO

GETNET Cartão Mastercard MASTERCARD

GETNET Cartão Visa VISA



Código Rede Meio de pagamentoTipo de cartões

(vads_payment_cards)Suporta o pagamento

por Token Cartão

GETNET Cartão Visa Electron VISA_ELECTRON

GLOBAL_PAYMENTS Cartão ELO ELO

GLOBAL_PAYMENTS Cartão Hiper HIPER

GLOBAL_PAYMENTS Cartão hipercard HIPERCARD

GLOBAL_PAYMENTS Cartão Mastercard MASTERCARD

GLOBAL_PAYMENTS Cartão Visa VISA

ITAU_IB Boleto Itaú ITAU_BOLETO

ITAU_IB Itaú Internet Banking ITAU_IB

REDE Cartão American Express AMEX

REDE Cartão Diners Club DINERS

REDE Cartão ELO ELO

REDE Cartão Hiper HIPER

REDE Cartão Hipercard HIPERCARD

REDE Cartão JCB JCB

REDE Cartão Maestro MAESTRO

REDE Cartão Mastercard MASTERCARD

REDE Cartão Visa VISA

REDE Cartão Visa Electron VISA_ELECTRON

REDE Cartão Visa Vpay VPAY

STONE Cartão Mastercard MASTERCARD

STONE Cartão Visa VISA



5. O COMPARTILHAMENTO DE TOKEN CARTÃO

Pode-se compartilhar Token Cartões entre diversas entidades jurídicas.

Os Token Cartões compartilhados entre diversas entidades jurídicas devem ser únicos e serobrigatoriamente gerados pela plataforma de pagamento.

No entanto, esta função é submetida a condições particulares. Favor entrar em contato com suaplataforma de pagamento para conhecê-las.



6. GERENCIAR OS TOKEN CARTÕES A PARTIR DO FORMULÁRIODE PAGAMENTO

O formulário de pagamento permite realizar as operações seguintes, apresentadas por caso de uso:

Cada um destes casos corresponde a uma valorização diferente do campo vads_page_action.

Caso de uso Valorização do campo vads_page_action

Criação de um Token Cartão sem pagamento REGISTER

Atualização das informações associadas ao Token Cartão REGISTER_UPDATE

Criação de um Token com pagamento REGISTER_PAY

Criação de um Token Cartão na contratação de uma assinatura REGISTER_SUBSCRIBE

Criação de um Token Cartão na contratação de uma assinatura seguida deum pagamento.

REGISTER_ PAY_SUBSCRIBE

Pagamento por Token Cartão PAYMENT

Uso de um Token Cartão para contratar uma assinatura SUBSCRIBE

Pagamento com proposta ao portador de criar um Token Cartão ASK_ REGISTER_PAY

Atualização das informações associadas ao Token Cartão durante umpagamento.

REGISTER_UPDATE_PAY

Em função do caso de uso (valorização do campo vads_page_action), a cinemática das trocas do ponto devista do comprador será diferente na página de pagamento.



6.1. Criação de um Token Cartão sem pagamento

Este caso corresponde simplesmente à criação de um Token Cartão.

O site de e-commerce envia para a plataforma de pagamento as informações do comprador, eobrigatoriamente o endereço e-mail.

1. O comprador verifica as informações exibidas na página de pagamento.

2. Ele seleciona o meio de pagamento que ele deseja salvar.

A página de pagamento exibe mais uma vez as informações do comprador e pede para digitar asinformações bancárias.

3. Se o comprador selecionou um cartão bancário, ele digita

• o número do cartão,

• o mês de vencimento do cartão,

• o ano de vencimento do cartão,

• o CVV do cartão, se tiver.

4. O comprador clica em Validar.

Se todos os controles do meio de pagamento foram realizados com sucesso, o resumo será exibido.

Contém em particular o Token Cartão recém criado. Este último poderá ser utilizado posteriormentepara realizar uma outra operação bancária.

Pode-se comunicar ao comprador estas diferentes informações por e-mail, e portanto receber:

• a confirmação de que estas informações bancárias foram salvas na plataforma de pagamento daloja,

• seu Token Cartão que ele poderá usar posteriormente para realizar uma outra operação bancária.

Observação:

Para ativar o envio por e-mail destas informações, favor consultar o capítulo Configurar os e-mailsenviados para o comprador.

O processamento de uma solicitação de criação de Token Cartão sem pagamento resulta na criação deuma transação de tipo VERIFICATION (VERIFICAÇÃO), exibida no Back Office Estabelecimento Comerciale com as características seguintes:

• seu valor é de 1.00 BRL,

• ou seu status é "Aceito" (vads_trans_status=ACCEPTED) ou é"Recusado" (vads_trans_status=REFUSED),

• nunca será capturada no banco e permanecerá na aba "Transações em andamento".

Advertência:

O Token Cartão não será criado se a solicitação de autorização for recusada.



6.2. Modificação das informações associadas ao Token Cartão

Corresponde à atualização solicitada pelo comprador das informações vinculadas ao seu meio depagamento e/ou as suas informações pessoais.

O site de e-commerce envia para a plataforma de pagamento:

• as novas informações, particularmente o endereço e-mail, obrigatório

• o Token Cartão a ser atualizado.

As páginas apresentadas são as mesmas que no caso anterior (Criação do Token Cartão sem pagamento).

O processamento de uma solicitação de atualização de um Token Cartão resulta na criação de umatransação de tipo VERIFICATION (VERIFICAÇÃO), exibida no Back Office Estabelecimento Comercial e comas características seguintes:


• seu status é “Aceito” (vads_trans_status=ACCEPTED) ou “Recusado” (vads_trans_status=REFUSED),


Advertência:

O Token Cartão não será atualizado se a solicitação de autorização for recusada.



6.3. Criação de um Token Cartão durante um pagamento

Neste caso, os parâmetros necessários a uma solicitação de pagamento são utilizados para informar osparâmetros necessários à inscrição.


1. O comprador verifica as informações exibidas na página de pagamento (identidade, valor e moeda datransação).

2. Ele seleciona o meio de pagamento que ele deseja salvar e usar.

A página de pagamento exibe:

• para a inscrição:

• as informações sobre a identidade do comprador,

• as informações bancárias digitadas do comprador.

• para o pagamento:

• as informações vinculadas à transação (número de transação, valor...).











• a confirmação do pagamento.

Observação:


Advertência:




6.4. Criação de um Token Cartão na contratação de uma assinatura

Além das informações usadas no caso da Criação do Token Cartão sem pagamento, este caso de uso devetambém comunicar informações vinculadas à assinatura tais como:

• o valor inicial da assinatura (valor utilizado na(s) primeira(s) parcela(s) se ele for diferente (opcional),

• o valor da assinatura (valor das parcelas ou utilizado para as parcelas posteriores quando a primeirafor diferente).


1. O comprador verifica as informações exibidas na página de pagamento (identidade, valores e moedade transação).


A página de pagamento aparece. Contém as informações:




• para a assinatura:

• a quantidade de parcelas,

• o valor por parcela.









Os valores da assinatura são também exibidos no resumo do pagamento quando a verificação donúmero do meio de pagamento (exemplo: cartão bancário) for realizada com sucesso.



• a confirmação que a assinatura foi salva.

Observação:


O processamento de uma solicitação de criação de Token Cartão com contratação de uma assinaturaresulta na criação de uma transação de tipo VERIFICATION, exibida no Back Office EstabelecimentoComercial e com as características seguintes:




• seu status é “Aceito” (vads_trans_status=ACCEPTED) ou “Recusado” (vads_trans_status=REFUSED),


Advertência:




6.5. Criação de um Token Cartão na contratação de uma assinaturaseguida de um pagamento

Este caso de uso deve apresentar informações tais como:

• as informações sobre o comprador,

• o código da transação,

• as informações sobre a assinatura (valores).

Exemplo de uso: uma assinatura de um valor de X BRL/ para X meses com despesas de início de serviçopara pagar na hora do pedido.


1. O comprador verifica as informações exibidas na página de pagamento (identidade, valores e moedade transação).


A página de pagamento aparece. Contém as informações:




• para a assinatura:

• a quantidade de parcelas,

• o valor por parcela.


• o valor das despesas de início de serviço.









Os valores da assinatura bem como as despesas de início de serviço serão também exibidos noresumo do pagamento quando a verificação do número de meio de pagamento (exemplo: cartãobancário) for realizada com sucesso.



• a confirmação que a assinatura foi salva.




Observação:


Advertência:


6.6. Pagamento por Token Cartão

O pagamento por Token Cartão possibilita, a partir de um Token Cartão previamente salvo, realizarpagamentos unitários ou múltiplos sem ter que selecionar um meio de pagamento nem ter que digitardados bancários.

Neste caso, somente haverá uma simples etapa de confirmação com um resumo da transação (númeroe valor).



Uma solicitação de autorização é realizada com o meio de pagamento associado ao Token Cartão. Seesta for realizada com sucesso, o resumo será exibido.



• o detalhe do pagamento.

Observação:


Observação:

Se o Token Cartão estiver associado a um meio de pagamento vencido, a plataforma de pagamentovai propor automaticamente ao comprador digitar os novos dados bancários para realizar opagamento e atualizar o Token Cartão associado a ele.


Pagamento por Token Cartão e Garantia de Pagamento

Por padrão, a transferência de responsabilidade em caso de litígio não pode ser aplicada a um pagamentopor Token Cartão.

Mesmo se uma autenticação 3D Secure foi realizada com sucesso na criação do Token Cartão, ospagamentos realizados com este Token Cartão não são sujeitos automaticamente à transferência deresponsabilidade.

Para que a transferência de responsabilidade seja efetiva, o comprador deve obrigatoriamente digitar oCVV do seu cartão e fazer uma autenticação 3D Secure (ou uma autenticação alta em 3DS2).

Entre em contato o suporte técnico para pedir a ativação desta opções.

Observação

Por padrão (ou seja sem ativar a opção “3D Secure nos pagamentos por Token Cartão”), as informaçõessobre a autenticação 3D Secure (campos vads_threeds_xxxx), são enviadas vazias na resposta, salvo ocampo vads_threeds_exit_status.



6.7. Uso de um Token Cartão para contratar uma assinatura

Uma vez que um Token Cartão for criado, pode-se adicionar uma ou várias assinatura(s) adicional(ais) queutilizarão este Token Cartão.

Quando contratar uma assinatura nova, não precisará digitar nenhum dado bancário. O comprador deveráapenas confirmar.



O resumo da assinatura criada é exibido.



• o detalhe da assinatura.

Observação:


Advertência:




6.8. Pagamento com proposta ao portador de criar um Token Cartão

O comprador pode, na hora do pagamento, memorizar seus dados bancários assinalando a caixacorrespondente. Esta operação, totalmente segura, permite ao comprador facilitar suas futuras compras.


1. O comprador verifica as informações exibidas na página de pagamento (valor e moeda da transação).


A página de pagamento exibe as informações do comprador e pede para digitar as informaçõesbancárias.

O comprador pode selecionar Desejo salvar os dados do meu meio de pagamento para uma futuracompra. Por padrão, esta caixa não está selecionada. Não entanto, o comprador pode memorizarsuas informações bancárias na plataforma de pagamento da loja. As futuras compras dele serãosimplificadas.







Uma vez que os controles sobre o meio de pagamento forem realizados e que a solicitação deautorização for aceita pelo banco, o resumo será exibido com a mensagem:

Sua solicitação de cadastro com pagamento foi salva com sucesso.

Este resumo contém informações relativas ao Token Cartão, que poderá ser utilizado posteriormentepara realizar uma outra operação bancária e para o pagamento.


• a confirmação do pagamento,


Observação:


Advertência:




6.9. Modificação de informações associadas a um Token Cartão duranteum pagamento

Corresponde à atualização, solicitada pelo comprador, das informações vinculadas ao seu meio depagamento e/ou as suas informações pessoais durante um pagamento.


1. O comprador verifica as informações exibidas na página de pagamento (identidade, valor e moeda datransação, seu Token Cartão).

2. Seleciona o meio de pagamento que ele deseja salvar e usar.

A página de pagamento exibe:





• as informações vinculadas à transação (número de transação, valor...).







Se todos os controles do meio de pagamento foram realizados com sucesso, o resumo será exibidocom a mensagem seguinte:

A atualização do seu Token Cartão foi salva e a solicitação de pagamento foi realizada com sucesso.




Observação:


Advertência:

O Token Cartão não será atualizado se a solicitação de autorização for recusada.



7. CICLO DE VIDA DE UM PAGAMENTO RECORRENTE

A assinatura começa na data de vigência.

A plataforma de pagamento irá gerar então os pagamentos segundo o cronograma determinado pela regrade assinatura enviada no formulário de criação da assinatura (campo vads_sub_desc).

Para cada data de pagamento de uma assinatura, se a regra Url de notificação na criação de umaassinatura for ativada e devidamente configurada, o site de e-commerce receberá o resultado dopagamento na sua URL de notificação (IPN).

Se houver falha:

• o Estabelecimento Comercial não será avisado por e-mail,

• o pagamento não será automaticamente apresentado novamente.

Se o meio de pagamento venceu, uma transação recusada será criada sem chamar o banco emissor. Odetalhe do erro (vads_payment_error) tem o valor 8 - A data de vencimento do cartão não autoriza estaação.

Se os dados do meio de pagamento foram apagados após 15 meses sem atividade, uma transação recusadaserá criada sem chamar o banco emissor. O detalhe do erro (vads_payment_error) tem o valor 107 - Omeio de pagamento associado ao Token Cartão não está mais válido.



8. CICLO DE VIDA DE UM PAGAMENTO RECORRENTE COMAUTORIZAÇÃO PRÉVIA

Graças a esta opção, quando um pagamento for recusado por um motivo que não seja relativo à fraude(ver capítulo Lista dos códigos retorno da solicitação de autorização), a plataforma de pagamento poderealizar diariamente e automaticamente uma nova solicitação de autorização até 48 horas antes da dataprevista de captura no banco.

Assim que a opção for ativada na loja, os pagamentos recorrentes serão criados 6 dias antes da dataprevista pela regra da assinatura.

É imprescindível ativar a regra Url de notificação para uma autorização por batch no seu Back OfficeEstabelecimento Comercial (ver capítulo Configurar a notificação em autorização por batch).

D-6: Criação do pagamento recorrente

• A solicitação de autorização é aceita

• O pagamento ficará Aguardando captura até a data prevista inicialmente.

• Uma chamada para a url de notificação será lançada se a regra Url de notificação na criação de umaassinatura for ativada. A solicitação terá os valores seguintes:

Nome do campo Valor

vads_url_check_src REC

vads_trans_status AUTHORISED

• A solicitação de autorização é recusada por um motivo relativo à fraude

• O pagamento é definitivamente Recusado.


Nome do campo Valor


vads_trans_status REFUSED

• A solicitação de autorização é recusada por um motivo não relativo à fraude.

• O pagamento ficará Aguardando autorização.


Nome do campo Valor


vads_trans_status WAITING_AUTHORISATION

D-5, D-4, D-3: Nova solicitação de autorização iniciada automaticamente



• Uma chamada para a url de notificação será lançada se a regra Url de notificação para umaautorização por batch for ativada. Neste caso, a solicitação terá os valores seguintes:

Nome do campo Valor

vads_url_check_src BATCH_AUTO



Nome do campo Valor


• A solicitação de autorização é recusada por um motivo relativo à fraude



Nome do campo Valor



• A solicitação de autorização é recusada por um motivo não relativo à fraude.

• O pagamento ficará Aguardando captura até a data prevista.


Nome do campo Valor


vads_trans_status WAITING_AUTHORISATION

D-2: Última solicitação de autorização iniciada automaticamente




Nome do campo Valor



• A solicitação de autorização é recusada (seja qual for o motivo)



Nome do campo Valor



J: Captura da transação

O pagamento é capturado automaticamente.

Nenhuma chamada para a URL de notificação será lançada.

Observações

• Recusa de um pagamento entre D-6 e D-2

Quando o pagamento é definitivamente recusado, você deve ter certeza que o acesso ao serviço paraqual a assinatura foi contratada seja rescindido na data prevista, e não no dia da recepção da recusado pagamento.



• Rescisão de uma assinatura

Quando o comprador rescinde a assinatura dele, a responsabilidade de rescindir os pagamentos criadospor antecipação (prévios) cabe ao Estabelecimento Comercial.

8.1. Lista dos códigos retorno da solicitação de autorização

Os códigos retorno da solicitação de autorização são retornados pelo banco emissor (se disponível).

Códigos retornados na rede CB:

Valor DescriçãoMotivo

fraudulosoValor Descrição

Motivofrauduloso

00 Transação aprovada ou realizada comsucesso

38 Data de validade do cartão vencida

02 Contatar o emissor do cartão. 41 Cartão perdido SIM

03 Receptor inválido SIM 43 Cartão roubado SIM

04 Guardar o cartão SIM 51 Provisão insuficiente ou limite decrédito excedido

05 Não honrar SIM 54 Data de validade do cartão vencida SIM

07 Guardar o cartão, condições especiais SIM 55 Senha errada

08 Aprovar após identificação 56 Cartão ausente da base SIM

12 Transação inválida SIM 57 Transação interditada para esteportador

SIM

13 Valor inválido SIM 58 Transação interditada para esteportador

14 Número de cartão inválido SIM 59 Suspeita de fraude SIM

15 Emissor de cartão desconhecido SIM 60 O receptor do cartão deve entrar emcontato com o adquirente

17 Cancelamento comprador 61 Valor de saque fora do permitido

19 Repetir a transação posteriormente 63 Regras de segurança não respeitadas SIM

20 Resposta errada (erro no domínio doservidor)

68 Resposta não entregue ou recebidatarde demais

24 Atualização do arquivo não foi possível 75 Quantidade de tentativas senhasexcedidas

25 Não foi possível localizar o registro noarquivo

76 Portador já interditado, antigo registrosalvo

SIM

26 Registro duplicado, antigo registrosubstituído

90 Parada temporária do sistema

27 Erro em "edit" no campo de lista deatualização arquivo

91 Emissor de cartão não alcançável

28 Acesso proibido ao arquivo 94 Transação duplicada

29 Atualização impossível 96 Mau funcionamento do sistema

30 Erro de formato 97 Prazo de tempo limite de segurançaglobal

31 Código do organismo compradorinválido

SIM 98 Servidor indisponívelencaminhamento rede pedidonovamente

33 Data de validade do cartão vencida SIM 99 Incidente domínio iniciador

34 Suspeita de fraude SIM



8.2. Notificação por e-mail quando uma parcela foi recusada

Caso da opção Autorização antecipada

Quando o pagamento for recusado, um e-mail de advertência é enviado para o vendedor.



9. ESTABELECER O DIÁLOGO COM A PLATAFORMA DEPAGAMENTO

O diálogo entre o site de e-commerce e a plataforma de pagamento realiza-se via uma troca de dados.

Para criar um pagamento, estes dados são enviados em um formulário HTML via o navegador docomprador.

No final do pagamento, o resultado será enviado ao site de e-commerce de duas maneiras:

• automaticamente com notificações chamadas URL de notificação instantânea (também chamada IPNpara Instant Payment Notification), ver capítulo Configurar as notificações.

• pelo navegador quando o comprador clica no botão para voltar no site de e-commerce, ver capítuloGerenciar o retorno para ao site de e-commerce.

Para garantir a segurança das trocas, os dados são assinados com uma chave somente conhecida peloEstabelecimento Comercial e pela plataforma de pagamento.

9.1. Similaridades com o pagamento unitário

Todas as funções disponíveis para o pagamento unitário estão também disponíveis para os pagamentospor Token Cartão e por assinatura.

Para maiores informações, consultar Guia de implementação API Formulário

Segue uma lista não exaustiva deste último:

• Pagamento unitário, pagável em uma vez, ou parcelado.

• Gerenciamento de diversas moedas.

• Gerenciamento de diversos meios de pagamento e dos contratos Estabelecimentos Comerciaisassociados.

• Personalização das páginas de pagamentos.

• Exibição em uma iframe.



10. CONFIGURAR AS NOTIFICAÇÕES

Diversos tipos de notificações estão disponíveis no Back Office Estabelecimento Comercial.

• Chamada URL de notificação

• E-mail enviado ao Estabelecimento Comercial

• E-mail enviado ao comprador

• E-mail enviado ao Estabelecimento Comercial

• SMS enviado ao comprador

Eles possibilitam gerenciar os eventos (pagamento aceito, o comprador desistiu da compra, cancelamentopelo Estabelecimento Comercial, validação pelo Estabelecimento Comercial...) que gerará o envio de umanotificação para o site de e-commerce, Estabelecimento Comercial ou para o comprador.

As notificações de tipo Chamada URL de notificação são as mais importantes porque elas representam o único meioconfiável para o site de e-commerce para obter o resultado de um pagamento.

Se a plataforma não conseguir entrar em contato com a URL da sua página, um e-mail será enviado parao endereço e-mail especificado.

Contém:

• O código HTTP do erro encontrado

• Elementos de analise segundo o erro

• As suas conseqüências

• Os passos a seguir a partir do Back Office Estabelecimento Comercial para enviar de novo a solicitaçãopara a URL definida acima.

Para acessar ao gerenciamento das regras de notificação:

Ir para o menu: Configuração > Regras de notificações.



10.1. Configurar a notificação no final do pagamento

Esta regra permite notificar o site de e-commerce nos casos seguintes:

• Pagamento aceito

• Pagamento recusado

• Criação ou atualização de um Token Cartão

• Criação de uma assinatura

Esta notificação é imprescindível para comunicar o resultado de uma solicitação de pagamento, decriação de Token Cartão ou de criação de assinatura.

Ela informará ao site de e-commerce o resultado mesmo se o comprador não clicar em Voltar para a loja.

1. Clique direito na linha URL de notificação no final do pagamento.

2. Selecione Gerenciar a regra.

3. Na seção Configuração geral, preencha o campo Endereço(s) e-mail(s) para avisar em caso de falha.

Para especificar vários endereços e-mails, separe os e-mails por um ponto e vírgula.

4. Assinale a caixa Re-chamada automática em caso de falha se você deseja autorizar a plataforma aenviar de novo automaticamente a notificação em caso de falha, até 4 vezes.

Para maiores informações, consulte o capítulo Re-chamada automática em caso de falha na página34.

5. Na seção URL de notificação do API formulário V1, V2, digite a URL da sua página nos campos URL aser chamada em modo TEST e URL a ser chamada em modo PRODUCTION se você deseja receber asnotificações no formato API Formulário.

6. Na seção URL de notificação do API REST, digite a URL da sua página nos campos URL alvo do IPN aser chamado em modo TESTE e URL alvo do IPN a ser chamado em modo PRODUÇÃO se você usar ocliente JavaScript.

7. Salve suas modificações.



10.2. Configurar a notificação se o comprador desistir ou cancelar


• Em caso de abandono/cancelamento por parte do comprador, com o botão Cancelar e voltar para aloja.

• Quando o comprador não finalizou o pagamento antes do fim da sessão de pagamento.

O tempo máximo de uma sessão de pagamento é de 10 minutos.

Esta regra está desativada por padrão.

1. Clique direito na linha URL de notificação de anulação.









8. Ative a regra, clicando direito em URL de notificação de anulação e selecionando Ativar a regra.



10.3. Configurar a notificação em uma operação procedente do BackOffice

Esta regra permite notificar o site de e-commerce a cada operação realizada no Back OfficeEstabelecimento Comercial :

• Criação de um pagamento manual (aceito ou recusado)

• Modificação de uma transação

• Duplicação de uma transação

• Reembolso de uma transação

• Cancelamento de uma transação

• Validação de uma transação

• Criação de um Token Cartão

• Atualização de um Token Cartão

1. Clique direito na linha Url de notificação para uma operação proveniente do Back Office.









8. Ative a regra, clicando direito em Url de notificação para uma operação proveniente do Back Officee selecionando Ativar a regra.



10.4. Configurar a notificação durante a criação de uma assinatura


• Quando a plataforma cria uma nova parcela de um pagamento recorrente.

• A cada nova tentativa de pagamento, após que uma parcela de um pagamento recorrente foi recusada.

Requer ativar a opção de autorização antecipada.


1. Clique direito na linha Url de notificação na criação de uma assinatura.







7. Ative a regra, com um clique direito em Url de notificação na criação de uma assinatura e selecioneAtivar a regra.



10.5. Configure a notificação em autorização por batch

Se a loja possuir a opção Autorização prévia, é preciso ativar a regra Url de notificação para umaautorização por batch para receber o resultado final do pagamento.


1. Clique direito na linha Url de notificação para uma autorização por batch.









8. Ative a regra, clicando direito em Url de notificação para uma autorização por batch e selecionandoAtivar a regra.



10.6. Re-chamada automática em caso de falha

A re-chamada automática não se aplica às notificações enviadas manualmente a partir do Back OfficeEstabelecimento Comercial.

O Estabelecimento Comercial pode ativar um mecanismo que permite à plataforma enviar de novoautomaticamente as notificações quando o site de e-commerce encontra-se indisponível, até 4 vezes.

Uma autenticação será considerada em falha se o código de retorno HTTP retornado pelo site de e-commerce não constar na lista seguinte: 200,201, 202, 203, 204, 205, 206, 301, 302,303, 307, 308.

As tentativas de chamadas são programadas a horários fixos a cada 15 minutos (00, 15, 30, 45).

Após cada tentativa sem sucesso, um e-mail de alerta é enviado ao endereço especificado na configuraçãoda regra de notificação em questão.

O título do e-mail de aviso apresenta o número da tentativa de envio da notificação. Ele é apresentadosob a forma attempt # seguido do número de tentativa.

• Exemplo de título de um e-mail recebido após a primeira falha de notificação no final de um pagamento:

[MODE TEST] Minha loja - Tr. ref. 067925 / FALHA durante a chamada da sua URL de notificação [unsuccessful attempt #1]

• Exemplo de título de e-mail recebido após uma segunda falha:


• Exemplo de título de e-mail recebido após uma terceira falha:


• Exemplo de título de e-mail recebido após a última tentativa:

[MODE TEST] Minha loja - Tr. ref. 067925 / FALHA durante a chamada da sua URL de notificação [unsuccessful attempt #last]

Para notificar ao site de e-commerce a falha da última tentativa de notificação, o título do e-mailapresentará a menção attempt #last.

Durante a re-chamada automática, algumas informações não são registradas no banco de dados ou sãomodificadas.

Exemplos de campos não disponíveis / não salvos em banco de dados:

Nome do campo Descrição

vads_page_action Operação realizada

vads_payment_config Tipologia de pagamento (à vista ou parcelado)

vads_action_mode Modo de aquisição dos dados do meio de pagamento

Exemplos de campos enviados com valores diferentes:

Nome do campo Novo valor

vads_url_check_src Sempre com o valor de RETRY para uma re-chamada automática.

vads_trans_status O status da transação pode variar entre a chamada inicial e a re-chamadaautomática (cancelamento do Estabelecimento Comercial, captura no banco datransação, etc.).

vads_hash O valor deste campo é gerado de novo a cada chamada.



Nome do campo Novo valor

signature O valor da assinatura depende dos diferentes status que podem variar entre achamada inicial e a re-chamada automática.

Estes e-mails apresentam em detalhes:

• o problema encontrado

• elementos de análise em função do erro

• as suas consequências

• os passos a seguir a partir do Back Office Estabelecimento Comercial para enviar manualmente anotificação.

Observação:

Após a quarta tentativa, pode-se também chamar de novo a URL de notificação manualmente no seu BackOffice Estabelecimento Comercial.

Atenção, durante a re-chamada automática, toda chamada manual para a URL de notificação vai afetar onúmero de tentativas automáticas:

• uma chamada manual realizada com sucesso encerra a re-chamada automática

• um chamada manual em falha não terá impacto na re-chamada automática em andamento.



10.7. Configurar os e-mails enviados para o comprador

Na aba E-mail enviado ao comprador:

1. Clique direito na regra que quer modificar e selecione Ativar a regra.

2. Clique direito de novo na regra e selecione Gerenciar a regra.

O assistente de gerenciamento de regra de notificação abre.

3. Na seção Configuração geral, você pode personalizar a denominação da regra.

4. Para personalizar o conteúdo de e-mail:

a. Clique em Configuração e-mail comprador.

b. Selecione o modelo de e-mail para aplicar.

c. Selecione o idioma que você quer modificar.

d. Clique no link Personalizar valores de texto por padrão se você desejar modificar o assunto e oconteúdo do e-mail “por padrão”.

e. Clique em Campos para incluir para exibir a lista dos campos disponíveis para personalizar o e-mail.

f. Selecione os campos que você deseja incluir. Um recapitulativo detalhado do tratamento dasolicitação será acrescentado ao conteúdo do e-mail.

5. Para modificar os eventos que inciam a notificação:

a. Clique na aba Condições da regra

Uma condição é constituída de uma variável, de um operador de comparação e de um valor dereferência.

Exemplo: "modo = TESTE", "valor superior a 1000". Quando uma regra for executada, o valor davariável é resgatado e comparado com o valor de referência.

b. Clique duas vezes em uma condição existente para modificá-la.

c. Clique em Adicionar para criar uma nova condição.

Todas as condições devem ser validadas para que a regra seja executada.

6. Clique em Salvar.



11. CRIAR UM FORMULÁRIO DE PAGAMENTO

Para criar uma solicitação de pagamento, você deve montar um formulário html da seguinte forma:

<form method="POST" ação="https://secure.payzen.com.br/vads-payment/"> <input type="hidden" name="parametre1" value="valor1" /> <input type="hidden" name="parametre2" value="valor2" /> <input type="hidden" name="parametre3" value="valor3" /> <input type="hidden" name="assinatura" value="signature"/> <input type="submit" name="pagar" value="Pagar"/></form>

Contém:

Os elementos técnicos seguintes:

• Os tags <form> e </form> que permitem criar um formulário HTML.

• O atributo method="POST" que especifica o método usado para enviar os dados.

• O atributo action="https://secure.payzen.com.br/vads-payment/" que especifica onde enviar os dadosdo formulário.

Os dados do formulário:

• O código da loja.

• As características do pagamento em função do caso de uso.

• As informações complementares em função das suas necessidades.

• A assinatura que garante a integridade do formulário.

Estes dados são acrescentados ao formulário usando o tag <input> :

<input type="hidden" name="parametro1" value="valor1" />

Para valorizar os atributos name e value, ver o Dicionário de dados disponível em nosso website.

Todos os dados do formulário devem ser codificados em UTF-8.

Os símbolos especiais (acentos, pontuação etc...) serão assim devidamente interpretados pela plataformade pagamento. Caso contrário, o cálculo de assinatura estará errado e o formulário será recusado.

O botão Pagar que vai permitir o envio dos dados:

<input type="submit" name="pagar" value="Pagar"/>

https://secure.payzen.com.br/vads-payment/




Alguns casos de uso são apresentados nos capítulos seguintes. Eles permitem montar um formulário depagamento segundo suas necessidades.

O quadro a seguir apresenta os diferentes formatos que você poderá encontrar quando montar seuformulário.

Notação Descrição

a Símbolos alfabéticos (de "A" a "Z" e de "a" a "z")

n Símbolos numéricos

s Símbolos especiais

an Símbolos alfanuméricos

ans Símbolos alfanuméricos e especiais (com exceção de "<" e ">")

3 Comprimento fixo até 3 símbolos

..12 Comprimento variável até 12 símbolos

json JavaScript Object Notation.Objeto contendo pares de chave/valor separados por uma virgula.Começa por uma chaveta esquerda " { e acaba com uma chaveta direita " } ".Todo par chave/valor contém o nome da chave entre aspas duplas seguido por " :", seguido por um valor.O nome da chave deve ser alfanumérico.O valor pode ser:

• Um string de caracteres (neste caso ele deve ficar entre aspas duplas)

• um número

• um objeto

• um quadro

• um booliano

• Vazio

Exemplo: {"name1":45,"name2":"value2", "name3":false}

enum Caracteriza um campo que possui um número infinito de valores.A lista dos valores possíveis é dada na definição do campo.

Lista de enum Lista de valores separados por um " ; ".A lista dos valores possíveis é dada na definição do campo.Exemplo: vads_payment_cards=VISA;MASTERCARD

map Lista de pares chave/valor separados por um " ; ".Todo par chave/valor contém o nome da chave seguido por " = ", seguido por um valor.O valor pode ser:

• um string de caracteres

• um booliano

• um objeto json

• um objeto xml

A lista dos valores possíveis para cada par de chave/valor é dada na definição do campo.Exemplo: vads_theme_config=SIMPLIFIED_DISPLAY=true;RESPONSIVE_MODEL=Model_1



11.1. Criar um formulário "Criação do Token Cartão sem pagamentos"

Caso de uso: criação de um Token Cartão para realizar pagamentos rápidos posteriormente.

1. Informar a totalidade dos campos presentes no quadro que segue para montar seu formulário depagamento.

Nome do campo Descrição Formato Valor

vads_page_action Ação a ser realizada. enum REGISTER

vads_ctx_mode Modo de funcionamento. enum TEST ou PRODUCTION

vads_cust_email Endereço e-mail do comprador. ans..150 Ex: [email protected]

vads_action_mode Modo de aquisição dos dados do meio depagamento.

enumINTERACTIVE

vads_site_id Código de identificação da loja. n8 Ex: 12345678

vads_trans_date Data e hora UTC do formulário de pagamento. n14 Ex: 20190501130025

vads_version Versão do protocolo de troca. string V2

2. Use o campo vads_identifier se você desejar gerar o código do Token associado ao meio depagamento.

O formato do token não pode ser an..32. Este formato é reservado aos Tokens gerados pelaplataforma de pagamento.

3. Adicione os campos opcionais em função das suas necessidades (ver capítulo Usar funçõescomplementares ).

4. Calcular o valor do campo signature usando a totalidade dos campos do seu formulário, com o nomecomeçando por vads_ (ver capítulo Calcular a assinatura).

11.2. Criar um formulário “Modificação das informações associadas aoToken Cartão”

Caso de uso: atualização das informações bancárias associadas a um Token Cartão.



vads_page_action Ação a ser realizada. enum REGISTER_UPDATE




enumINTERACTIVE

vads_identifier Token Cartão (único) associado a um meio depagamento.

ans..50

Ex: MeuTokenCartãoObservação: Dois formatospossíveis:

• an32 : quando o código forgerado pela plataforma

• ans..50 : quando o código forgerado pelo EstabelecimentoComercial.






11.3. Criar um formulário "Criação do Token Cartão durante umpagamento"

Caso de uso: pagamento com criação de um Token Cartão.



vads_page_action Ação a ser realizada. enum REGISTER_PAY

vads_amount Valor do pagamento (na sua menor unidademonetária).

n..12Ex: 3000 para 30,00 BRL


vads_currency Código da moeda usada para o pagamento.n3

Ex: 986 para o Real do Brasil(BRL)



enumINTERACTIVE

vads_payment_config Tipo de pagamento. enum SINGLE



vads_trans_id Código único de uma transação. n6 Ex: 123456








11.4. Criar um formulário “Criação de um Token Cartão na contrataçãode uma assinatura”

Caso de uso: contratação de uma assinatura com criação de um Token Cartão.

IMPORTANTE

Nenhum pagamento será realizado durante a contratação. Somente uma solicitação de verificação será realizada paravalidar os dados do meio de pagamento.

O primeiro pagamento será realizado uma vez que a data de efeito for atingida, entre 00h00 e 05h00.

Se você desejar que o comprador faça um primeiro pagamento na hora da contratação, consulte o capítulo seguinte: Criarum formulário “Criação de um Token Cartão na contratação de uma assinatura seguida de um pagamento” na página44.



vads_page_action Ação a ser realizada. enum REGISTER_SUBSCRIBE



vads_action_ mode Modo de aquisição dos dados domeio de pagamento.

enumINTERACTIVE


vads_sub_amount Valor das parcelas da assinatura(na sua menor unidade monetária).

n..12 Ex: 3000 para 30,00 BRL

vads_sub_effect_date Data de início da assinatura.n8

Cuidado, esta data não pode ser anterior à datavigente.Ex: 20210601

vads_sub_currency Código da moeda usada para aassinatura.

n3Ex: 986 para o Real do Brasil (BRL)

vads_sub_desc Regra de recorrência a ser aplicadasegundo a especificação iCalendarRFC5545.

string A frequência da assinatura pode ser diária,semanal ou mensal.Pode-se especificar o número do dia ou do mês(por exemplo “10 do mês”, “cada 3 meses”).Observação: o string não deve conter espaço.Exemplos:

• Para definir uma assinatura todas assemanas:

RRULE:FREQ=WEEKLY

• Para definir uma assinatura a cada duassemanas, hoje e a cada 7 dias:

RRULE:FREQ=WEEKLY;INTERVAL=2

• Para definir parcelas de pagamento queocorrem o último dia de cada mês, durante12 meses:

RRULE:FREQ=MONTHLY;BYMONTHDAY=28,29,30,31;BYSETPOS=-1;COUNT=12

• Para definir parcelas de pagamento no dia10 de todo mês, durante 12 meses:

RRULE:FREQ=MONTHLY;COUNT=12;BYMONTHDAY=10

vads_trans_date Data e hora UTC do formulário depagamento.

n14Ex: 20190501130025





Observação:

O valor de vads_sub_effect_date não pode ter uma data vencida.







11.5. Criar um formulário “Criação de um Token Cartão na contrataçãode uma assinatura seguida de um pagamento”

Caso de uso: pagamento e contratação de uma assinatura com criação de um Token Cartão.



vads_page_action Ação a ser realizada. enum REGISTER_PAY_SUBSCRIBE

vads_amount Valor do pagamento (na sua menorunidade monetária).

n..12 Ex: 3000 para 30,00 BRL


vads_currency Código da moeda usada para opagamento.



vads_action_mode Modo de aquisição dos dados domeio de pagamento.

enumINTERACTIVE




n..12Ex: 3000 para 30,00 BRL

vads_sub_currency Código da moeda usada para aassinatura.



string

A frequência da assinatura pode ser diária,semanal ou mensal.Pode-se especificar o número do dia ou do mês(por exemplo “10 do mês”, “cada 3 meses”).Observação: o string não deve conter espaço.Exemplos:


RRULE:FREQ=WEEKLY







vads_sub_effect_date Data de início da assinatura. n8 Ex: 20210601


n14Ex: 20190501130025



Observação:



11.6. Criar um formulário "Pagamento por Token Cartão "

Caso de uso: pagamento em um clique (utilização de um Token Cartão existente e válido).



vads_page_action Ação a ser realizada. enum PAYMENT


n..12 Ex: 3000 para 30,00 BRL


vads_currency Código da moeda usada para o pagamento. n3 Ex: 986 para o Real do Brasil (BRL)


enumINTERACTIVE

vads_identifier Token Cartão (único) associado a um meiode pagamento.

ans..50

Ex: MeuTokenCartãoObservação: Dois formatos possíveis:






n14Ex: 20190501130025







11.7. Criar um formulário “Uso de um Token Cartão para contratar umaassinatura”

Caso de uso: utilização de um Token Cartão existente e válido para contratar uma assinatura.

IMPORTANTE

Nenhum pagamento será realizado durante a contratação.

O primeiro pagamento será realizado uma vez que a data de efeito for atingida, entre 00h00 e 05h00.



vads_page_action Ação a ser realizada. enum SUBSCRIBE


vads_action_mode Modo de aquisição dos dados domeio de pagamento.

enumINTERACTIVE

vads_identifier Token Cartão (único) associado aum meio de pagamento.

ans..50

Ex: MeuTokenCartãoObservação: Dois formatos possíveis:

• an32 : quando o código for gerado pelaplataforma

• ans..50 : quando o código for gerado peloEstabelecimento Comercial.



n..12 Ex: 3000 para 30,00 BRL

vads_sub_effect_date Data de início da assinatura. n8 Ex: 20210601

vads_sub_currency Código da moeda utilizada para aassinatura.



string A frequência da assinatura pode ser diária,semanal ou mensal.Pode-se especificar o número do dia ou do mês(por exemplo “10 do mês”, “cada 3 meses”).Observação: o string não deve conter espaço.Exemplos:


RRULE:FREQ=WEEKLY











n14Ex: 20190501130025


Observação:






11.8. Criar um formulário “Pagamento com proposta ao portador decriação de Token Cartão”

Caso de uso: propor a criação de um Token Cartão durante um pagamento.



vads_page_action Ação a ser realizada. enum ASK_REGISTER_PAY


n..12Ex: 3000 para 30,00 BRL





enumINTERACTIVE












11.9. Criar um formulário “Modificação de informações associadas a umToken Cartão durante um pagamento”

Caso de uso: atualização do Token Cartão durante um pagamento efetuado com um cartão vencido.



vads_page_action Ação a ser realizada. enum REGISTER_UPDATE_PAY




enumINTERACTIVE

vads_identifier Token Cartão (único) associado a um meio depagamento.

string

Ex: MeuTokenCartãoObservação: Dois formatospossíveis:




n..12Ex: 3000 para 30,00 BRL










12. USAR FUNÇÕES COMPLEMENTARES

Para ter um formulário personalizado e adaptado as suas necessidades, você pode usar funçõescomplementares dentre da lista abaixo:

IMPORTANTEOutras funcionalidades úteis estão apresentadas no Guia de implementação API Formulário.

• Definir a moeda para criar ou a atualizar um Token Cartão

• Definir um valor diferente para as x primeiras parcelas

Estas funcionalidades são apresentadas nos capítulos seguintes. Estes capítulos vão ajudar a montar semdificuldades seu formulário de pagamento.



12.1. Definir um valor diferente para as x primeiras parcelas

Você deseja definir uma assinatura cuja(s) primeira(s) parcela(s) possui um valor diferente das parcelasvalorizadas pelo campo vads_sub_amount.

Exemplo: para definir uma assinatura cujas 3 primeiras parcelas são de 25,00 BRL, e o resto das parcelasde 30,00 BRL:

Para isso:

1. Preencher a totalidade dos campos necessários a seu caso de uso para montar seu formulário depagamento.

2. Preencher os campos seguintes:

Nome do campo Descrição Valor

vads_sub_init_amount_number Quantidade de parcelas nas quais será aplicado ovalor definido por vads_sub_init_amount

3

vads_sub_init_amount Valor das primeiras parcelas. A quantidadedas primeiras parcelas é definido porvads_sub_init_amount_number.

2500

vads_sub_amount Valor das parcelas da assinatura salvo as que podemser definidas por vads_sub_init_amount_number

3000

vads_sub_currency Moeda usada para todas as parcelas da assinatura Ex: 986 para o Real do Brasil(BRL)

Observações:

• Os campos vads_sub_init_amount e vads_sub_amount não podem ter o valor de 0.

• Para definir uma assinatura cujos 3 primeiros meses são gratuitos, basta prorrogar a data de vigência(vads_sub_effect_date) de 3 meses.

Exemplo de formulário de pagamento:

<form method="POST" action="https://secure.payzen.com.br/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_capture_delay" value="0" /> <input type="hidden" name="vads_ctx_mode" value="TEST" /> <input type="hidden" name="vads_currency" value="978" /> <input type="hidden" name="vads_cust_country" value="FR" /> <input type="hidden" name="vads_cust_email" value="[email protected]" /><input type="hidden" name="vads_cust_first_name" value="Paul" /> <input type="hidden" name="vads_cust_last_name" value="Juve" /> <input type="hidden" name="vads_cust_title" value="M." /> <input type="hidden" name="vads_page_action" value="REGISTER_SUBSCRIBE" /> <input type="hidden" name="vads_payment_config" value="SINGLE" /> <input type="hidden" name="vads_site_id" value="91335531" /> <input type="hidden" name="vads_trans_date" value="20190716080441" /> <input type="hidden" name="vads_trans_id" value="362812" /> <input type="hidden" name="vads_validation_mode" value="0" /> <input type="hidden" name="vads_sub_currency" value="986" /> <input type="hidden" name="vads_sub_init_amount_number" value="3" /> <input type="hidden" name="vads_sub_init_amount" value="2500" /> <input type="hidden" name="vads_sub_amount" value="3000" /> <input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="G6oZchxNT+ySm7YQ/zvQvfgxmOmubvZ0lPwFKKVUSyI="/><input type="submit" name="pagar" value="Pagar"/></form>

12.2. Definir a moeda para criar ou a atualizar um Token Cartão

Se:

• você possuir um contrato que suporta mais de uma moeda,




• você possuir mais de uma loja,

• suas lojas forem associadas ao mesmo contrato,

• cada loja gerar pagamentos em uma moeda diferente,

(ex : US dólar para a primeira loja, Euro para a segunda)

pode-se que a moeda usada para criar ou atualizar um Token Cartão não seja suportada pela loja.

De fato, a plataforma de pagamento seleciona por padrão a primeira moeda encontrada por ordemalfabética para realizar as verificações necessárias junto ao emissor do meio de pagamento.

Para evitar erros de tratamento de IPN, você pode enviar a moeda que deve ser usada via o formulário.

Observação:

Você poderá mesmo assim usar o Token Cartão para realizar pagamentos em qualquer moeda suportadapelo contrato.


vads_currency Código numérico da moeda aser usada para o pagamento,segundo a norma ISO 4217 (códigonumérico)

n3

Ex: 986 para o Real do Brasil (BRL)



13. CALCULAR A ASSINATURA

Para calcular a assinatura, você deve ter:

• todos os campos com o nome começando por vads_

• o tipo de algoritmo escolhido na configuração da loja

• da chave

O valor da chave está disponível no seu Back Office Estabelecimento Comercial no menu Configuração >Loja > aba Chaves.

O tipo de algoritmo é definido no seu Back Office Estabelecimento Comercial no menu Configuração >Loja > aba Configuração.

Para um segurança máxima, recomendamos usar o algoritmo HMAC-SHA-256 bem como uma chavealfanumérica.

O uso do algoritmo SHA-1 é desvalorizado mas mantido por razões de compatibilidade.

Para calcular a assinatura:

1. Classificar por ordem alfabética todos os campos com o nome começando por vads_ .

2. Garanta que todos os campos sejam codificados em UTF-8.

3. Separe os valores dos campos com o símbolo "+".

4. Concatene o resultado com a chave de teste ou de produção, separando-os com o símbolo "+".

5. Conforme o algoritmo definido na configuração da sua loja:

a. Se sua loja estiver configurada para usar “SHA-1”, aplique a função hash SHA-1 no string obtido naetapa anterior. Desvalorizado.

b. Se sua loja estiver configurada para usar "HMAC-SHA-256", calcule e codifique no formato Base64a assinatura da mensagem usando o algoritmo HMAC-SHA-256 com os parâmetros seguintes:

• a função hash SHA-256,

• a chave de teste ou de produção (em função do valor do campo vads_ctx_mode) como chavecompartilhada,

• O resultado da etapa anterior como mensagem para ser autenticada.

6. Salve o resultado da etapa anterior no campo signature.



Exemplos de parâmetros enviados para a plataforma de pagamento:

<form method="POST" action="https://secure.payzen.com.br/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /><input type="hidden" name="vads_amount" value="5124" /><input type="hidden" name="vads_ctx_mode" value="TEST" /><input type="hidden" name="vads_currency" value="986" /> <input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /><input type="hidden" name="vads_site_id" value="12345678" /><input type="hidden" name="vads_trans_date" value="20170129130025" /><input type="hidden" name="vads_trans_id" value="123456" /><input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="95934ce8678c9e3305f93134054143bd209972dd"/> <input type="submit" name="pagar" value="Pagar"/></form>

Este exemplo de formulário se entende da maneira seguinte:

1. Classificar por ordem alfabética todos os campos com o nome começando por vads_ :

• vads_action_mode

• vads_amount

• vads_ctx_mode

• vads_currency

• vads_page_action

• vads_payment_config

• vads_site_id

• vads_trans_date

• vads_trans_id

• vads_version

2. Concatene o valor dos campos com o símbolo "+" :

INTERACTIVE+5124+TEST+986+PAYMENT+SINGLE+12345678+20170129130025+123456+V2

3. Acrescente o valor da chave de teste no final do string separando com o símbolo "+"). Neste exemplo,a chave de teste é 1122334455667788

INTERACTIVE+5124+TEST+986+PAYMENT+SINGLE+12345678+20170129130025+123456+V2+1122334455667788

4. Se você usar o algoritmo SHA-1, aplique ele no string obtido.

O resultado para ser enviado no campo de assinatura é :95934ce8678c9e3305f93134054143bd209972dd

5. Se sua loja estiver configurada para usar "HMAC-SHA-256", calcule e codifique no formato Base64 aassinatura da mensagem usando o algoritmo HMAC-SHA-256 com os parâmetros seguintes:




O resultado a ser enviado no campo assinatura é:

6yRacR+27j4ufafWL/uafpA9YBUCOukOguC0ny2bm74=




14. ENVIAR A SOLICITAÇÃO DE PAGAMENTO

Para cada transação, o comprador deve ser redirecionado para a página de pagamento para finalizar opagamento.

O navegador dele deve enviar os dados do formulário de pagamento.

14.1. Redirecionar o comprador para a página de pagamento

A URL da plataforma de pagamento é a seguinte:


Exemplos de parâmetros enviados para a plataforma de pagamento:

<form method="POST" action="https://secure.payzen.com.br/vads-payment/"><input type="hidden" name="vads_action_mode" value="INTERACTIVE" /> <input type="hidden" name="vads_amount" value="2990" /> <input type="hidden" name="vads_ctx_mode" value="TEST" /> <input type="hidden" name="vads_currency" value="986" /><input type="hidden" name="vads_cust_country" value="BR" /><input type="hidden" name="vads_cust_email" value="[email protected]" /><input type="hidden" name="vads_order_id" value="CMD012859" /><input type="hidden" name="vads_page_action" value="PAYMENT" /><input type="hidden" name="vads_payment_config" value="SINGLE" /> <input type="hidden" name="vads_site_id" value="12345678" /> <input type="hidden" name="vads_trans_date" value="20200426101407" /> <input type="hidden" name="vads_trans_id" value="362812" /> <input type="hidden" name="vads_version" value="V2" /><input type="hidden" name="signature" value="NM25DPLKEbtGEHCDHn8MBT4ki6aJI/ODaWhCzCnAfvY="/><input type="submit" name="pagar" value="Pagar"/></form>

14.2. Gerenciar os erros

Se a plataforma detectar uma anomalia quando recebe o formulário, uma mensagem de erro apareceráe o comprador não poderá efetuar o pagamento.

Em modo de TESTE

A mensagem menciona a origem do erro e disponibiliza um link para consultar a descrição do código deerro, que ajudará você a identificar as razões possíveis.

Em modo de PRODUÇÃO

A mensagem avisa ao comprador que um problema técnico ocorreu.

Em ambos os casos, o estabelecimento recebe um e-mail de alerta.

Contém:

• a origem do erro,

• um link para consultar as razões possíveis para este código de erro, com o intuito de facilitar odiagnóstico,

• todos os campos presentes no formulário.

Uma descrição dos códigos de erro com suas razões possíveis está disponível em nosso site.

https://payzen.io/pt-BR/error-code/error-00.html



https://payzen.io/pt-BR/error-code/error-00.html



Outras mensagens podem ser enviadas durante o pagamento.

Segue uma lista das mensagens mais freqüentes:

Mensagem Descrição

Sua solicitação de pagamento foi recusado pelo seu banco.

• O banco do comprador recusou a solicitação deautorização ou de informação.

• As regras de gerenciamento de risco causaram a recusada transação.

Sua solicitação de inscrição foi recusada pelo seu banco. • O banco do comprador recusou a solicitação deautorização ou de informação.

• As regras de gerenciamento de risco causaram a recusada transação.

Esta ordem de pagamento está vencida. Favor entrar emcontato com sua loja

O comprador clicou no link de pagamento após a data devencimento da ordem.

Esta ordem de pagamento já foi paga.O comprador clicou de novo no link de pagamento após terrealizado o pagamento.

Uma falha ocorreu ao solicitar o pagamento, o site de e-commerce foi informado que a transação não pode serfinalizada.

O formulário de pagamento foi recusado. O responsável daloja recebeu um e-mail com os detalhes sobre a origem dafalha.

A transação não foi realizada

O site de e-commerce envia um código de transação já usadoem uma outra trancação (aceita ou recusada). O códigode transação deve ser único num mesmo dia (00:00:00 até23:59:59 UTC).

Sintamos muito, você foi desconectado devido a um tempode inatividade longo demais.

• O comprador tenta validar o número de cartão dele, massua sessão de pagamento já expirou. O tempo de sessão éde 10 minutos.

• O site de e-commerce envia um código de transaçãojá utilizado mas que não resultou em uma transação(pagamento abandonado por exemplo). O código detransação deve ser único num mesmo dia (00:00:00 até23:59:59 UTC).

Os cookies estão bloqueados pelo seu navegador. Favorautorizar os cookies antes de reiniciar a operação.

O comprador desativou o uso dos cookies pelo seunavegador. Os cookies são imprescindíveis ao funcionamentodo pagamento.



14.3. Gerenciar os timeout

Noção de sessão de pagamento

Uma "sessão de pagamento" corresponde ao tempo passado pelo comprador na página de pagamento.

A sessão de pagamento inicia assim que a plataforma de pagamento recebe o formulário.

A duração da sessão é de 10 minutos (salvo exceção para alguns meios de pagamento).

Esta duração é:

• suficiente para que todo comprador possa realizar seu pagamento.

• fixa: não é zerada quando o usuário fizer um ação

• inalterável: determinada pela plataforma de pagamento para atender requisitos técnicos.

Após este prazo, a sessão vence e os dados de sessão são apagados.

Vencimento da sessão de pagamento

Em certos casos, a sessão de pagamento vence a pesar do comprador não ter finalizado seu pagamento.

Casos mais frequentes:

1. Uma vez redirecionado para a página de pagamento, o comprador pode dar-se conta de que esta, porexemplo, na hora de ir almoçar.

Uma hora mais tarde, ele decide retomar o pagamento e clica no ícone do seu meio de pagamento.

Como sua sessão de pagamento venceu, a plataforma de pagamento exibe uma mensagem de erronotificando que ele foi desconecto por ultrapassar o tempo de inatividade autorizado.

O comprador pode então clicar no botão para voltar para o site de e-commerce.

Volte para a loja com a URL especificada pelo Estabelecimento Comercial:

• no campo vads_url_return enviado no formulário de pagamento,

• no campo “URL da loja” do Back Office Estabelecimento Comercial, se a URL não foi especificada nocampo vads_url_return do formulário de pagamento.

2. Uma vez que voltou na página de pagamento, o comprador fecha seu navegador (por engano ouporque não quer mais realizar o pagamento).

Notificação quando a sessão venceu

O site de e-commerce pode receber uma notificação quando uma sessão vencer.

Para isso o Estabelecimento Comercial deve configurar e ativar a regra URL de notificação de anulação(ver capítulo Configurar a notificação se o comprador desistir ou cancelar na página 30).



15. IMPLEMENTAR A IPN

O script deve conter pelo menos as etapas a seguir:

• Recuperar a lista dos campos presentes na resposta enviada em POST

• Calcular a assinatura levando em conta os dados recebidos

• Comparar a assinatura calculada com a assinatura recebida

• Analisar a natureza da notificação

• Recuperar o resultado do pagamento

O script pode por exemplo testar o status do pedido (ou a informação da sua escolha) para verificar quenão tenha sido atualizada já.

Uma vez que estas etapas foram realizadas, o script pode atualizar a base de dados (novo status do pedido,atualização do estoque, informações salvas do pagamento etc.).

Para facilitar o suporte e o diagnóstico pelo Estabelecimento Comercial em caso de erro de umanotificação, recomendamos escrever as mensagens que mostrarão quando o erro ocorreu.

A plataforma lê e armazena os primeiros 256 bytes do corpo da resposta HTTP.

Você pode escrever mensagens durante o processamento. Segue um exemplo de mensagem que vocêpode usar:

Mensagem Caso de uso

Data received Mensagem para exibir quando recuperar dados.Permite confirmar que a notificação foi de fato recebida pelosite de e-commerce.

POST is empty Mensagem para exibir quando recuperar dados.Permite destacar um eventual redirecionamento que teriacausado a perda dos parâmetros enviados pela plataforma depagamento.

An error occurred while computing the signature. Mensagem para exibir quando a verificação da assinatura daresposta falhou.

Order successfully updated. Mensagem para exibir no final do arquivo uma vez que vocêrealizou seus tratamentos com sucesso.

An error occurred while updating the order. Mensagem para exibir no final do arquivo se um erro ocorreudurante seus tratamentos.



15.1. Preparar seu ambiente

As notificações de tipo Chamada URL de notificação são as mais importantes porque elas representam o único meioconfiável para o site de e-commerce para obter o resultado de um pagamento.

É portanto primordial certificar-se do bom funcionamento das notificações.

Seguem algumas recomendações:

• Para que o diálogo entre a plataforma de pagamento e seu site de e-commerce funcione, você devecertificar-se com seu pessoal técnico de que a faixa de endereço IP 194.50.38.0/24 esteja autorizadanos diferentes dispositivos da sua arquitetura (firewalls, servidor apache, servidor proxy, etc.).

As notificações são enviadas a partir de um endereço IP que consta na faixa 194.50.38.0/24 em modode Teste e em modo de Produção.

• Os redirecionamentos provocam a perda de dados presentes no POST.

É o caso se existe uma configuração nos seus dispositivos ou seu serviço de hospedagem que redirecionaos URL de tipo "http://www.example.com" para "http://example.com" ou "http://example.com" para"https://example.com".

• A página não deve conter exibições HTML. Acessar recursos como imagens ou folhas de estilo diminuema velocidade das trocas entre a plataforma de pagamento e o site de e-commerce.

• Evite o quanto puder neste script integrar tarefas que necessitam tempo tal como gerar uma faturaPDF ou enviar e-mail.

O tempo de processamento impacta diretamente o prazo para a visualização da página de resumo dopagamento.

Quanto mais o tratamento demorar, mais longo o tempo de espera antes de visualizar. Após 35s, aplataforma considera que a chamada falhou (timeout).

• Se sua página for somente acessível em https, teste sua URL no site deQualys SSL Labs (https://www.ssllabs.com/ssltest/ e modifique sua configuração se for necessário para obterum grade A.

Seu certificado SSL deve ser assinado por uma autoridade de certificação idônea no mercado.

• Certifique-se que está usando as últimas versões do protocolo TLS para manter um alto nível desegurança.

https://www.ssllabs.com/ssltest/




15.2. Recuperar os dados devolvidos na resposta

Os dados retornados na resposta dependem dos parâmetros enviados no formulário de pagamento, dotipo de pagamento efetuado, das opções da sua loja e do formato da notificação.

Os dados são sempre enviados em POST para a plataforma de pagamento.

O primeiro passo consiste em recuperar o conteúdo recebido em modo POST.

Exemplos:

• Em PHP, os dados serão armazenados na superglobal $_POST.

• Em ASP.NET (C#), você deve usar a propriedade Form da classe HttpRequest.

• Em Java, você deve usar o método getParameter da interface HttpServletRequest.

A resposta é constituída de uma lista de campos. Cada campo contém um valor resposta. A lista de campospode chegar a mudar.

O script deverá realizar uma volta para recuperar a totalidade dos campos enviados.

Recomendamos testar a presença do campo vads_hash, presente somente em uma notificação.

if (empty ($_POST)){ echo 'POST is empty'; }else{ echo 'Data Received '; if (isset($_POST['vads_hash'])){ echo 'Form API notification detected'; //Signature computation //Signature verification //Order Update } }



15.3. Calcular a assinatura do IPN

A assinatura é calculada segundo a mesma lógica usada durante a solicitação de pagamento.

IMPORTANTE

Os dados enviados pela plataforma de pagamento são codificados em UTF-8. Qualquer alteração dos dados recebidosresultará em um cálculo de assinatura incorreto.

Você deve calcular a assinatura com os campos recebidos na notificação e não com os que você enviou na sua solicitação depagamento.

1. Levem em consideração todos os campos com o nome começando por vads_.

2. Classifique todos os campos por ordem alfabética.

3. Separe os valores dos campos com o símbolo "+".

4. Concatene o resultado com a chave de teste ou de produção, separando-os com o símbolo "+".

5. Conforme o algoritmo definido na configuração da sua loja:

a. Se sua loja estiver configurada para usar “SHA-1”, aplique a função hash SHA-1 no string obtido naetapa anterior. Desvalorizado.

b. Se sua loja estiver configurada para usar "HMAC-SHA-256", calcule e codifique no formato Base64a assinatura da mensagem usando o algoritmo HMAC-SHA-256 com os parâmetros seguintes:




Exemplos em PHP

function getSignature($params, $key){ /** * Função que calcula a assinatura. * $params : quadro apresentando os campos recebidos na IPN. * $key : chave de TEST ou de PRODUCTION */ //IInicialização da variável que conterá o string a ser cifrado $conteúdo_assinatura= ""; //Triagem dos campos por ordem alfabética ksort($params); foreach($params as $nome=>$valor){ //Recuperação dos campos vads_ if (substr($nom,0,5)=='vads_'){ //Concatenação com o separador "+" $conteúdo_assinatura .= $valor."+"; } } //Adição da chave no final do string $conteúdo_assinatura .= $key; //Codificação base64 do string cifrado com ol algoritmo HMAC-SHA-256 $sign = base64_encode(hash_hmac('sha256',$conteúdo_assinatura, $key, true)); return $sign; }



15.4. Comparar as assinaturas

Para garantir a integridade da resposta, você deve comparar a assinatura presente na IPN com o valorcalculado na etapa anterior.

IMPORTANTENão pode comparar a assinatura da IPN com a assinatura que você enviou na sua solicitação de pagamento.

Se as assinaturas corresponderem,

• você poderá então considerar que a resposta esta segura e continuar a análise.

• caso contrário, o script deverá apontar uma exceção e avisar o Estabelecimento Comercial sobre aanomalia

Exemplo PHP:

if ($_POST['signature'] == $sign){ //Processing data

}else{ throw new Exception('An error occurred while computing the signature');}

As assinaturas não correspondem por causa de:

• erro de implementação (erro no seu cálculo, problema de codificação UTF-8, etc.),

• erro no valor da chave usada ou na chave do campo vads_ctx_mode (problema freqüente quandopassa em produção).

• tentativa de corrupção dos dados.



15.5. Analisar a natureza da notificação

O campo vads_url_check_src permite diferenciar as notificações vinculadas em função do evento quelançou elas:

• criação de um Token cartão (com ou sem contratação de uma assinatura).

• pagamento de uma parcela de uma assinatura.

• retorna a notificação a partir do Back Office Estabelecimento Comercial pelo EstabelecimentoComercial.

Ele menciona a regra de notificação aplicada:

Valor Regra aplicada

PAY O valor PAY é enviado nos seguintes casos:

• solicitação de criação de um mandato ou de um Token Cartão (REGISTER)

• solicitação de criação de um mandato ou de um Token Cartão na contratação uma assinatura(REGISTER_SUBSCRIBE)

• pagamento à vista (pagamento à vista ou primeira parcela de um pagamento parcelado)

• o comprador desistiu ou cancelou o pagamentosomente se o Estabelecimento Comercial configurou a regra URL de notificação de anulação.

BO Execução da notificação a partir do Back Office Estabelecimento Comercial (clique direito em umatransação > Executar a URL de notificação).Verifique a presença o campo vads_recurrence_number:

• se presente, a notificação refere ao resultado de um pagamento recorrente (re-chamada de umanotificação de tipo REC),

• se ausente, a notificação refere à notificação de fim de pagamento.

BATCH O BATCH será enviado se houver uma atualização do status de uma transação após a sincronizaçãocom o adquirente.É o que acontece com pagamentos redirecionados para o adquirente.Somente se o Estabelecimento Comercial configurou a regra Url de notificação para umamodificação por batch.

BATCH_AUTO O valor BATCH_AUTO é enviado nos seguintes casos:

• pagamento pré-datado com mais de 7 dias

• prestações de um pagamento parcelado (com exceção da primeira)somente se o Estabelecimento Comercial configurou a regra Url de notificação para umaautorização por batch.

A notificação é enviada durante a solicitação de autorização de um pagamento com o status de"Esperando a autorização".

REC O valor REC é enviado somente para os pagamentos por assinatura se o Estabelecimento Comercialconfigurou a regra URL de notificação na criação de um pagamento recorrente.

MERCH_BO O valor MERCH_BO é enviado:

• durante uma operação realizada a partir do Back Office Estabelecimento Comercial(cancelamento, reembolso, modificação, validação, duplicata, criação e/ou atualização deum Token Cartão), se o Estabelecimento Comercial configurou a regra de notificação: Url denotificação para uma operação proveniente do Back Office

RETRY Rechamada automática da URL de notificação.Verifique a presença o campo vads_recurrence_number:

• se presente, a notificação refere ao resultado de um pagamento recorrente (re-chamada de umanotificação de tipo REC),

• se ausente, a notificação refere à notificação de fim de pagamento.

Tabela 1 : Valores associados ao campo vads_url_check_src

Testando seu valor, o script pode realizar um tratamento diferente em função da natureza da notificação.



Por exemplo:

Se vads_url_check_src tem o valor de PAY ou de BATCH_AUTO então o script atualiza o status dasolicitação, ...

Se vads_url_check_src tem o valor de REC, o script recupera então a referência da assinatura e incrementao número de parcelas vencidas no caso de um pagamento aceito, ...

No caso de um débito recorrente (proveniente de um REGISTER_SUBSCRIBE), a plataforma de pagamentonotifica o credor (Estabelecimento Comercial) na criação de toda transação.

15.6. Tratar os dados da resposta

Criação de um Token Cartão

Para entender o resultado, analise os campos abaixo:


vads_page_action Ação realizada.O valor retornado é REGISTER.

vads_identifier_status Status da criação do Token Catão.Os valores possíveis são:

• CREATED : a solicitação de autorização foi aceita.O Token Cartão foi criado com sucesso e consta no Back Office EstabelecimentoComercial.

• NOT_CREATED : a solicitação de autorização foi recusada. O Token Cartão não foi criado.

• ABANDONED : O comprador desistiu da ação. O Token Cartão não foi criado.

vads_identifier Código do Token Cartão.O valor retornado é:

• ou idêntico ao valor enviado na solicitação, seja qual for o resultado da criação do TokenCartão, mesmo em caso de desistência,

• ou o valor gerado pela plataforma, se o campo não for enviado na solicitação e que oToken Cartão for criado com sucesso (vads_identifier_status=CREATED).

O campo vads_identifier não é retornado:

• se não for enviado na solicitação e se o comprador desiste(vads_identifier_status=ABANDONED),

• se não for enviado na solicitação e se o Token Cartão não for criado(vads_identifier_status=NOT_CREATED).

vads_cust_email Endereço e-mail do comprador enviado na solicitação.

vads_site_id Código de identificação da loja.O valor retornado é idêntico ao valor enviado na solicitação.

vads_ctx_mode Modo de funcionamento.O valor retornado (TEST ou PRODUCTION) é idêntico ao valor enviado na solicitação.

Uma solicitação de “criação de um Token Cartão sem pagamento” resulta na criação de uma transaçãode tipo VERIFICATION, exibida no Back Office.

Esta transação ajuda o Estabelecimento Comercial a entender no seu Back Office porque a criação doToken Cartão foi recusada.

Seguem suas características:


vads_operation_type Tipo de transação.



Nome do campo DescriçãoSeu valor é VERIFICATION.

vads_trans_status Status da transação.Os valores possíveis são:

• ACCEPTEDA solicitação de autorização ou de informação foi aceita.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.

• REFUSEDA solicitação de autorização ou de informação foi recusada.O Token Cartão não foi criado.

vads_amount 100

vads_trans_id Código da transaçãoO valor dele é gerado pela plataforma de pagamento

vads_trans_uuid Código único da transação.O valor dele é gerado pela plataforma de pagamento

vads_auth_mode Tipo de solicitação realizada para os servidores de autorização.Seu valor é MARK.

vads_auth_number Número de autorização retornado pelo servidor de autorização.Vazio se a autorização falhou.

vads_auth_result Código retorno da solicitação de autorização devolvida pelo banco emissor.Vazio se erro antes da autorização.

vads_risk_assessment_result Lista das ações realizadas na transação, após o acionamento das regras de gerenciamento derisco avançado.As regras relativas ao valor ou cuja ação for “Validar manualmente” não se aplicam no casode uma transação de tipo VERIFICATION.Os valores possíveis são:

• ENABLE_3DS: 3D Secure ativado.

• DISABLE_3DS 3D Secure desativado.

• REFUSE: A solicitação de criação de Token Cartão é recusada.

• RUN_RISK_ANALYSIS: Resultado do analista de riscos externos.Consulte a descrição do campo vads_risk_analysis_result para maiores detalhes.

• INFORM : Um aviso foi enviado.O Estabelecimento Comercial é avisado que um risco foi identificado por uma ou maisregras do centro de notificação.

Informações sobre o meio de pagamento usado

Nome do campo Observação

vads_card_brand Meio de pagamento usado.Consulte o capítulo Meios de pagamento compatíveis para ter a lista dos valores possíveis.

vads_card_number Número do cartão truncado / oculto.

vads_expiry_month Mês de vencimento do cartão usado.

vads_expiry_year Ano de vencimento do cartão usado.

vads_card_country Código país do cartão usado segundo a norma ISO 3166.

vads_bank_label Nome do banco emissor do cartão usado.

vads_bank_product Código produto do cartão usado.

Detalhes sobre a autenticação 3DS


vads_threeds_auth_type Tipo de autenticação do portador.Os valores possíveis são:

• “Vazio” se o comprador não se autenticou corretamente,



Nome do campo Observação• FRICTIONLESS: autenticação do portador sem interação com a ACS. Valor retornado

somente em 3DS v2,

• CHALLENGE: autenticação interativa do portador (digitação OTP ou resposta a uma seriede perguntas). Valor retornado em 3DS v1 e 3DS v2.

vads_threeds_enrolled Status de inscrição do portador ao programa 3D Secure.Os valores possíveis são:

• Y: Autenticação disponível.

• N: Autenticação não disponível.

• U: Status de inscrição ao programa 3DS Secure desconhecido.

• vazio: Processo 3DS não realizado (3DS desativado na solicitação, EstabelecimentoComercial não inscrito ou meio de pagamento não elegível no 3DS).

vads_threeds_status Resultado da autenticação 3D Secure.Os valores possíveis são:

• Y: Portador identificado com sucesso.

• N: Erro de autenticação do portador.

• U: Autenticação impossível.

• A: Tentativa de autenticação mas autenticação não efetuada.

• vazio: Autenticação 3DS não realizada (3DS desativado na solicitação, portador nãoinscrito ou meio de pagamento não elegível no 3DS).

Os campos facultativos enviados na solicitação são retornados na resposta com os mesmos valores.



Modificação das informações associadas ao Token Cartão



vads_page_action Ação realizada.O valor retornado é REGISTER_UPDATE.

vads_identifier_status Status da atualização de Token Cartão.Os valores possíveis são:

• UPDATED: : o Token Cartão foi atualizado com sucesso.

• NOT_UPDATED: o Token Cartão não foi atualizado.

• ABANDONED : O comprador desistiu da ação.O Token não foi criado e não será exibido no Back Office Estabelecimento Comercial.

vads_identifier Código de Token Cartão para atualizar.O valor retornado é idêntico ao valor enviado na solicitação.




Uma solicitação de atualização de um Token Cartão resulta na criação de uma transação de tipoVERIFICATION, exibida no Back Office.




vads_operation_type Tipo de transação.Seu valor é VERIFICATION.




vads_amount 100









Nome do campo Descrição• ENABLE_3DS: 3D Secure ativado.


















• FRICTIONLESS: autenticação do portador sem interação com a ACS. Valor retornadosomente em 3DS v2,
















Criação de um Token Cartão durante um pagamento



vads_page_action Ação realizada.O valor retornado é REGISTER_PAY.


• CREATED : a solicitação de autorização foi aceita.O Token Cartão foi criado com sucesso.

• NOT_CREATED : a solicitação de autorização foi recusada.O Token não foi criado e não será exibido no Back Office Estabelecimento Comercial.



• AUTHORISEDA solicitação de autorização ou de informação foi aceita.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.

• AUTHORISED_TO_VALIDATEA solicitação de autorização ou de informação foi aceita.O Estabelecimento Comercial deve validar manualmente a transação.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.

• CAPTUREDA solicitação de autorização ou de informação foi aceita.O pagamento está exibido na aba “Transações capturadas” do Back Office.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.

• WAITING_AUTHORISATIONO prazo de captura no banco é maior que o tempo de validade da autorização. Asolicitação de autorização para o valor total ainda não foi feita.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.

• WAITING_AUTHORISATION_TO_VALIDATEPara validar e autorizarO prazo de captura no banco é maior que o tempo de validade da autorização.Uma autorização 1 BRL foi aceita.O Estabelecimento Comercial deve validar manualmente a transação para lançar asolicitação de autorização e a captura.


• ABANDONEDO comprador desistiu da operação.A transação não está exibida no Back Office Estabelecimento Comercial.O Token Cartão não foi criado.




O campo vads_identifier não será retornado:



Nome do campo Descrição• se não for enviado na solicitação e se o comprador desiste

(vads_identifier_status=ABANDONED),





Para ter o detalhe do pagamento, consulte os dados abaixo:

Informações sobre a transação:


vads_operation_type Tipo de transação.Seu valor é DEBIT.

vads_amount Valor da transação.O valor retornado é idêntico ao valor enviado na solicitação.

vads_currency Código da moeda usada para o pagamento.

vads_trans_id Código da transaçãoO valor retornado é idêntico ao valor enviado na solicitação.


vads_contract_used Número do contrato associado à transação.

vads_auth_mode Tipo de solicitação realizado para os servidores de autorização:

• MARK : corresponde a uma autorização de 1 BRL.Valor também usado se o tempo entre a data de captura solicitada e a data do vigente forexatamente superior ao tempo de validade da autorização.

• FULL: corresponde a uma autorização do valor total da transação.Valor usado se o tempo entre a data de captura solicitada e a data vigente forexatamente inferior ao tempo de validade da autorização.



vads_risk_control Resultado dos controles de risco.Quando pelo menos um controle retorna o valor ERROR, a transação é recusada.Consulte a descrição do campo vads_risk_analysis_result para maiores detalhes.

vads_risk_assessment_result Lista das ações realizadas na transação, após o acionamento das regras de gerenciamento derisco avançado.Os valores possíveis são:



• MANUAL_VALIDATION: Transação criada em validação manual.A captura do pagamento está bloqueada temporariamente para permitir aoEstabelecimento Comercial efetuar todas as verificações desejadas.

• REFUSE: A transação foi recusada.









vads_expiry_month Mês de vencimento do cartão usado para o pagamento.

vads_expiry_year Ano de vencimento do cartão usado para o pagamento.

vads_card_country Código país do cartão usado para o pagamento segundo a norma ISO 3166.

vads_bank_label Nome do banco emissor do cartão usado para o pagamento.

vads_bank_product Código produto do cartão usado para o pagamento.

Detalhes sobre a autenticação alta:
















Criação de um Token Cartão na contratação de uma assinatura



vads_page_action Ação realizada.O valor retornado é REGISTER_SUBSCRIBE.


• CREATED : a solicitação de autorização foi aceita.O Token Cartão foi criado com sucesso.Consulte o valor do campo vads_recurrence_status para saber se a assinatura foi criada.

• NOT_CREATED : a solicitação de autorização foi recusada.O Token não foi criado e não será exibido no Back Office Estabelecimento Comercial. Aassinatura não foi criado.

• ABANDONED : O comprador desistiu da ação.O Token Cartão não foi criado e não está exibido no Back Office EstabelecimentoComercial.A assinatura não foi criado.

vads_recurrence_status Status da criação da assinatura.Os valores possíveis são:

• CREATED: A assinatura foi criada com sucesso.

• NOT_CREATED: A assinatura não foi criado.

• ABANDONED: o comprador desistiu da ação. A assinatura não foi criado.




O campo vads_identifier não é retornado:



vads_subscription Código de identificação da assinatura.O valor retornado é:

• ou o valor enviado na solicitação, seja qual for o resultado da criação da assinatura,

• ou o valor gerado pela plataforma de pagamento, se o campo não for enviado com asolicitação e que a assinatura for criada com sucesso (vads_recurrence_status=CREATED).

O campo vads_subscription não será retornado:

• se não for enviado na solicitação e se o comprador desiste(vads_recurrence_status=ABANDONED),

• se não for enviado na solicitação e se a assinatura não for criada(vads_recurrence_status=NOT_CREATED).




Uma solicitação de “criação de um Token Cartão na contratação de uma assinatura” resulta na criaçãode uma transação de tipo VERIFICATION, exibida no Back Office.






vads_operation_type Tipo de transação.Seu valor é VERIFICATION.




vads_amount 100



























• FRICTIONLESS: autenticação do portador sem interação com a ACS. Valor retornadosomente em 3DS v2,
















Criação de um Token Cartão na contratação de uma assinatura seguida de um pagamento



vads_page_action Ação realizada.O valor retornado é REGISTER_PAY_SUBSCRIBE.


• CREATED : a solicitação de autorização foi aceita.O Token Cartão foi criado com sucesso.Consulte o valor do campo vads_recurrence_status para saber se a assinatura foi criada.

• NOT_CREATED : a solicitação de autorização foi recusada.O Token não foi criado e não será exibido no Back Office Estabelecimento Comercial. Aassinatura não foi criado.

• ABANDONED : O comprador desistiu da ação.O Token Cartão não foi criado e não está exibido no Back Office EstabelecimentoComercial.A assinatura não foi criado.



• AUTHORISED_TO_VALIDATEA solicitação de autorização ou de informação foi aceita.O Estabelecimento comercial deve validar manualmente a transação.O Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.










Nome do campo Descrição• NOT_CREATED: A assinatura não foi criado.



























• MARK: corresponde a uma autorização de 1 BRL.Valor também usado se o tempo entre a data de captura solicitada e a data do vigente forexatamente superior ao tempo de validade da autorização.


vads_auth_number Número de autorização retornado pelo servidor de autorização.



Nome do campo DescriçãoVazio se a autorização falhou.









• INFORM: Um aviso foi enviado.O Estabelecimento Comercial é avisado que um risco foi identificado por uma ou maisregras do centro de notificação.


























Pagamento por Token Cartão



vads_page_action Ação realizada.O valor retornado é PAYMENT.









vads_identifier Código do Token Cartão para debitar.O valor retornado é idêntico ao valor enviado na solicitação.

vads_cust_email Endereço e-mail do comprador associado ao Token Cartão.









Nome do campo DescriçãoSeu valor é DEBIT.






























vads_threeds_enrolled Status de inscrição do portador ao programa 3D Secure.



Nome do campo ObservaçãoOs valores possíveis são:












Contratação de uma assinatura



vads_page_action Ação realizada.O valor retornado é SUBSCRIBE.



• NOT_CREATED: A assinatura não foi criado.


vads_identifier Código do Token Cartão para debitar.O valor retornado é idêntico ao valor enviado na solicitação.







vads_cust_email Endereço e-mail do comprador associado ao Token Cartão.









vads_expiry_month Mês de vencimento do cartão usado para a criação do Token Cartão.

vads_expiry_year Ano de vencimento do cartão usado para o criação do Token Cartão.

vads_card_country Código país do cartão usado para a criação do Token Cartão segundo a norma ISO 3166.

vads_bank_label Nome do banco emissor do cartão usado para a criação do Token Cartão.

vads_bank_product Código produto do cartão usado para o criação do Token Cartão.

Detalhes sobre a autenticação alta realizada na criação do Token Cartão:














Pagamento com proposta ao portador de criar um Token Cartão



vads_page_action Ação realizada.O valor retornado é ASK_REGISTER_PAY.

vads_identifier_status Status da criação do Token Catão.O campo não será enviado se o comprador não autorizou o registro dos seus dados decartão.Os valores possíveis são:

• CREATED : a solicitação de autorização foi aceita.O Token Cartão foi criado com sucesso.

• NOT_CREATED : a solicitação de autorização foi recusada.O Token não foi criado e não será exibido no Back Office Estabelecimento Comercial.



• AUTHORISEDA solicitação de autorização ou de informação foi aceita.



Nome do campo DescriçãoO Token Cartão foi criado e pode ser consultado no Back Office EstabelecimentoComercial.







vads_identifier Código do Token Cartão.O campo não será enviado se o comprador não autorizou o registro dos seus dados decartão.O valor retornado é:















Nome do campo DescriçãoSeu valor é DEBIT.







• MARK : corresponde a uma autorização de 1 BRL.Valor também usado se o tempo entre a data de captura solicitada e a data do vigente forexatamente superior ao tempo de validade da autorização.























vads_threeds_enrolled Status de inscrição do portador ao programa 3D Secure.



Nome do campo ObservaçãoOs valores possíveis são:












Modificação de informações associadas a um Token Cartão durante um pagamento



vads_page_action Ação realizada.O valor retornado é REGISTER_UPDATE_PAY.

vads_identifier_status Status da atualização de Token Cartão.Os valores possíveis são:

• UPDATED: : o Token Cartão foi atualizado com sucesso.

• NOT_UPDATED: o Token Cartão não foi atualizado.









Nome do campo Descrição• WAITING_AUTHORISATION_TO_VALIDATE

Para validar e autorizarO prazo de captura no banco é maior que o tempo de validade da autorização.Uma autorização 1 BRL foi aceita.O Estabelecimento Comercial deve validar manualmente a transação para lançar asolicitação de autorização e a captura.



vads_identifier Código de Token Cartão para atualizar.O valor retornado é idêntico ao valor enviado na solicitação.
























Nome do campo Descrição• MANUAL_VALIDATION: Transação criada em validação manual.

A captura do pagamento está bloqueada temporariamente para permitir aoEstabelecimento Comercial efetuar todas as verificações desejadas.





























15.7. Teste e troubleshooting

Para testar as notificações, siga as etapas seguintes:

1. Faça um pagamento (em modo TESTE ou em modo PRODUÇÃO).

2. Quando finalizou o pagamento, procure a transação no seu Back Office (Menu Gerenciamento >Transações ou Transações de TESTE se você fez o pagamento em modo TESTE.

3. Clique duas vezes na transação para exibir o detalhe da transação.

4. No detalhe da transação, encontre a seção Dados técnicos.

5. Verifique o status da URL de notificação:

Segue a lista dos status possíveis:

Status Descrição

N/A A transação não resultou em uma notificação e nenhuma regra de notificação foiativada.

URL não definida Um evento deu inicio à regra de notificação de fim de pagamento mas a URL nãoestá configurada.

Chamada em andamento Notificação em andamento. Este status é temporário.

Enviado A notificação foi devidamente enviada e um dispositivo remoto respondeu com umcódigo HTTP 200, 201, 202, 203, 204, 205 ou 206.

Enviado (redirecionamento permanente) O site de e-commerce retornou um código HTTP 301 ou 308 com uma nova URLde contato. Uma nova chamada em modo POST é realizada para a nova URL

Enviado (redirecionamento temporário) O site de e-commerce retornou um código HTTP 302 ou 307 com uma nova URL decontato. Uma nova chamada em modo POST é realizada para a nova URL

Enviado (redirecionamento para uma outrapágina)

O site de e-commerce retornou um código HTTP 303 com uma nova URL decontato. Uma nova chamada em modo GET é realizada para a nova URL.

Falha Erro genérico diferente dos códigos apresentados abaixo.

Servidor indisponível A notificação durou mais de 35s.

Erro handshake SSL A configuração do seu servidor não está correta.Faça um diagnóstico no site da Qualys (https://www.ssllabs.com/ssltest/) ecorrija os erros.

Conexão interrompida Erro de comunicação.

Conexão recusada Erro de comunicação.

Erro servidor 300 Caso de redirecionamento não suportado pela plataforma.



Erro servidor 400 O site de e-commerce retornou um código HTTP 400 Bad Request.

Erro servidor 401 O site de e-commerce retornou um código HTTP 401 Unauthorized..Certifique-se de que o recurso não esteja protegido por um arquivo .htaccess.

Erro servidor 402 O site de e-commerce retornou um código HTTP 402 Payment Required.

Erro servidor 403 O site de e-commerce retornou um código HTTP 403 Forbidden.Certifique-se de que o recurso não esteja protegido por um arquivo .htaccess.

Erro servidor 404 O site de e-commerce retornou um código HTTP 404 Not Found.Verifique que a URL esteja devidamente digitada na configuração da regra.Verifique também que o arquivo esteja de fato presente no seu servidor.

Erro servidor 405 O site de e-commerce retornou um código HTTP 405 Method Not allowed.

Erro servidor 406 O site de e-commerce retornou um código HTTP 406 Not Acceptable.

Erro servidor 407 O site de e-commerce retornou um código HTTP 407 Proxy AuthenticationRequired.




Status Descrição

Erro servidor 408 O site de e-commerce retornou um código HTTP 408 Request Time-out.

Erro servidor 409 O site de e-commerce retornou um código HTTP 409 Conflict.

Erro servidor 410 O site de e-commerce retornou um código HTTP 410 Gone.

Erro servidor 411 O site de e-commerce retornou um código HTTP 411 Length Required.

Erro servidor 412 O site de e-commerce retornou um código HTTP 412 Precondition Failed.

Erro servidor 413 O site de e-commerce retornou um código HTTP 413 Request Entity Too Large.

Erro servidor 414 O site de e-commerce retornou um código HTTP 414 Request-URI Too long.

Erro servidor 415 O site de e-commerce retornou um código HTTP 415 Unsupported Media Type.

Erro servidor 500 O site de e-commerce retornou um código HTTP 500 Internal Server Error.Um erro aplicativo ocorreu no nível do servidor que hospeda sua loja. Consulte oslogs do seu servidor HTTP (geralmente apache).O problema só pode ser corrigido indo no seu servidor.

Erro servidor 501 O site de e-commerce retornou um código HTTP 501 Not Implemented.

Erro servidor 502 O site de e-commerce retornou um código HTTP 502 Bad Gateway / Proxy Error.

Erro servidor 503 O site de e-commerce retornou um código HTTP 503 Service Unavailable.

Erro servidor 504 O site de e-commerce retornou um código HTTP 504 Gateway Time-out.O servidor do Estabelecimento Comercial não aceitou a chamada dentro do prazoprevisto de 10s.

Erro servidor 505 O site de e-commerce retornou um código HTTP 505 HTTP Version not supported.

Para obter mais informações sobre uma notificação, clique no link Exibir as informações ou clique na abaHistórico e encontra a linha Chamada URL de notificação.

Para ajudar o Estabelecimento Comercial a identificar a origem do erro, a plataforma analisasistematicamente os 512 primeiros dígitos retornados pelo site de e-commerce e os exibe na coluna Info.

• Exemplo de notificação realizada com sucesso:

• Exemplo de notificação em falha

Se a plataforma não conseguir entrar em contato com a URL da sua página, um e-mail de alerta será entãoenviado para o endereço e-mail especificado.

Contém:



• O código HTTP do erro encontrado

• Elementos de analise segundo o erro

• As suas conseqüências

• Os passos a seguir a partir do <ph ixia_locid="125" translate="no">Back Office </ph>Back OfficeEstabelecimento Comercial para enviar de novo a solicitação para a URL definida na configuração daregra.



16. ANEXOS

16.1. Criar automaticamente uma assinatura por Web services

• Web Services SOAP V5

Usar a operação createSubscription.

Para maiores informações, favor consultar Guia de implementação API Webservices SOAP v5 disponívelem nossa página de documentações e suporte.

• Web services REST de pagamento

Use o método Charge/CreateSubscription para realizar pagamentos recorrentes (assinaturas) com umToken Cartão já existente e válido.

16.2. Rescindir automaticamente uma assinatura por Web services

• Web Services SOAP V5

Utilizar a operação cancelSubscription para rescindir uma assinatura em uma data determinada.

Para maiores informações, favor consultar Guia de implementação API Webservices SOAP v5 disponívelem nossa página de documentações e suporte.

• Web services REST de pagamento

Use o método Subscription/Cancel para rescindir uma assinatura.

guia de implementação - documentation payzen · [email protected]. entrar em contato com o...

Documents