PDF

Transcrição

PDF

Manual de integração via formulário
PayZen 2.5
Versão do documento 3.6
Conteúdo
1. HISTÓRICO DO DOCUMENTO........................................................................................................4
2. ENTRAR EM CONTATO COM O SUPORTE TÉCNICO............................................................... 6
3. OS DIFERENTES TIPOS DE PAGAMENTO.................................................................................. 7
3.1.
3.2.
3.3.
3.4.
Pagamento
Pagamento
Pagamento
Solicitação
à vista........................................................................................................................................7
pré-datado................................................................................................................................. 7
parcelado................................................................................................................................... 7
de autorização........................................................................................................................... 8
4. ENTENDER O PROCESSO DE UM PAGAMENTO....................................................................... 9
4.1. Definir as etapas de um pagamento - Visão do comprador........................................................................9
4.2. Definir as etapas de um pagamento - Visão do vendedor........................................................................ 12
4.3. Ciclo de vida das transações..................................................................................................................... 13
5. ESTABELECER O DIÁLOGO COM A PLATAFORMA DE PAGAMENTO.............................. 20
5.1. Definir a URL da página de pagamento...................................................................................................20
5.2. Identificar-se durante as trocas................................................................................................................. 20
5.3. Escolher o modo de Teste ou de Produção.............................................................................................. 21
5.4. Gerenciar o diálogo com o site de e-commerce....................................................................................... 22
5.5. Gerenciar a segurança............................................................................................................................... 24
5.7. Gerenciar as configurações da sua loja por arquivo de configuração.......................................................26
6. CONFIGURAR AS NOTIFICAÇÕES............................................................................................... 27
6.1. Notificações dos diferentes status para um pagamento a vista.................................................................27
6.2. Notificações dos diferentes status para um pagamento pré-datado.......................................................... 28
6.3. Notificações dos diferentes status para as parcelas de um pagamento parcelado..................................... 29
6.4. Configurar as notificações.........................................................................................................................30
Configurar a notificação no final do pagamento................................................................................. 30
Configurar a notificação do resultado final de um pagamento pré-datado.......................................... 32
Configurar a notificação se o comprador desiste ou cancela...............................................................34
Configurar a notificação em autorização por batch............................................................................. 35
6.5. Ativar a re-chamada automática............................................................................................................... 36
6.6. Re-chamar manualmente a notificação..................................................................................................... 38
6.7. Configurar os e-mails enviados para o comprador................................................................................... 39
6.8. Configurar os e-mails enviados para o vendedor..................................................................................... 40
7. CRIAR UM FORMULÁRIO DE PAGAMENTO............................................................................ 42
7.1.
7.2.
7.3.
7.4.
Criar
Criar
Criar
Criar
um pagamento à vista...................................................................................................................... 43
um pagamento pré-datado................................................................................................................44
um pagamento parcelado................................................................................................................. 46
uma autorização sem captura...........................................................................................................48
8. USAR FUNÇÕES COMPLEMENTARES........................................................................................ 49
8.1. Definir o modo de captura no banco (automático / manual).................................................................... 50
8.2. Enviar os dados do comprador................................................................................................................. 52
8.3. Enviar os dados de entrega....................................................................................................................... 53
8.4. Enviar os dados do pedido........................................................................................................................54
8.5. Ativar / Desativar 3D Secure.................................................................................................................... 56
8.6. Definir o contrato comercial..................................................................................................................... 57
8.7. Gerenciar o retorno para o site de e-commerce........................................................................................58
8.8. Ativar o retorno automático para o site de e-commerce...........................................................................61
8.9. Personalizar a página de pagamento......................................................................................................... 62
8.10. Sobrescrever a URL de notificação instantânea (IPN)........................................................................... 68
8.11. Criar um pagamento sem redirecionar para a página de pagamento...................................................... 69
9. CALCULAR A ASSINATURA.......................................................................................................... 71
9.1. Exemplo de implementação em JAVA.....................................................................................................72
9.2. Exemplo de implementação em PHP........................................................................................................73
10. ENVIAR A SOLICITAÇÃO DE PAGAMENTO...........................................................................74
10.1. Redirecionar o comprador para a página de pagamento.........................................................................74
10.2. Gerenciar os erros....................................................................................................................................74
11. ANALISAR O RESULTADO DO PAGAMENTO........................................................................75
11.1.
11.2.
11.3.
11.4.
11.5.
11.6.
11.7.
Recuperar os dados devolvidos na resposta............................................................................................77
Calcular a assinatura................................................................................................................................78
Comparar as assinaturas.......................................................................................................................... 78
Analisar a natureza da notificação.......................................................................................................... 79
Identificar o tipo de operação................................................................................................................. 80
Tratar os dados da resposta.....................................................................................................................81
Tratar os erros......................................................................................................................................... 86
12. TRATAR O RETORNO PARA A LOJA.......................................................................................87
13. INICIAR A FASE DE TESTE........................................................................................................ 88
13.1. Efetuar testes de pagamento....................................................................................................................88
13.2. Testar a URL de notificação instantânea (IPN)......................................................................................88
14. ATIVAR A LOJA EM MODO DE PRODUÇÃO.......................................................................... 89
14.1.
14.2.
14.3.
14.4.
Gerar o certificado de produção..............................................................................................................89
Passar seu site de e-commerce em produção..........................................................................................89
Efetuar um primeiro pagamento em produção....................................................................................... 89
Gerar de novo o certificado de produção............................................................................................... 90
15. FAQ - PERGUNTAS MAIS FREQUENTES................................................................................ 91
16. DICIONÁRIO DE DADOS............................................................................................................. 92
1. HISTÓRICO DO DOCUMENTO
Versão
Data
Comentário
3.6
01/02/2016
Precisões dadas para o meio de pagamento Itau Internet Banking (capítulo
vads_payment_cards do dicionário de dados).
Dicionário de dados
•
3.5
3.4
23/11/2015
01/10/2015
vads_auth_result : adição dos valores. AMEX
•
vads_payment_cards e vads_contracts : adição de valores.
•
Precisões dadas sobre o formato dos campos:
•
vads_cust_address
•
vads_ship_to_street
•
vads_ship_to_street2
•
vads_trans_status : adição do status INITIAL na lista dos status possíveis.
•
vads_change_rate
•
vads_recurrence_number
•
Correção do formato do campo vads_product_labelN
•
Correção do nome do campo vads_product_vatN
•
Adição do campo:
•
3.3a
24/07/2015
vads_cust_national_id
Capítulo adicional
•
Configurar a notificação em autorização por batch
Modificação dos capítulos:
3.3
07/07/2015
•
Utilizar uma i-frame
•
vads_trans_id
Capítulos adicionais
•
Configurar os e-mails enviados para o comprador.
•
Configurar os e-mails enviados para o vendedor.
Informações adicionais sobre a utilização de uma i-frame.
•
Adição dos campos:
•
vads_trans_uuid
•
vads_risk_assessment_result
•
vads_risk_analyzis_result : acrescentar valores.
•
vads_payment_cards : acrescentar valores.
3.2
27/04/2015
Correção de erro para o campovads_ship_to_type
3.1
02/03/2015
URL servidor renomeada em URL de notificação
Capítulos adicionais
•
Gerenciar as configurações da sua loja por arquivo de configuração
•
Ativar a re-chamada automática
•
Re-chamar manualmente a notificação
Informações adicionais sobre a utilização de uma i-frame.
Manual de integração via formulário - Versão do documento 3.6
Direito de propriedade intelectual - 4 / 163
Versão
Data
Comentário
•
3.0
21/11/2014
Adição dos campos:
•
vads_payment_seq
•
vads_cust_legal_name
•
vads_ship_to_legal_name
•
Acrescentar o valor E_CV na lista dos meios de pagamento (rede ANCV)
•
Precisão sobre o campo vads_url_check
Refazer globalmente a documentação.
Confidencialidade
Todas as informações contidas neste documento são consideradas como confidenciais. O uso destas fora do quadro
desta consulta ou a divulgação para pessoas alheias esta submetida à aprovação antecipada da Lyra Network.
2. ENTRAR EM CONTATO COM O SUPORTE TÉCNICO
Em caso de problema de conexão com o Back Office, clique no link "senha esquecida ou senha bloqueada".
Para perguntas técnicas ou solicitação de assistência, nossos serviços estão disponíveis :
por telefone no:
+55 (11) 3336-9217 ou +55 (11) 3336-9209 ligando do Brasil
por e-mail:
[email protected]
Para facilitar o atendimento as suas solicitações, você deverá informar seu código de loja (número com
8 dígitos).
Esta informação aparece no e-mail de cadastro da sua loja, ou no Back Office (menu Configuração > Loja
> Configurações).
3. OS DIFERENTES TIPOS DE PAGAMENTO
3.1. Pagamento à vista
Um pagamento é considerado como à vista si:
• o valor é debitado de uma vez só,
• o prazo de captura no banco é de 0 dia.
Uma solicitação de autorização para o valor global é efetuada. O pagamento esta entregue no banco assim
que for possível.
3.2. Pagamento pré-datado
Um pagamento é considerado como pré-datado se:
• o valor é debitado de uma vez só,
• o prazo de captura no banco é estritamente superior a 0 dia.
A data da captura não pode ser superior a 12 meses em relação à data de registro do pagamento.
Existe dois tipos de pagamentos pré-datados:
• Prazo de captura menor em relação ao tempo de validade da autorização (ver seção Validade de uma
autorização apresentada abaixo)
Uma solicitação de autorização para o valor global é efetuada. Sem modificações da parte do vendedor, o
pagamento é entregue na data de apresentação solicitada.
• Prazo de captura maior em relação ao tempo de validade da autorização (ver seção Validade de uma
autorização apresentada abaixo)
Uma solicitação de autorização de 1 BRL é efetuada no hora do registro do pagamento para garantir a
validade do cartão.
Se esta autorização de 1 BRL for aceita, o pagamento é salvo.
D-1 na data de apresentação solicitada, uma solicitação de autorização para o valor global é efetuada.
O pagamento pode ser aceito ou recusado. O vendedor deve então ficar muito atento com este tipo de
pagamento antes de entregar um bem / um serviço para o comprador.
3.3. Pagamento parcelado.
Um pagamento é chamado "parcelado" desde que o comprador seja debitado pela sua compra em várias
parcelas.
A primeira parcela funciona da mesma maneira que um pagamento à vista.
A ou as parcela(s) seguinte(s) funciona(n) como o ou os pagamento(s) pré-datado(s).
Somente a primeira parcela pode estar sujeita a uma garantia para o vendedor somente se a data de
apresentação solicitada da primeira parcela for anterior a data de validade da autorização em função do
meio de pagamento. (ver seção Validade de uma autorização apresentada abaixo)
3.4. Solicitação de autorização
A plataforma de pagamento envia uma mensagem para o emissor do cartão para ter o acordo dele para
efetuar o pagamento da transação.
De uma maneira geral, o débito é efetivo somente após a captura da transação no banco.
Alguns emissores de cartão pré-pagos ou de procedência espanhola e canadense debitam o valor da
autorização em tempo real e o creditam de novo quando a autorização venceu (ver quadro abaixo).
Validade de uma autorização
Segue abaixo a lista dos meios de pagamento cuja validade de autorização é maior a 0 dia.
Meio de pagamento
Tipo de cartão
Tempo de validade de
uma autorização (em dias)
Rede
Boleto Bancário
BOLETO
BOLETO
7
American Express
AMEX
CIELO
4
Aura
AURA
CIELO
4
Elo
CIELO_ELO
CIELO
4
Diners
DINERS
CIELO
4
Discover
DISCOVER
CIELO
4
JCB
JCB
CIELO
4
Mastercard
MASTERCARD
CIELO
4
Visa
VISA
CIELO
4
Diners
DINERS
ELAVONBR
4
Discover
DISCOVER
ELAVONBR
4
Mastercard
MASTERCARD
ELAVONBR
4
Visa
VISA
ELAVONBR
4
Diners
DINERS
REDECARD
4
Hipercard
HIPERCARD
REDECARD
4
Mastercard
MASTERCARD
REDECARD
4
Visa
VISA
REDECARD
4
4. ENTENDER O PROCESSO DE UM PAGAMENTO
O procedimento de um pagamento online tem uma abordagem diferente se você tomar o ponto de vista
do comprador ou do vendedor.
4.1. Definir as etapas de um pagamento - Visão do comprador
O diagrama abaixo apresenta a cinemática das trocas do ponto de vista do comprador.
Figura 1 : Cinemática das trocas - Visão do comprador
1. O comprador finaliza o pedido.
2. O site de e-commerce redireciona o comprador para a plataforma de pagamento.
Esse redirecionamento assumirá a forma de um formulário HTML POST em HTTPS.
Os parâmetros do formulário são descritos no capítulo Gerar uma solicitação de pagamento.
3. A plataforma de pagamento, após verificação dos parâmetros e da sua assinatura irá apresentar a
página de seleção do meio de pagamento.
Figura 2 : Seleção do meio de pagamento
Se o meio de pagamento foi especificado no formulário, o comprador passa diretamente para a etapa 6.
4. O comprador seleciona seu meio de pagamento.
5. Ele clica em Validar.
6. Ele informa o número e a data de vencimento do cartão.
Se o cartão possui um criptograma visual, este último deve ser informado.
Figura 3 : Digitar as informações do meio de pagamento
7. Ele confirma o que ele digitou clicando em Validar.
8. Se o vendedor e o cartão do comprador são alistados no programa 3D Secure, uma autentificação 3D
Secure ocorre.
9. Uma solicitação de autorização é feita para o banco do comprado, o emissor, além de controles de
fraudes internas da plataforma de pagamento.
10.Em caso de êxito, uma página de resumo será apresentada ao comprador recapitulando as
informações da transação.
Um botão possibilitando o retorno para a loja aparece.
Figura 4 : Recapitulativo da transação
Em caso de falha, uma mensagem é exibida. O comprador recebe a informação que a solicitação de
pagamento foi recusada. Um botão que permite cancelar e retornar para a loja aparece.
Figura 5 : Página de resumo em caso de falha da transação
4.2. Definir as etapas de um pagamento - Visão do vendedor
O pagamento online, do lado do vendedor, acontece da seguinte forma:
Figura 6 : Cinemática das trocas - Visão do vendedor
1. O comprador finaliza o pedido.
2. O site de e-commerce elabora o formulário a partir dos dados do carrinho do comprador.
3. O site de e-commerce redireciona o comprador para a plataforma de pagamento. Esse
redirecionamento assumirá a forma de um formulário HTML POST em HTTPS. Os parâmetros do
formulário são descritos no capítulo Gerar um formulário de pagamento.
4. Depois que o comprador digitou os dados do meio de pagamento, a plataforma efetua o pagamento.
5. Segundo a configuração da loja (ver capítulo Configurar as notificações), uma chamada automática
submete o resultado do pagamento ao site de e-commerce.
6. O site de e-commerce analisa e trata o resultado do pagamento.
7. Inicia a atualização da sua base de dados (status do pedido, estoque, etc...),
8. O comprador recebe o resultado do pagamento na plataforma. Se ele decide voltar para o site de ecommerce, este último o agradece e exibe o status do pedido.
4.3. Ciclo de vida das transações
Em todos os seguintes esquemas, a legenda seguinte é adotada:
Ação do vendedor necessária - manual (Back Office) ou automática (serviço web)
Modo de validação automática
Ciclo de vida de uma transação de pagamento à vista
Na sequência da solicitação de pagamento, certos controles são automaticamente iniciados:
• A autentificação 3D Secure.
• Diferentes controles locais efetuados diretamente pela plataforma de pagamento (eles podem incluir
os controles vinculados a contratação do serviço adicional de controles antifraude).
• Uma solicitação de autorização é também efetuada no banco do comprador, no mesmo dia da data de
pagamento, seja qual for a data pedida de captura no banco.
Se um dos controles falha, a solicitação de pagamento é recusada. O comprador é informado da recusa.
No Back Office, pode consultar a transação com o status Recusado.
Caso contrário, o status da transação é Aguardando captura.
O comprador é informado se a solicitação de pagamento dele é aceita e recebe um e-mail de
confirmação. A transação será entregue automaticamente no dia pedido pelo vendedor.
Na espera desta captura , o vendedor pode mudar a data de captura assim como o valor (modificação
do valor somente para um valor menor, este caso corresponde a uma entrega parcial do vendedor).
Se for preciso, ele pode também cancelar a transação, que terá então o status Cancelado.
Ciclo de vida de uma transação de pagamento pré-datado
Prazo de captura menor que o tempo de validade da autorização
(ver diagrama ciclo de vida de uma transação de pagamento a vista).
Prazo de captura maior que o tempo de validade da autorização
Qualquer transação de pagamento pré-datado efetuada com o modo de validação automática, com uma
solicitação de autorização de 1 BRL efetuada com sucesso, pode ser consultada no Back Office com o status
Aguardando autorização.
A solicitação de autorização é efetuada automaticamente:
• processo padrão: o dia da data desejada de captura no banco,
• processo com autorização antecipada: em função do meio de pagamento selecionado, a D-X (ver
quadro ilustrando a validade de uma autorização) antes da data desejada de captura no banco.
O modo por autorização antecipada deve ser solicitado ao serviço de atendimento ao cliente.
No caso de uma recusa de tipo não frauduloso (ver quadro), a autorização será repetida todo dia até
D-2 antes da data de captura no banco.
Durante a espera, o vendedor pode cancelar a transação ou modificar o valor desta última (somente
para um valor menor) e/ou a data de captura.
O seguinte diagrama apresenta os diferentes status que podem ser tomados por este tipo de transação
(caso de uma solicitação que não foi lançada de novo):
Ciclo de vida de uma transação de pagamento parcelado
A primeira prestação do pagamento parcelado seguirá exatamente as mesmas regras que uma transação
de pagamento à vista ou uma transação de pagamento pré-datado em função da sua data de captura no
banco.
As seguintes parcelas são por padrão posicionadas no status Aguardando autorização. O banco do
comprador poderá recusar a solicitação de autorização. A plataforma de pagamento informará em seguida
por e-mail que a transação foi recusada.
As solicitações de autorização das seguintes parcelas são automaticamente efetuadas como para uma
transação de pagamento pré-datado, ou seja, com duas datas possíveis:
• processo padrão: o dia da data desejada de captura no banco,
• processo com autorização antecipada: em função do meio de pagamento selecionado, a D-X (ver
quadro ilustrando a validade de uma autorização) antes da data desejada de captura no banco.
As parcelas posteriores seguem o diagrama de status seguinte (caso de uma solicitação de autorização
que não foi lançada de novo):
O cancelamento de uma parcela não diz em nenhum caso que as seguintes parcelas a serem capturadas
no banco serão canceladas.
Modo de validação manual
Ciclo de vida de uma transação de pagamento à vista
Na seqüência da solicitação de pagamento, certos controles são automaticamente iniciados:
• A autentificação 3D Secure.
• Diferentes controles locais efetuados diretamente pela plataforma de pagamento (eles podem incluir
os controles vinculados a contratação do serviço adicional do controle dos riscos).
• Uma solicitação de autorização esta sendo efetuada no banco do comprador.
Se um dos controles falha, a solicitação de pagamento é recusada. O comprador é informado da recusa.
No Back Office, pode consultar a transação com o status Recusado.
Caso contrário o pagamento é aceito e a transação pode ser consultada no Back Office com o status A
Validar.
O vendedor deve então obrigatoriamente validar a transação antes da data de captura solicitada. Caso
contrário, a transação terá o status Expirado e não poderá mais ser capturada no banco.
Assim que uma transação for validada, terá o status Aguardando captura.
Pode também cancelar a transação se for necessário. A transação terá então o status Cancelado.
Ciclo de vida de uma transação de pagamento pré-datado
Prazo de captura menor que o tempo de validade da autorização
(ver diagrama ciclo de vida de uma transação de pagamento à vista).
Prazo de captura maior que o tempo de validade da autorização
Qualquer transação de pagamento pré-datado efetuada com o modo de validação manual, com uma
solicitação de autorização de 1 BRL efetuada com sucesso, pode ser consultada no Back Office com o status
A validar & a autorizar.
A solicitação de autorização é automaticamente efetuada no dia da captura no banco solicitada, sob
reserva que o vendedor tenha anteriormente validado a transação.
Enquanto espera a captura, o vendedor pode cancelar a transação ou modificar o valor desta última e/
ou a data de captura.
Estas transações seguem o diagrama de status seguinte:
Ciclo de vida de uma transação de pagamento parcelado
A primeira prestação do pagamento parcelado seguirá exatamente as mesmas regras que uma transação
de pagamento à vista ou uma transação de pagamento pré-datado, em função da data de captura no
banco solicitada.
As parcelas posteriores são por padrão posicionadas no status A validar & a autorizar enquanto a primeira
parcela não for validada pelo vendedor. A quitação destas últimas não esta garantida para o vendedor. De
fato, o banco do comprador pode recusar a solicitação de autorização.
A validação da 1a parcela vale como validação de todas as parcelas seguintes. Porém, o cancelamento
de uma parcela não vale cancelamento das parcelas posteriores.
Pontos específicos vinculados às autorizações antecipadas.
Para ativar as autorizações antecipadas, favor entrar em contato com o serviço de atendimento ao cliente
da plataforma de pagamento.
Este processo aplica-se somente para as solicitações de autorização:
• do pagamento pré-datado,
• das parcelas, que não seja a primeira, para um pagamento parcelado.
O inicio da autorização será efetuado a D-Δ (ver quadro ilustrando a validade de uma autorização para
cada meio de pagamento) antes da data de captura no banco desejada.
Se foi recusado pelo servidor de autorização do banco do comprador, exclusivamente por um motivo não
frauduloso (ver quadro), um processo retoma automaticamente as solicitações de autorização até D-2.
Se foi recusado por um motivo frauduloso, a transação é considerada como definitivamente recusada.
5. ESTABELECER O DIÁLOGO COM A PLATAFORMA DE
PAGAMENTO
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 do
comprador.
No final do pagamento, o resultado é enviado ao site de e-commerce de duas maneiras:
• automaticamente via notificações chamadas URL de notificação instantânea (também chamada IPN Instant Payment Notification), ver capítulo Configurar as notificações,
• pelo navegador quando o comprador clicar no botão voltar para o site de e-commerce , ver capítulo
Gerenciar o retorno para o site de e-commerce.
Para garantir a segurança das trocas, os dados são assinados com um certificado somente conhecido pelo
vendedor e pela plataforma de pagamento
5.1. Definir a URL da página de pagamento
O site de e-commerce comunica com a plataforma de pagamento redirecionando o comprador para a
página:
https://secure.payzen.com.br/vads-payment/
5.2. Identificar-se durante as trocas
Para dialogar com a plataforma de pagamento, o vendedor precisa de duas informações:
• Código da loja: permite identificar o site de e-commerce durante as trocas. Seu valor é enviado para
o campo vads_site_id.
• O certificado : permite calcular a assinatura numérica enviada para o campo assinatura.
Para resgatar estes valores:
1. Conecte-se ao seu Back Office : https://secure.payzen.com.br/vads-merchant/
2. Clique sobre Configuração> Loja.
3. Selecionar a aba Certificados
Figura 7 : Visualizar o código da loja e o certificado
Dois tipos de certificado são disponibilizados:
• O certificado de teste que permite gerar a assinatura de um formulário em modo de teste.
• O certificado de produção que permite gerar a assinatura de um formulário em modo de produção.
5.3. Escolher o modo de Teste ou de Produção
A escolha do modo de TESTE ou PRODUÇÃO realiza-se usando o campo vads_ctx_mode (Ver capítulo Criar
um formulário de pagamento).
• O modo TEST permite efetuar pagamentos de teste.
Esta sempre disponível, mesmo depois da criação do certificado de produção.
Se você esta criando um novo site de e-commerce (ou possui ambiente onde fatura), você poderá
realizar seus testes sem impacto para o site atualmente em funcionamento.
As transações de TEST estão disponíveis no Back Office no menu Gerenciador > Transações de TESTE
Figura 8 : Visualizar as transações de teste
• O modo PRODUÇÃO estará disponível apenas depois que o certificado de produção for criado (ver
capítulo Ativar a loja em modo de PRODUÇÃO ).
Ele permite efetuar pagamentos reais.
As transações de PRODUÇÃO estão disponíveis no Back Office no menu Gerenciador > Transações
Figura 9 : Visualizar as transações de produção
5.4. Gerenciar o diálogo com o site de e-commerce
A gestão do diálogo com o site de e-commerce é realizada graça a dois tipos de URL:
• Url de notificação instantânea, chamada IPN (Instant Payment Notification),
• Url de retornocom o site de e-commerce
Url de notificação instantânea, IPN (Instant Payment Notification)
A plataforma de pagamento notifica automaticamente o resultado do pagamento ao site de e-commerce
Os dados são enviados em modo POST.
A plataforma é capaz de entrar em contato com o site de e-commerce seja qual for o protocolo usado
(http ou https).
Para tratar essas notificações, o vendedor deve criar uma página no seu site que:
• analisa os dados recebidos em modo POST,
• garante a integridade das informações calculando a assinatura,
• verifica que não se trate de uma dupla notificação (reenvio da notificação desde o Back Office por
exemplo),
• inicia a atualização da sua base de dados (status do pedido, estoque, etc...),
• envia e-mails para o comprador (fatura, acompanhamento de pedido, etc...).
O tempo de processamento impacta diretamente o prazo para a visualização da página de resumo do
pagamento. Quanto mais o processamento demora, mais longo o tempo de espera antes de visualizar.
Para receber as notificações, o vendedor deve configurar as regras de notificações no seu Back Office (ver
capítulo Configurar as notificações).
Se houver problema de comunicação com o site de e-commerce, a plataforma de pagamento envia um email para o administrador da loja, destacando o motivo da falha (erro http. etc ...) bem como os passos a
seguir para enviar de novo a notificação desde o Back Office.
Url de retorno para o site de e-commerce
O vendedor pode configurar no Back Office as URL de retorno "padrões" desde o menu Configurações >
Loja > aba Configuração) :
Figura 10 : Especificações dos URL de retorno
Pode configurar uma URL de retorno para a loja diferente segundo o modo.
O padrão é que o comprador seja redirecionado para a URL de retorno, seja qual for o resultado.
Se por acaso nenhuma URL estiver configurada neste nível, então o redirecionamento usará a URL principal
da loja (campo URL definido no quadro Detalhes da loja).
O vendedor tem a possibilidade de sobrescrever esta configuração no seu formulário de pagamento (ver
capítulo Definir as URL de retorno ).
Observação:
O status da regra "URL de notificação instantânea no final do pagamento" (IPN) esta disponível nesta tela.
Se esta última não for configurada, favor configurá-la (ver capítulo Configurar as notificações).
5.5. Gerenciar a segurança
Diferentes meios são implementados para garantir a segurança das transações de pagamento em linha.
Gerenciar a segurança com a assinatura
A integridade das informações trocadas é garantida por uma troca de assinaturas numéricas entre a
plataforma de pagamento e o site de e-commerce.
O diálogo entre a plataforma de pagamento e o site de e-commerce realiza-se via submissão de formulários
HTML.
Um formulário contém uma lista de campos específicos (ver Criar um formulário de pagamento) usados
para calcular sua assinatura numérica (ver capítulo Calcular a assinatura).
O resultado deste cálculo deve ser enviado para o campo assinatura.
Usamos a função de fatiamento « SHA-1 » para encriptar a assinatura.
SHA-1 esta disponível na maioria das linguagens usadas para o desenvolvimento de aplicações Web.
Dependendo da linguagem escolhida, você poderá ter que codificar você mesmo as funções de fatiamento
SHA-1 (como em ASP por exemplo).
Para uma melhor compreensão, segue o resultado do SHA-1 do símbolo "a":
SHA1( " a ") = 86f7e437faa5a7fce15d1ddcb9eaeaea377667b8
Modelização dos mecanismos de segurança:
Figura 11 : Diagrama mecanismo de segurança
1. O site de e-commerce recupera os dados do formulário e calcula a assinatura.
2. O site de e-commerce submete o formulário para a plataforma.
3. A plataforma recupera os dados do formulário e calcula a assinatura.
4. A plataforma compara a assinatura calculada com a assinatura enviada pelo site de e-commerce.
5. Se as assinaturas são diferentes, a solicitação de pagamento é recusada.
Se não, a plataforma efetua o pagamento.
6. A plataforma recupera os dados do resultado e calcula a assinatura da resposta.
7. Segundo a configuração da boutique (ver capítulo Configurar as notificações), a plataforma submete
o resultado do pagamento ao site de e-commerce.
8. O site de e-commerce recupera os dados e calcula a assinatura. Ele compara a assinatura calculada
com a assinatura enviada pela plataforma.
9. Se as assinaturas são diferentes, o vendedor analisa a origem do erro (erro de cálculo, tentativa de
fraude etc...)
Se não, o site de e-commerce atualiza a sua base de dados (estado do estoque, estado do pedido etc...).
Guardar o certificado de produção
Assim que o primeiro pagamento foi efetuado com um cartão físico, o certificado de produção é oculto
por razões de segurança.
Aconselhamos fortemente guardar este certificado em um lugar seguro (arquivo criptografado, base de
dados etc...).
Em caso de perda, o vendedor terá a possibilidade de gerar um novo certificado desde seu Back Office.
Para lembrança, o certificado de produção esta disponível no Back Office no menu Configuração > Loja
> aba Certificados.
Gerenciar os dados sensíveis
Regras estritas regem as transações de pagamento online (Certificação PCI-DSS).
Como vendedor, você tem que ter certeza de nunca divulgar dados não criptografados que poderiam
passar por um número de cartão bancário. Seu formulário seria recusado (código 999 - Sensitive data
detected).
Evite particularmente os números de pedidos de um comprimento entre 13 e 16 símbolos numéricos e
começando por 3, 4 ou 5.
5.6. Utilizar uma i-frame
Um i-frame (in line frame) é usado para abrir uma página web em uma outra página web.
Exemplos de códigos:
<FRAMESET>
<FRAME SRC="https://secure.payzen.com.br/vads-payment/">
</FRAMESET>
<iframe src="https://secure.payzen.com.br/vads-payment/"></iframe>
5.7. Gerenciar as configurações da sua loja por arquivo de configuração
O uso dum arquivo de configuração evita introduzir valores em duro no código.
Os arquivos de configuração podem conter:
• a URL da página de pagamento,
• o valor do certificado,
• o código da loja,
• ...
Esses arquivos permitem digitar os dados a registrar.
O programa que gera o formulário de pagamento irá chamar o arquivo de configuração com a configuração
para usar o valor.
O vendedor debe assegurar que:
• o arquivo não pode ser acessível após o exterior.
• as especificidades da linguagem de programação utilizada são respeitadas.
Exemplo de arquivo de configuração "conf.txt":
vads_site_id = 11111111
TEST_key = 2222222222222222
PROD_key = 3333333333333333
vads_ctx_mode = TEST
Exemplo da chamada do arquivo de configuração no formulário de pagamento :
$conf_txt = parse_ini_file("conf.txt");
if ($conf_txt['vads_ctx_mode'] == "TEST") $conf_txt['key'] = $conf_txt['TEST_key'];
if ($conf_txt['vads_ctx_mode'] == "PRODUCTION") $conf_txt['key'] = $conf_txt['PROD_key'];
6. CONFIGURAR AS NOTIFICAÇÕES
O Back Office permite gerenciar os eventos que vão gerar uma chamada para o site de e-commerce e
configurar a URL da página que deve ser solicitada.
Os seguintes esquemas ilustram, para cada evento, o status da transação enviado na notificação.
A legenda escolhida para cada um é a seguinte:
Ação do vendedor necessária - manual (Back Office) ou automática (serviço web)
Ação do comprador
6.1. Notificações dos diferentes status para um pagamento a vista
Figura 12 : Diagrama de fluxo - Pagamento à vista
Evento
Status notificado
Nome da regra para ser configurada
O comprador desistiu
ABANDONED
URL de notificações sobre cancelamento
Cancelado pelo vendedor
CANCELED
URL de notificação sobre uma operação
proveniente do Back Office
Resposta ao pedido de autorização
AUTHORISED_TO_VALIDATE,
AUTHORISED, REFUSED
URL de notificações ao fim do
pagamento
Tabela 1 : Regras de notificação a ativar para um pagamento à vista
6.2. Notificações dos diferentes status para um pagamento pré-datado
Figura 13 : Diagrama de fluxo - Pagamento pré-datado
X : tempo de validade de autorização.
Evento
Status notificado
O comprador desistiu
ABANDONED
URL de notificações sobre
cancelamento
CANCELED
URL de notificação sobre uma
operação proveniente do Back Office
Validação pelo vendedor
WAITING_AUTHORISATION
operação proveniente do Back Office
Resposta à solicitação de
autorização de 1 BRL
REFUSED, WAITING_AUTHORISATION,
WAITING_AUTHORISATION_TO_VALIDATE
URL de notificação ao fim do
pagamento
Resposta ao pedido de
autorização
AUTHORISED, REFUSED,
AUTHORISED_TO_VALIDATE
autorização por lote
Tabela 2 : Regras de notificação a serem ativadas para um pagamento pré-datado
6.3. Notificações dos diferentes status para as parcelas de um pagamento
parcelado
Figura 14 : Diagrama de fluxo - Vencimentos de um pagamento parcelado
X : tempo de validade de autorização.
Evento
Status notificado
CANCELED
URL de notificação sobre uma operação
Resposta ao pedido de autorização
AUTHORISED, REFUSED
autorização por lote
Tabela 3 : Regras de notificação a serem ativadas para um pagamento parcelado
6.4. Configurar as notificações
Diversos tipos de notificações estão disponíveis no Back Office. Elas possibilitam gerenciar os eventos (o
comprador desistiu da compra, cancelamento pelo vendedor, validação pelo vendedor...) que gerarão uma
chamada para o site de e-commerce e configurar a URL da página a contatar.
Para acessar ao gerenciamento das regras de notificação:
1. Conecte-se a: https://secure.payzen.com.br/vads-merchant/.
2. Ir para o menu: Configuração > Regras de notificações.
Figura 15 : Regras de notificações
Configurar a notificação no final do pagamento
Esta notificação é imprescindível para comunicar o resultado de uma solicitação de pagamento.
Para configurar esta notificação:
1. Fazer um clique direito na linha URL de notificação no final do pagamento.
2. Selecionar Gerenciar a regra.
3. Informar a URL da sua página nos campos URL a ser chamada em modo TEST e URL a ser chamada
em modo PRODUÇÃO.
Figura 16 : URL de notificação no final do pagamento
4. Preencher o campo Endereço(s) de e-mail(s) para avisar em caso de falha.
5. Para especificar vários endereços e-mails, separa-los por um ponto e vírgula.
6. Configurar a Rechamada automática em caso de falha.
Esta opção permite enviar de novo e automaticamente a notificação para o site de e-commerce se
houver falha, até 4 vezes.
Para maiores informações, ver capítulo Ativar a rechamada automática
7. Salve suas modificações.
Se a plataforma não consegue entrar em contato com a URL da sua página, um e-mail é enviado para o
endereço especificado na etapa 6.
Contem:
• O código HTTP do erro encontrado
• Elementos de analise segundo o erro
• As suas consequências
• Os passos a seguir desde o Back Office para enviar de novo a solicitação para a URL.
Configurar a notificação do resultado final de um pagamento pré-datado
Esta notificação é imprescindível para comunicar o resultado de um pagamento pré-datado:
• Se o pagamento foi aceito.
• Se o pagamento foi recusado.
Permite ao site de e-commerce ser notificado quando há uma solicitação de autorização.
Exemplo
Para um pagamento pré-datado com prazo de 60 dias, a solicitação de autorização não é efetuada
durante o pagamento. O site e-commerce será contatado quando o pedido de autorização pela regra
URL de notificação sobre uma autorização por lote.
Esta regra esta desativada por padrão.
1. Fazer um clique direito na linha URL de notificação sobre uma autorização por lote.
3. Informar a URL de sua página nos campos URL para chamar em modo TEST e URL para chamar em
modo PRODUCTION.
Figura 17 : Configure a notificação sobre uma autorização por lote
4. Preencher o campo Endereço(s) de e-mail(s) para avisar se houver falha.
Para maiores informações, ver capítuloAtivar a rechamada automática
8. Ativar a regra, fazendo um clique direito em URL de notificação sobre uma autorização por lote e
selecione Ativar a regra.
Contem:
• o código HTTP do erro encontrado,
• elementos de análise em função do erro,
• os passos a seguir desde o Back Office para enviar de novo a solicitação para a URL definida na etapa 5.
Configurar a notificação se o comprador desiste ou cancela
A plataforma de pagamento pode notificar sistematicamente o site de e-commerce:
• Se o comprador desiste ou cancela, com o botão Cancelar e Voltar para a loja.
• Quando o comprador não finalizou o pagamento antes do fim da sessão de pagamento.
A tempo máximo de uma sessão de pagamento é de 10 minutos.
1. Fazer um clique direito na linha URL de notificações em cancelamento.
em modo PRODUÇÃO.
Para maiores informações, ver capítulo Ativar a re-chamada automática.
Contem:
• elementos de análise segundo o erro,
• os passos a seguir desde o Back Office para enviar de novo a solicitação para a URL definida a etapa 5.
Configurar a notificação em autorização por batch
A plataforma de pagamento pode notificar sistematicamente o site de e-commerce quando uma transação
com um status Para validar estiver vencida. O vencimento lança a notificação. O status Expirado é
definitivo.
Recomendamos ativar esta notificação para transações PayPal (modo Order) para que você seja notificado
da captura.
Esta regra esta desativada por padrão.
1. Fazer um clique direito na linha URL de notificação sobre uma modificação por lote.
em modo PRODUÇÃO.
Para maiores informações, ver capítulo Ativar a re-chamada automática.
8. Ativar a regra, fazendo um clique direito em URL de notificação sobre uma modificação por lote e
selecione Ativar a regra.
Contem:
• O código HTTP do erro encontrado
• Elementos de analise segundo o erro
• As suas consequências
• Os passos a seguir desde o Back Office para enviar de novo a solicitação para a URL.
6.5. Ativar a re-chamada automática
Esta opção permite enviar de novo e automaticamente a notificação para o site de e-commerce se houver
falha, até 4 vezes.
3. Fazer um clique direito sobre uma da regras de notificações.
Figura 18 : URL de notificação ao fim do pagamento
As tentativas de chamadas são programadas a horários fixos a cada 15 minutos (00, 15, 30, 45).
Após cada tentativa não sucedida, um e-mail de alerta é enviado para o endereço informado
anteriormente.
O e-mail enviado neste caso, inclui no seu objecto o número correspondente a tentativa de envio da
notificação. Apresenta-se como attempt # seguido do número de tentativa.
Exemplo do conteúdo do objecto dum e-mail recebido após o primeiro falho de notificação ao fim do
pagamento:
[MODE TEST] Minha loja - Tr. ref. 067925 / FALHO ao momento da chamada da sua URL de
notificação [unsuccessful attempt #1]
No caso de múltiplos falhos, o objecto do e-mail contem o número de tentativa.
Exemplo do objecto dum e-mail recebido após o segundo falho:
Exemplo do objecto dum e-mail recebido após o terceiro falho:
Para notificar ao site e-commerce o falho da última tentativa de notificação, o objecto dum e-mail
contem attempt #last.
Exemplo do objecto dum e-mail recebido após a última falho:
notificação [unsuccessful attempt #last]
Para cada um dos e-mails recebidos, o conteúdo do e-mail especificará:
• O problema encontrado
• Os elementos de analise segundo o erro,
• As conseqüências
• Os passos a seguir desde o Back Office para enviar de novo a solicitação para a URL definidos na
etapa 5 .
Observação:
Após a quarta tentativa, é sempre possível re-chamar a URL notificação. Isso pode ser feito
manualmente a partir de seu Back Office.
Atenção, durante a re-chamada automática, toda a chamada manual para a URL de notificação afeta
ao número de tentativas automáticas.
Observação:
Durante a re-chamada automática, alguma informação não é registrada no banco de dados ou é
modificada.
Exemplos de campos não disponível / não registrado no banco de dados:
• vads_page_action
• vads_payment_config
• vads_action_mode
Exemplos de campos enviados com valores diferentes:
• vads_url_check_src à RETRY,
• vads_trans_status. O status da transação após esta operação varia de acordo com o seu status no
momento da chamada à URL (ver capítulo Ciclo de vida das transações).
• vads_hash com um valor diferente de acordo com os novos valores,
• signature com um valor diferente de acordo com os novos valores.
6.6. Re-chamar manualmente a notificação
Esta opção permite volver a executar manualmente a URL de notificação a partir do Back Office quando
uma transação contem um erro.
1. Conecte-se a: https://secure.payzen.com.br/vads-merchant/
2. Pesquisar a transação para a qual deseja re-chamar manualmente a notificação.
3. Fazer um clique direito sobre a transação e selecionar Executar a URL de notificação.
Uma mensagem informará sobre a boa execução deste pedido se a sua aplicação está disponível.
Você pode, em qualquer caso, consultar o resultado de sua ação no histórico de eventos da operação
e, possivelmente, analisar mensagens de erro se o problema persiste.
Durante a re-chamada manual a partir do Back Office, alguma informação não é registrada no banco de
dados ou é modificada.
Exemplos de campos não disponível / não registrado no banco de dados:
Exemplos de campos enviados com valores diferentes:
• vads_url_check_src à BO,
• vads_trans_status. O status da transação após esta operação varia de acordo com o seu estado no
momento da chamada à URL (ver capítulo Ciclo de vida das transações).
• vads_hash com um valor diferente de acordo com os novos valores,
• signature com um valor diferente de acordo com os novos valores.
6.7. Configurar os e-mails enviados para o comprador
O Back-Office permite que o vendedor configure e-mails destinados ao comprador:
• E-mail de confirmação da assinatura.
• E-mail de confirmação de pagamento.
• E-mail de confirmação de cadastro.
Para configurar estes e-mails:
2. Ir para o menu: Configuração >Regras de notificações.
3. Selecione a aba E-mail enviado para o comprador.
4. Clique direito na denominação de um e-mail e selecione Ativar a regra.
Para personalizar um e-mail:
5. Clique direito na denominação de um e-mail que tenha a regra ativada e selecione Gerenciar a regra.
Três abas estão disponíveis.
• Configuração
Permite personalizar o e-mail que será enviadoa denominação da regra.
• Condições da regra
Permite criar uma lista (pode ser vazia) de condições de execução da regra (segundo o evento que
dispara). Uma condição é constituída de uma variável, de um operador de comparação e de um
valor de referência.
Exemplo "modo = TESTE", "valor superior a 1000". Quando uma regra for executada, o valor da
variável é resgatado e comparado com o valor de referência. Todas as condições devem ser validadas
para que a regra seja executada.
• Informações
Exibe um resumo da regra
6. Selecione a aba Configuração.
7. Personalizar o conteúdo do e-mail segundo suas necessidades.
a. Clique em E-mail enviado ao comprador para exibir o conteúdo do e-mail "padrão" comum a
todos os vendedores que utilizam a plataforma de pagamento.
b. Selecione a aba que corresponde ao idioma do e-mail que você deseja personalizar.
c. Clique em Personalizar os valores de texto padrão.
d. Modificar o texto do e-mail.
e. Clique em Opções Info Email para exibir a lista dos campos disponíveis para personalizar o e-mail.
f. Selecione os campos que você deseja incluir no e-mail. Um recapitulativo detalhado do
tratamento da solicitação será acrescentado ao conteúdo do e-mail.
8. Clique em Salvar.
6.8. Configurar os e-mails enviados para o vendedor
A plataforma de pagamento pode notificar o vendedor por padrão nos casos seguintes:
• E-mail de confirmação de pagamento
• E-mail de recusa de pagamento agendado
• E-mail de confirmação de cadastro cliente
• E-mail de recusa parcelas de pagamento em x vezes
• E-mail de confirmação da assinatura
• E-mail de re-geração do certificado
Para configurar estes e-mails:
3. Selecione a aba E-mail enviado para o vendedor.
4. Clique direito na denominação de um e-mail e selecione Ativar a regra.
Para personalizar um e-mail:
5. Clique direito na denominação de um e-mail que tenha a regra ativada e selecione Gerenciar a regra.
Três abas estão disponíveis.
• Configuração
Permite personalizar o e-mail que será enviado.
• Condições da regra
Permite criar uma lista (pode ser vazia) de condições de execução da regra (segundo o evento que
dispara). Uma condição é constituída de uma variável, de um operador de comparação e de um
valor de referência.
Exemplo "modo = TESTE", "valor superior a 1000". Quando uma regra for executada, o valor da
variável é resgatado e comparado com o valor de referência. Todas as condições devem ser validadas
para que a regra seja executada.
• Informações
Exibe um resumo da regra
6. Selecione a aba Configuração.
7. Personalizar o conteúdo do e-mail segundo suas necessidades.
a. Clique em Configuração geral para especificar o endereço e-mail para ser notificado e
opcionalmente, o gerente da empresa e/ou o contato técnico da empresa e/ou o gerente da loja.
b. Clique em Configuração e-mail para exibir o conteúdo do e-mail "padrão" comum a todos os
vendedores que utilizam a plataforma de pagamento.
c. Selecione a aba que corresponde ao idioma do e-mail que você deseja personalizar.
d. Clique em Personalizar os valores de texto padrão.
e. Modificar o texto do e-mail.
f. Clique em Opções Info Email para exibir a lista dos campos disponíveis para personalizar o e-mail.
g. Selecione os campos que você deseja incluir no e-mail. Um recapitulativo detalhado do
tratamento da solicitação será acrescentado ao conteúdo do e-mail.
Observação:
Para visualizar antes as modificações efetuadas, clique em Pre-visualizar o e-mail localizado em baixo
da caixa de diáloguo.
7. 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="assinatura" value="assinatura"/>
<input type="submit" name="pagar" value="Pagar"/>
</form>
Contém:
Os elementos técnicos seguintes:
• As marcas <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 dados
do formulário.
Os dados do formulário:
• O código da loja,
• As características do pagamento em função do caso de uso (ver capítulos seguintes),
• As informações complementares em função das suas necessidades (ver capítulo Usar funções
complementares ),
• A assinatura que garante a integridade do formulário (ver capítulo Calcular a assinatura).
Estes dados são acrescentados ao formulário usando a marca <input>:
<input type="hidden" name="parametro1" value="valor1" />
Para valorizar as marcas name e value , ver o capítulo Dicionário de dados .
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 plataforma
de pagamento. Caso contrário, o cálculo de assinatura estará errado e o formulário será recusado.
O botão Pagar vai permitir o envio dos dados :
Casos de uso são apresentados nos capítulos seguintes. Eles permitem montar um formulário de
pagamento segundo suas necessidades.
• Criar um pagamento imediato em dinheiro.
• Criar um pagamento adiado em dinheiro.
• Criar um pagamento em parcelas.
• Criar uma autorização sem captura.
7.1. Criar um pagamento à vista
Em modo de pagamento à vista, o comprador paga a totalidade da sua compra de uma vez.
O pagamento é entregue no banco o mesmo dia.
1. Informar a totalidade dos campos do quadro que segue para montar seu formulário de pagamento.
Nome do campo
Descrição
Valor
vads_site_id
Código da loja
Ex : 12345678
vads_ctx_mode
Modo de funcionamento
TEST ou PRODUCTION
vads_trans_id
Número da transação
Ex : 123456
vads_trans_date
Data e hora UTC do formulário de pagamento
Ex : 20140129130025
vads_amount
Valor do pagamento
Ex : 3000 para 30 BRL
vads_currency
Código da moeda usada para o pagamento
Ex : 986 para Real brasileiro
vads_action_mode
Modo de aquisição dos dados do cartão
INTERACTIVE
vads_page_action
Ação a ser realizada
PAYMENT
vads_version
Versão do protocolo de troca
V2
vads_payment_config
Tipo de pagamento
SINGLE
vads_capture_delay
Prazo antes da captura no banco
0
vads_validation_mode
Modo de validação
0 (Automático)
Tabela 4 : Lista dos campos - Pagamento à vista
2. Preencher o campo vads_payment_config à SINGLE.
3. Preencher o campo vads_capture_delay à 0.
4. Preencher o campo vads_validation_mode à 0 para validar automaticamente (o pagamento será
entregue automaticamente para o banco).
5. Acrescente os campos em opção em função das suas necessidades (ver capítulo Usar funções
complementares ),
6. Calcule o valor do campo signature usando a totalidade dos campos do seu formulário, com o nome
começando por vads_ (ver capítulo Calcular a assinatura).
Exemplo de formulário para o pagamento à vista:
<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="3000" />
<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=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="20140526101407" />
<input type="hidden" name="vads_trans_id" value="239848" />
<input type="hidden" name="vads_version" value="V2" />
<input type="hidden" name="signature" value="86b2a17b9a5fcefb6c0120c57b25ec86ad1704ee"/>
</form>
7.2. Criar um pagamento pré-datado
Um pagamento pré-datado é um pagamento que será debitado de um vez só e cuja captura no banco é
exatamente superior a 0 dia.
• Uma solicitação de autorização será efetuada para o valor global se o prazo de validade da autorização
é superior ou igual à duração de validade de uma solicitação de autorização (ver quadro).
• Uma solicitação de autorização de 1 BRL será efetuada se o prazo de validade da autorização é superior
à duração de validade de uma solicitação de autorização (ver quadro).
A solicitação de autorização para o valor global será efetuada a D-1 antes da data de apresentação no
banco.
Nome do campo
Descrição
Valor
vads_site_id
Código da loja
Ex : 12345678
vads_ctx_mode
TEST ou PRODUCTION
vads_trans_id
Ex : 123456
vads_trans_date
Ex : 20140129130025
vads_amount
Valor do pagamento (na sua menor unidade monetária)
vads_currency
vads_action_mode
INTERACTIVE
vads_page_action
PAYMENT
vads_version
V2
vads_payment_config
Tipo de pagamento
SINGLE
vads_capture_delay
> 0 Ex: 3
Modo de validação
0 (automático) ou 1 (manual)
Tabela 5 : Lista dos campos - Pagamento pré-datado
2. Preencher o campo vads_payment_config à SINGLE.
3. Preencher o campo vads_capture_delay com um valor superior a 0.
4. Preencher o campo vads_validation_mode à 0 para uma validação automática (o pagamento
será entregue automaticamente no banco) ou a 1 para uma validação manual (o pagamento será
entregue no banco após uma validação manual no Back Office).
complementares ).
Exemplo de formulário de pagamento pré-datado:
</form>
7.3. Criar um pagamento parcelado.
Este modo de pagamento permite ao vendedor oferecer uma facilidade de pagamento para o comprador.
O formulário de pagamento estabelece o número de parcelas e o intervalo que os separa.
A primeira parcela funciona da mesma forma que um pagamento à vista.
As seguintes parcelas funcionam da mesma forma que um pagamento pré-datado.
Atenção:
As regras de notificações devem ser ativadas. Ver capítulo Configurar as notificações.
Detalhes:
No dia do pagamento, o vendedor não é creditado da totalidade do valor e a garantia de pagamento não
pode ser aplicada nas parcelas futuras.
A data da última parcela não pode ser superior a 1 ano em relação à data de apresentação do formulário.
Caso contrário, uma mensagem de erro é exibida e o formulário será recusado.
1. Informar a totalidade dos campos presentes abaixo para montar seu formulário de pagamento.
Nome do campo
Descrição
Valor
vads_site_id
Código da loja
Ex : 12345678
vads_ctx_mode
TEST ou PRODUÇÃO
vads_trans_id
Ex : 123456
vads_trans_date
Ex : 20140129130025
vads_amount
vads_currency
vads_action_mode
INTERACTIVE
vads_page_action
PAYMENT
vads_version
V2
vads_payment_config
Tipo de pagamento
ver etapa 2.
vads_capture_delay
0
vads_validation_mode Modo de validação
0 (automático) ou 1 (manual)
Tabela 6 : Lista dos campos - Pagamento parcelado
2. Preencher o campo vads_payment_config respeitando a seguinte sintaxe:
• Valores e datas de parcelas fixas :
MULTI:first=1000;count=3; period=30 ou:
"first" corresponde o valor do pagamento (na sua menor unidade monetária) do primeiro
pagamento feito no dia do pagamento,
"count" representa o número total de parcelas,
"period" determina o intervalo entre cada parcela.
• Valores e datas de parcelas personalizadas :
MULTI_EXT:data1=valor1;data2=valor2;data3=valor3 ou:
data1=valor1 estabelece a data e o valor da primeira transferência.
Os valores são apresentados na menor unidade da moeda. A soma de todos os valores deve ser
igual ao valor do campovads_amount.
As datas são apresentadas no formato YYYYMMDD.
3. Preencher o campo vads_capture_delay a 0. O primeiro pagamento será entregue no banco o
mesmo dia.
4. Preencher o campo vads_validation_mode à 0 para uma validação automática (o pagamento será
entregue automaticamente no banco) ou a 1 para uma validação manual (operação manual efetuada
pelo Back Office).
O modo de validação se aplica para todas as parcelas.
complementares ).
Exemplo de formulário de pagamento parcelado (Valores e datas de parcelas fixas):
<input type="hidden" name="vads_payment_config" value="MULTI:first=1000;count=3;period=30"/>
<input type="hidden" name="signature" value= "180b93e173b16d90b47099482ce9ed05325b33bb"/>
<input type="submit" name="pagar" value="Pagar" />
</form>
Exemplo de formulário de pagamento parcelado (Valores e datas de parcelas fixas):
<input type="hidden" name="vads_payment_config" value="
MULTI_EXT:20140201=1000;20140301=1000;20140401=1000" />
</form>
7.4. Criar uma autorização sem captura
Este modo de pagamento permite garantir a validade dos dados do cartão do comprador sem fazer débito.
Se for preciso, o vendedor poderá aplicar um débito neste cartão do valor desejado usando a função
Duplicar pelo Back Office. Pour cela :
• o modo de validação manual é usado,
• o vendedor não deve validar manualmente as transações.
Nome do campo
Descrição
Valor
vads_site_id
Código da loja
Ex : 12345678
vads_ctx_mode
TEST ou PRODUCTION
vads_trans_id
Ex : 123456
vads_trans_date
Ex : 20140129130025
vads_amount
(para 1 BRL)
vads_currency
vads_action_mode
INTERACTIVE
vads_page_action
PAYMENT
vads_version
V2
vads_payment_config
Tipo de pagamento
SINGLE
vads_capture_delay
0
Modo de validação do pagamento
1
Tabela 7 : Lista dos campos - Autorização sem captura
2. Preencher o campo vads_amount com um valor baixo. Não vai prejudicar o limite do cartão.
3. Preencher o campo vads_validation_mode a 1.
complementares ).
Exemplo de formulário para uma autorização sem captura:
<input type="hidden" name="vads_validation_mode" value="1"/>
<input type="hidden" name="signature" value= "95338e879ea543a4dada12107a0c1c4d95ed3239"/>
<input type="submit" name="pagar" value="Pagar" />
</form>
8. USAR FUNÇÕES COMPLEMENTARES
Para ter um formulário personalizado e adaptado as suas necessidades, você pode usar funções
complementares dentre da lista abaixo:
• Configurar o modo de captura no banco (modo de validação)
• Enviar informações sobre o comprador (estado civil, endereço e-mail..)
• Enviar informações sobre a entrega (endereço...)
• Enviar informações sobre o pedido (referência, conteúdo do carrinho...)
• Ativar ou desativar 3D Secure
• Definir o contrato comercial que será usado para o pagamento
• Personalizar elementos da página de pagamento
• Sobrescrever a url de notificação instantânea (também chamada IPN)
• Gerenciar as URL de retorno para o site de e-commerce
• Ativar o retorno automático para o site de e-commerce no final do pagamento
• Efetuar um pagamento sem redirecionar o comprador para a página de pagamento
Estas funcionalidades são apresentadas nos capítulos seguintes. Estes capítulos vão ajudar a montar sem
dificuldades seu formulário de pagamento.
8.1. Definir o modo de captura no banco (automático / manual)
O vendedor pode configurar pelo Back Office como serão enviados os pagamentos para o banco (Menu
Configurações > Loja > aba Configuração) :
Figura 19 : Definir o modo de captura no banco
• Automático : Nenhuma ação necessária, os pagamentos são capturados no banco quando o prazo de
entrega vence.
• Manual : o vendedor deve obrigatoriamente validar cada pagamento pelo Back Office para que seja
capturado no banco, e isso, antes da data de captura desejada.
Toda transação que não foi validada no devido prazo é considerada como vencida e nunca será
capturada no banco.
Por padrão, o Back Office esta configurado para que todos os pagamentos sejam capturados
automaticamente no banco.
O vendedor pode sobrescrever esta configuração no seu formulário de pagamento.
Deverá implementar os critérios da sua escolha (status do estoque, prazo de reabastecimento, etc...)
para poder decidir se a transação deve ser capturada automaticamente no banco ou não.
1. Preencher a totalidade dos campos necessários a seu caso de uso (ver capítulo Gerar um formulário
de pagamento) para montar seu formulário de pagamento.
2. Preencher o campo vads_validation_mode para configurar o modo de captura no banco da
transação (manual ou automático).
Este campo será reenviado na resposta com o valor enviado no formulário.
Valor
Descrição
Ausente ou vazio
Toma o valor definido no Back Office.
0
Captura automática no banco.
1
Captura manual no banco.
Tabela 8 : Valores associados o campo vads_validation_mode
Exemplo de formulário de pagamento com definição do modo de captura no banco:
<input type="hidden" name="vads_action_mode" value="SILENT" />
<input type="hidden" name="vads_card_number" value="4970100000000000" />
<input type="hidden" name="vads_cvv" value="123" />
<input type="hidden" name="vads_expiry_month" value="5" />
<input type="hidden" name="vads_expiry_year" value="2017" />
<input type="hidden" name="vads_payment_cards" value="VISA" />
<input type="hidden" name="vads_validation_mode" value="1" />
</form>
Exemplo de formulário de pagamento com definição do modo de captura no banco em modo INTERACTIVE:
</form>
Observação:
Os campos requisitados variam segundo o modo de aquisição das informações do meio de
pagamento(SILENT ou INTERACTIVE).
Quando o campo vads_action_modeé valorizado a SILENT, as informações do meio de pagamento se
tornam obrigatórias.
8.2. Enviar os dados do comprador
O vendedor pode enviar informações sobre o comprador (endereço, e-mail, estado civil, número de
telefone etc...). Estes dados constituirão as informações para o faturamento.
Todos os dados que serão transmitidos via o formulário de pagamento serão exibidos no Back Office
quando consultar o detalhe da transação (aba Comprador).
1. Preencher a totalidade dos campos necessários ao seu caso de uso (ver capítulo Gerar um formulário
de pagamento). para montar seu formulário de pagamento.
2. Preencher os campos opcionais abaixo em função das suas necessidades.
Estes campos serão reenviados na resposta com o valor transmitido no formulário.
Nome do campo
Descrição
vads_cust_email
Endereço e-mail do comprado.
vads_cust_id
Referência do comprado no site de e-commerce.
vads_cust_title
Estado civil do comprador.
vads_cust_status
Status (PRIVADO: para pessoa física / EMPRESA para uma pessoa jurídica).
vads_cust_name
Desvalorizado. Use vads_cust_first_name e vads_cust_last_name.
vads_cust_first_name
Nome
vads_cust_last_name
Sobrenome
Razão social do comprador.
vads_cust_cell_phone
Número de telefone celular.
vads_cust_phone
Número de telefone.
vads_cust_address_number
Número de rua.
vads_cust_address
Caixa postal.
vads_cust_district
Bairro.
vads_cust_zip
CEP.
vads_cust_city
Cidade.
vads_cust_state
UF / Região.
vads_cust_country
Código país segundo a norma ISO 3166 .
Tabela 9 : Lista dos campos - Detalhes do comprador
8.3. Enviar os dados de entrega
O vendedor pode enviar os dados de entrega do comprador (endereço, estado civil, número de telefone
etc...).
Estes dados serão exibidos no Back Office quando consultar o detalhe da transação (aba Entrega).
2. Preencher os campos opcionais abaixo em função das suas necessidades.
Estes campos serão reenviados na resposta com o valor transmitido no formulário.
Nome do campo
Descrição
vads_ship_to_status
Status (PRIVADO: para pessoa física / EMPRESA para uma pessoa jurídica).
vads_ship_to_name
Desvalorizado. Sobrenome do comprador. Use vads_ship_to_first_name e
vads_ship_to_last_name.
vads_ship_to_first_name
Nome
vads_ship_to_last_name
Sobrenome
Razão social.
vads_ship_to_phone_num
vads_ship_to_street_number
Número de rua.
vads_ship_to_street
Caixa postal.
Segunda linha do endereço.
vads_ship_to_district
Bairro.
vads_ship_to_zip
CEP.
vads_ship_to_city
Cidade.
vads_ship_to_state
UF / Região.
vads_ship_to_country
Código país segundo a norma ISO 3166
Tabela 10 : Lista dos campos - Detalhes de entrega
Exemplo de formulário de pagamento com informações sobre a entrega
<input type="hidden" name="vads_ship_to_city" value="[...]" />
<input type="hidden" name="vads_ship_to_country" value=BR />
<input type="hidden" name="vads_ship_to_name" value="[...]" />
<input type="hidden" name="vads_ship_to_street" value="[...]" />
<input type="hidden" name="vads_ship_to_street_number" value="10" />
<input type="hidden" name="vads_ship_to_zip" value="[...]" />
<input type="hidden" name="signature" value="52a8c87ec10b35e6fd1769e7189c26a6e279566e"/>
</form>
8.4. Enviar os dados do pedido
O vendedor pode mencionar no formulário de pagamento dele se ele deseja enviar as informações do
pedido (número de pedido, descrição, conteúdo do carrinho etc...).
Estes dados serão exibidos no Back Office quando consultar o detalhe da transação (aba Carrinho).
2. Preencher os campos opcionais abaixo em função das suas necessidades. Estes campos serão
reenviados na resposta com o valor transmitido no formulário.
Nome do campo
Descrição
vads_order_id
Número de pedido.
vads_order_info
Descrição do pedido.
vads_order_info2
vads_order_info3
vads_nb_products
Quantidade de artigos.
vads_product_labelN
Denominação do artigo. N corresponde ao índice do artigo (0 para o primeiro, 1 para o
segundo...).
vads_product_amountN
Valor do artigo. N corresponde ao índice do artigo (0 para o primeiro, 1 para o segundo...).
vads_product_typeN
Tipo do artigo. N corresponde ao índice do artigo (0 para o primeiro, 1 para o segundo...).
vads_product_refN
Referência do artigo. N corresponde ao índice do artigo (0 para o primeiro, 1 para o
segundo...).
vads_product_qtyN
Quantidade de artigo. N corresponde ao índice do artigo (0 para o primeiro, 1 para o
segundo...).
Tabela 11 : Lista dos campos - Detalhes do pedido
3. Preencher o campo vads_nb_products com a quantidade de artigos contidos no carrinho.
Observação:
Este campo é obrigatório para que o carrinho seja levada em conta.
4. Preencher o campo vads_product_amountN com o valor dos diferentes artigos contidos no carrinho
na menor unidade da moeda.
0 corresponde ao índice do artigo (0 para o primeiro, 1 para o segundo...).
5. Preencher o campo vads_product_typeN com o valor correspondente ao tipo do artigo.
Valor
Descrição
FOOD_AND_GROCERY
Produtos alimentares e de mercadinho
AUTOMOTIVE
Automóveis / Motos
ENTERTAINMENT
Entretenimento / Cultura
HOME_AND_GARDEN
Casa e jardim
HOME_APPLIANCE
Equipamentos para a casa
AUCTION_AND_GROUP_BUYING
Leilões e compras em grupo
FLOWERS_AND_GIFTS|
Flores e presentes
COMPUTER_AND_SOFTWARE
Computadores e softwares
HEALTH_AND_BEAUTY
Saúde e beleza
SERVICE_FOR_INDIVIDUAL
Serviços para pessoa física
SERVICE_FOR_BUSINESS
Serviços para pessoa jurídica
SPORTS
Esportes
CLOTHING_AND_ACCESSORIES
Roupas e acessórios
TRAVEL
Viagem
HOME_AUDIO_PHOTO_VIDEO
Som, imagem e vídeo
Valor
Descrição
TELEPHONY
Telefonia
Tabela 12 : Valores associados a vads_product-type0
6. Preencher o campo vads_product_labelN com a denominação dos artigos contidos no carrinho.
7. Preencher o campo vads_product_qtyN com a quantidade de cada um dos artigos contidos no
carrinho.
8. Preencher o campo vads_product_refN com a referência de cada um dos artigos contidos no
carrinho.
9. Verificar o valor do campo vads_amount. Deve corresponder ao valor total do pedido.
10.Calcule o valor do campo signature usando a totalidade dos campos do seu formulário, com o nome
8.5. Ativar / Desativar 3D Secure
Para esta funcionalidade precisa ativar a opção 3D Secure seletivo
O vendedor pode indicar no formulário de pagamento dele se ele deseja ativar ou desativar o
funcionalidade 3D Secure.
Deverá implementar os critérios da sua escolha (valor, país, região de entrega etc...) para poder decidir se
a transação deve ser submetida ou não ao 3DS.
2. Preencher o campo vads_threeds_mpi para ativar ou desativar 3D Secure.
Valor
Descrição
ausente
ou vazio
Autentificação 3DS gerada pela plataforma de pagamento (configuração do vendedor).
0
1
Autentificação 3DS integralmente gerada pelo vendedor somente se vads_card_number foi preenchido
(digitação dos dados cartões no site do vendedor).
Os dados que resultam da autentificação 3D Secure efetuada pelo MPI do vendedor devem agora ser
enviados para os campos do formulário previstos para isso (vads_threeds_enrolled, vads_threeds_cavv,
vads_threeds_eci, vads_threeds_xid, vads_threeds_ cavvAlgorithm, vads_threeds_status).
2
Autentificação 3DS desativada para a transação, seja qual for a configuração padrão do vendedor.
Exemplo de ativação do 3DS em função do valor:
if (vads_amount < 300 BRL){
then vads_threeds_mpi = 2 // 3DS disabled
else vads_threeds_mpi = 0 // 3DS enabled
}
Exemplo de ativação do 3DS em função da região:
if (vads_cust_zip = 92 ) or (vads_cust_zip = 93 ){
then vads_threeds_mpi = 0 // 3DS enabled
else vads_threeds_mpi = 2 // 3DS disabled
}
Exemplo de formulário de pagamento com o 3DS desativado:
<input type="hidden" name="vads_threeds_mpi" value="2" />
<input type="hidden" name="signature" value="7896adcaaf7336839030db9715afa12353313f42"/>
</form>
8.6. Definir o contrato comercial
O vendedor pode especificar no formulário de pagamento dele o valor do contrato comercial que será
usado.
Esta funcionalidade é útil somente se você possui vários contratos numa mesma rede de aceitação.
2. Preencher o campo facultativo vads_contracts para definir o contrato comercial usado.
Exemplo
Valor
Descrição
Ausente ou vazio
Uso do contrato definido por ordem de prioridade no Back
Office (Menu Configuração > Loja > aba Contratos).
VISA=1231231
Comprador VISA
MASTERCARD=2323123
Comprador MASTERCARD
AMEX=949400444000
Rede American Express
Para definir uma lista de contratos, separe os valores por um ponto e virgula ";".
Exemplo
Você tem a disposição:
• dois contratos VISA : 1231230 e 1231231
• dois contratos AMEX : 949400444000 e 949400444001
Para escolher o contrato que será usado para estas duas redes, vads_contracts deverá ser valorizado da
maneira seguinte: vads_contracts=VISA=1231231;AMEX=949400444000
Exemplo de formulário de pagamento definindo o contrato comercial usado:
<input type="hidden" name="vads_contracts" value="VISA=1231231;AMEX=949400444000" />
<input type="hidden" name="signature" value="7896adcaaf7336839030db9715afa12353313f42"/>
</form>
8.7. Gerenciar o retorno para o site de e-commerce
No final do pagamento, o comprador tem a possibilidade de voltar para o site de e-commerce em uma
página chamada URL de retorno.
Não confundir com a URL de notificação instantânea (também chamada IPN) (ver capítulo Gerenciar o
dialogo para o site de e-commerce).
Definir os URL de retorno
No formulário de pagamento, o vendedor pode sobrescrever a configuração do Back Office. Para isso ele
pode:
• Usar 4 URL diferentes em função do resultado do pagamento:
• Pagamento aceito.
• Pagamento recusado.
• Desistiu do pagamento.
• Erro de pagamento.
• Usar somente uma URL seja qual for o resultado do pagamento.
Definir as URL de retorno em função do resultado do pagamento:
2. Preencher os campos facultativos apresentados no quando abaixo para elaborar o formulário de
pagamento adaptado as suas necessidades.
Se nenhuma URL for informada no formulário, o valor configurado no Back Office será selecionado.
Nome do campo
Descrição
vads_url_success
URL para qual será redirecionado o comprador, se o pagamento for aceito, depois clique
em "voltar para a loja"
vads_url_refused
URL para qual será redirecionado o comprador, se o pagamento for recusado, depois clique
em "voltar para a loja".
vads_url_cancel
URL para qual será redirecionado o comprador depois de clicar em "cancelar e voltar para
a loja" antes de ter efetuado o pagamento.
vads_url_error
URL para qual será redirecionado o comprador em caso de erro de tratamento pela
plataforma de pagamento.
começando porvads_ (ver capítulo Calcular a assinatura).
Exemplo de formulário de pagamento com definição de URL de retorno em função do resultado do
pagamento:
<input type="hidden" name="vads_url_cancel" value="http://demo.com/cancel.php" />
<input type="hidden" name="vads_url_error" value="http://demo.com/error.php" />
<input type="hidden" name="vads_url_refused" value="http://demo.com/refused.php" />
<input type="hidden" name="vads_url_success" value="http://demo.com/success.php" />
</form>
Definir uma URL de retorno única seja qual for o resultado do pagamento:
2. Preencher o campo facultativo vads_url_return para definir a URL de redirecionamento no final do
pagamento.
Se nenhuma URL for informada no formulário, o valor configurado no Back Office será selecionado.
Exemplo de formulário de pagamento com uma URL de retorno única seja qual for o resultado do
pagamento:
<input type="hidden" name="vads_url_return" value="http://demo.com/return.php" />
</form>
Definir o método de recepção dos dados
Por padrão, o site de e-commerce não recebe nenhum parâmetro.
Para recuperar informações na página de retorno (tracking, estatísticas, personalização das mensagens
para o comprador, etc..), o vendedor pode sobrescrever esta configuração no formulário de pagamento
dele.
2. Utilize o campo opcional vads_return_mode para indicar o método de envio dos dados para o site de
e-commerce.
Valor
Descrição
Absent, vide ou NONE
Nenhum dado é transmitido à URL de retorno.
GET
Os dados são transmitidos na URL da página de retorno
POST
Os dados são enviados para a página de retorno sob a forma de um formulário HTTP POST.
O método GET permite evitar a exibição de uma mensagem de alerta quando o retorno é feito num
ambiente não seguro (http).
Exemplo de formulário de pagamento com definição do modo de envio dos dados:
<input type="hidden" name="vads_return_mode" value="GET" />
</form>
8.8. Ativar o retorno automático para o site de e-commerce
O vendedor pode mencionar no seu formulário se ele deseja redirecionar automaticamente o comprador
para o site de e-commerce no final do pagamento.
Se você usar um código de tracking (Google Analytics ou outro) no seu site, você deve implementar esta
funcionalidade.
2. Utilize os campos opcionais abaixo em função das suas necessidades.
Nome do campo
Descrição
vads_redirect_success_timeout
Estabelece o prazo de espera antes do redirecionamento depois de um
pagamento aceito.
Este prazo é apresentado em segundo e deve ser entre 0 e 300 segundos.
vads_redirect_success_message
Estabelece a mensagem de espera antes do redirecionamento depois de um
pagamento aceito.
vads_redirect_error_timeout
Estabelece o prazo de espera antes do redirecionamento depois de um
pagamento recusado.
Este prazo é apresentado em segundo e deve ser entre 0 e 300 segundos.
vads_redirect_error_message
Estabelece a mensagem de espera antes do redirecionamento depois de um
pagamento recusado.
Tabela 13 : Lista dos campos facultativos disponíveis.
3. Preencher o campo vads_return_mode aGET.
Exemplo de formulário de pagamento:
<input type="hidden" name="vads_redirect_error_message" value="Vous allez être redirigé vers
votre site marchand" />
<input type="hidden" name="vads_redirect_error_timeout" value="0" />
<input type="hidden" name="vads_redirect_success_message" value="Vous allez être redirigé vers
votre site marchand" />
<input type="hidden" name="vads_redirect_success_timeout" value="0" />
<input type="hidden" name="vads_return_mode" value="GET" />
</form>
8.9. Personalizar a página de pagamento
Você pode personalizar alguns elementos da página de pagamento:
• os meios de pagamento propostos na hora do pagamento,
• o idioma usado nas páginas de pagamento exibidas,
• os idiomas propostos para o comprador nas páginas de pagamento (bandeiras),
• o nome e a url da loja,
• a denominação do botão Voltar para a loja.
Ativando a opção personalização avançada, você poderá modificar a página de pagamento para que ela
seja parecida com seu site de e-commerce. Isso deixará o comprador mais seguro e mais confiante quando
ele for redirecionado para realizar o pagamento.Favor consultar o "manual de usuário de personalização
avançada disponível no site de documentoshttps://payzen-io/pt-BR/.
Gerenciar os meios de pagamento propostos ao comprador
E possível personalizar os meios de pagamento que você deseja propor ao comprador.
2. Valorizar o campo vads_payment_cards utilizando o quadro abaixo.
• com um valor só se você não deseja exibir a página de seleção dos meios de pagamento.
• com uma lista de valores separados por um ";" para exibir a página de seleção dos meios de
pagamento.
Valor
Descrição
AMEX
American Express
AURA
Aura
BANCODOBRASIL_IB
Banco Do Brasil Internet Banking
BANRISUL_IB
Banrisul
BOLETO
Boleto
BRADESCO_IB
Bradesco Internet Banking
CIELO_ELO
Elo
DINERS
Diners
DISCOVER
Discover
E_SITEF
E_SITEF
HIPERCARD
Hipercard
ITAU_IB
Itau Internet Banking
Para o meio de pagamento Itau Internet Banking,
vads_payment_cards deve ser preencher a ITAU_IB. Se o
campo estiver vazio, o pagamento é cancelado
JCB
Jcb
MAESTRO
Maestro
MASTERCARD
MasterCard
VISA
Visa
VISA_ELECTRON
Visa Electron
Exemplo de formulário de pagamento com lista de escolha de meios de pagamento:
<input type="hidden" name="vads_payment_cards" value="VISA;MASTERCARD;" />
<input type="hidden" name="signature" value=""/>
</form>
Mudar o idioma
Você pode personalizar o idioma usado nas páginas de pagamento.
2. Preencher o campo vads_languagecom um dos valores presentes no quadro abaixo :
Idioma
Codificação ISO 639-1
Alemão
de
Inglês
en
Chinês
zh
Espanhol
es
Francês
fr
Italiano
it
Japonês
ja
Holandês
nl
Polonês
pl
Português
pt
Russo
ru
Sueco
sv
Turco
tr
• Se o valor do campo vads_language esta errado, o formulário será recusado.
• Se o campo não for enviado ou se ele permanecer vazio, a página de pagamento será exibida no
idioma do navegador do comprador.
• O comprador poderá a qualquer momento mudar de idioma clicando nas bandeiras presentes em
baixo da página de pagamento.
Exemplo de formulário de pagamento com lista de escolha de idiomas:
<input type="hidden" name="vads_language" value="fr;en" />
</form>
Modificar os idiomas propostos ao comprador
Você pode personalizar os idiomas propostos ao comprador.
O último idioma selecionado pelo comprador será o idioma padrão do e-mail de confirmação de
pagamento enviado para o comprador.
2. Preencher o campo vads_available_languages usando o quadro abaixo:
• com um valor só se você não deseja que o comprador mude de idioma.
• com uma lista de valores separados por um « ; » para listar os idiomas disponíveis.
Idioma
Valor
Bandeira exibida por padrão
Alemão
de
x
Inglês
en
x
Chinês
zh
x
Espanhol
es
x
Francês
fr
x
Italiano
it
x
Japonês
ja
x
Holandês
nl
x
Polonês
pl
Português
pt
x
Russo
ru
x
Sueco
sv
x
Turco
tr
x
Se o valor do campo vads_available_languages esta errado, o formulário será recusado.
Exemplo de formulário de pagamento com lista de escolha de idiomas:
<input type="hidden" name="vads_available_languages" value="fr;en" />
</form>
Mudar o nome e a URL da loja
Se você possui dois nomes de domínios, você pode mudar o nome e a URL da loja para exibir o nome do
domínio.
2. Preencher o campo vads_shop_name para sobrescrever o nome da loja exibido na página de
pagamento.
Este valor será mencionado no ticket de transação assim como no e-mail de confirmação.
3. Preencher o campo vads_shop_url para mudar a URL da loja exibida nas páginas de pagamento.
Este valor será mencionado no e-mail de confirmação.
Se o valor do campo vads_shop_url esta errado, o formulário não será recusado. Porém, o valor será
usado pelo 3D Secure O pagamento poderá ser recusado se a URL não é valida.
Exemplo de formulário de pagamento com modificação do nome e da URL da loja:
<input type="hidden" name="vads_shop_name" value="Ma Boutique" />
<input type="hidden" name="vads_shop_url" value="http://www.maboutique.fr" />
</form>
Mudar a denominação do botão "Voltar para a loja".
Você pode personalizar o texto «Voltar para a loja ».
2. Use o campo vads_theme_config para mudar a denominação dos botões "Voltar para a loja".
3. Use a palavra chave SUCCESS_FOOTER_MSG_RETURN para mudar a denominação do botão "Voltar
para a loja" exibido se o pagamento for aceito.
4. Use a palavra chave CANCEL_FOOTER_MSG_RETURN para mudar a denominação do botão "Cancelar
e voltar para a loja" nas diferentes páginas de pagamento.
Ativando a opção personalização avançada, você poderá mudar denominações (exemplo: loja) exibidos
na página de pagamento. Consulte o "manual do usuário de personalização avançada" disponível no site
documentaçõeshttps://payzen-io/pt-BR/.
Exemplo de formulário de pagamento que muda a denominação do botão "Voltar para a loja".
<input type="hidden" name="vads_order_id" value="CD100000858" />
<input type="hidden" name="vads_theme_config"
value="CANCEL_FOOTER_MSG_RETURN=Cancelar;SUCCESS_FOOTER_MSG_RETURN=Retorno" />
<input type="hidden" name="signature" value=" a88c7380d165e49d5cb61c3408e0800c697b03fd "/>
</form>
8.10. Sobrescrever a URL de notificação instantânea (IPN)
Você pode sobrescrever a url de notificação instantânea (também chamada IPN) no formulário se você usa
uma só loja para diferentes canais de venda, diferentes tipologias de pagamento, diferentes idiomas etc...
Esta funcionalidade não é compatível com a execução, pelo Back Office, da solicitação enviada à url de
notificação instantânea. A URL chamada será a mesma que foi configurada na regra de notificação (ver
capítulo Configurar as notificações).
2. Preencher o campo vads_url_check para sobrescrever a URL da página que será notificada.
Se o valor do campo vads_url_check esta errado, o formulário será recusado.
Exemplo de formulário de pagamento que sobrecarrega a URL de notificação instantânea:
<input type="hidden" name="vads_url_check" value="http://www.maboutique.fr/check" />
</form>
8.11. Criar um pagamento sem redirecionar para a página de pagamento
Para esta funcionalidade precisa contratar e ativar a opção Aquisição dos dados bancários.
Neste modo, a aquisição dos dados bancários vai ocorrer no site do vendedor.
Esta funcionalidade:
• esta disponível se o seu banco autoriza digitar informações bancários no site de e-commerce.
• requer no mínimo o uso de um certificado SSL no site de e-commerce.
• não permite efetuar um pagamento com a autenticação 3D Secure.
Esta funcionalidade não funciona para os pagamentos com redirecionamento, tais como:
• PayPal, PayPal sandbox
1. Informar os campos presentes abaixo para montar seu formulário de pagamento.
Nome do campo
Descrição
Valor
vads_site_id
Código da loja
Ex : 12345678
vads_ctx_mode
TEST ou PRODUCTION
vads_trans_id
Ex : 123456
vads_trans_date
Ex : 20140129130025
vads_amount
Valor do pagamento
vads_currency
vads_action_mode
SILENT
vads_page_action
PAYMENT
vads_version
V2
vads_payment_config
Tipo de pagamento
SINGLE
vads_capture_delay
0
vads_payment_cards
Rede do cartão
Ex : VISA
vads_card_number
Número de cartão usado para o pagamento.
Ex : 4970100000000000
vads_cvv
Criptograma visual
Ex : 123
vads_expiry_month
Mês de vencimento do cartão
Ex : 2
vads_expiry_year
Ano de vencimento
Ex : 2023
Tabela 14 : Lista dos campos - Pagamento sem redirecionar para a página de pagamento
2. Preencher os campos vads_payment_config e vads_capture_delay em função das suas necessidades.
3. Preencher o campo vads_action_mode aSILENT.
4. Preencher os campos vads_card_number,vads_expiry_month, vads_expiry_year, vads_cvv com as
informações de cartão digitadas pelo comprador.
5. Preencher o campo vads_payment_cards em função da escolha do comprador usando o quadro
abaixo :
Valor
Descrição
AMEX
American Express
AURA
Aura
BANCODOBRASIL_IB
BANRISUL_IB
Banrisul
BOLETO
Boleto
BRADESCO_IB
CIELO_ELO
Elo
DINERS
Diners
DISCOVER
Discover
E_SITEF
E_SITEF
HIPERCARD
Hipercard
ITAU_IB
Para o meio de pagamento Itau Internet Banking,
vads_payment_cards deve ser preencher a ITAU_IB. Se o
campo estiver vazio, o pagamento é cancelado
JCB
Jcb
MAESTRO
Maestro
MASTERCARD
MasterCard
VISA
Visa
VISA_ELECTRON
Visa Electron
complementares ).
Exemplo de formulário de pagamento sem redirecionar para a página de pagamento:
<input type="hidden" name="vads_action_mode" value="SILENT" />
<input type="hidden" name="vads_card_number" value="4970100000000000" />
<input type="hidden" name="vads_cvv" value="123" />
<input type="hidden" name="vads_expiry_month" value="5" />
<input type="hidden" name="vads_expiry_year" value="2017" />
<input type="hidden" name="vads_payment_cards" value="VISA" />
</form>
9. CALCULAR A ASSINATURA
Para calcular a assinatura você deve completar todos os campos com o nome começando por vads_ et do
certificado (o valor do certificado permite calcular a assinatura numérica.).
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 tenham o código UTF-8.
3. Separe os valores dos campos com o símbolo "+".
4. Concatene o resultado com o certificado de teste ou de produção, separando-os com o símbolo "+".
5. Aplicar o algoritmo SHA-1 para ter o valor da assinatura.
Exemplos de parâmetros enviados para a plataforma de pagamento:
<input type="hidden" name="vads_currency" value=value="986" />
<input type="hidden" name="signature" value="606b369759fac4f0864144c803c73676cbe470ff"/>
</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_amount
• vads_ctx_mode
• vads_currency
• vads_site_id
• vads_trans_date
• vads_trans_id
• vads_version
2. Concatene o valor dos campos com o símbolo "+" :
INTERACTIVE+1524+TEST+PAYMENT+SINGLE+12345678+20090501193530+654321+V2
3. Acrescente o valor do certificado de teste no final da string separando-a com o símbolo "+"). Neste
exemplo, o certificado de teste é 1122334455667788 :
INTERACTIVE+1524+TEST+986+PAYMENT+SINGLE
+12345678+20090501193530+654321+V2+1122334455667788
4. Aplique o algoritmo SHA-1 na corrente formada.
O resultado a ser enviado no campo de assinatura é: 606b369759fac4f0864144c803c73676cbe470ff.
9.1. Exemplo de implementação em JAVA
Definição da classe utilitária Sha que terá o que for necessário ao tratamento do algoritmo SHA1.
import java.security.MessageDigest;
import java.security.SecureRandom;
public class Sha {
static public final String SEPARATOR = "+" ;
public static String encode(String src) {
try {
MessageDigest md;
md = MessageDigest.getInstance( "SHA-1" );
byte bytes[] = src.getBytes( "UTF-8" );
md.update(bytes, 0, bytes. length );
byte[] sha1hash = md.digest();
return convertToHex(sha1hash);
} catch(Exception e) {
throw new RuntimeException(e);
}
}
private static String convertToHex(byte[] sha1hash) {
StringBuilder builder = new StringBuilder();
for (int i = 0; i < sha1hash. length ; i++) {
byte c = sha1hash[i];
addHex(builder, (c >> 4) & 0xf);
addHex(builder, c & 0xf);
}
return builder.toString();
}
private static void addHex(StringBuilder builder, int c) {
if (c < 10)
builder.append((char) (c + '0' ));
else
builder.append((char) (c + 'a' - 10));
}
}
Função que calcula a assinatura:
public
ActionForward performCheck(ActionMapping actionMapping, Basivoirorm form,
HttpServletRequest request, HttpServletResponse response){
SortedSet<String> vadsFields = new TreeSet<String>();
Enumeration<String> paramNames = request.getParameterNames();
// take and sort the fields starting with vads_* alphabetically
while (paramNames.hasMoreElements()) {
String paramName = paramNames.nextElement();
if (paramName.startsWith( "vads_" )) {
vadsFields.add(paramName);
}
}
// Compute the signature
String sep = Sha.SEPARATOR;
StringBuilder sb = new StringBuilder();
for (String vadsParamName : vadsFields) {
String vadsParamValue = request.getParameter(vadsParamName);
if (vadsParamValue != null) {
sb.append(vadsParamValue);
}
sb.append(sep);
}
sb.append( shaKey );
String c_sign = Sha.encode(sb.toString());
return c_sign;}
9.2. Exemplo de implementação em PHP
// Function that calculate the signature
// $params : table containing the fields to send to the form
function getSignature($params){
//Initialization of the variable that will contain the string to encrypt
$signature_content = "" ;
// sort field alphabetically( $params );
foreach ( $params as $nom => $value )
{
// Recovery of vads_ fields
if (substr($nom,0,5) == 'vads_') {
// Concatenation with "+"
$signature_content .= $value . "+" ;
}
// Adding the certificate at the end
$signature_content .= $key ;
// Applying SHA-1 algorythm
$signature = sha1( $signature_content );
return $signature ;
}
10. ENVIAR A SOLICITAÇÃO DE PAGAMENTO
Para cada transação, o comprador deve ser redirecionado para a página de pagamento para finalizar o
pagamento.
O navegador dele deve enviar os dados do formulário de pagamento.
10.1. Redirecionar o comprador para a página de pagamento
A URL da plataforma de pagamento é a seguinte:
https://secure.payzen.com.br/vads-payment/
Exemplos de parâmetros enviados para a plataforma de pagamento:
<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]" />
</form>
10.2. Gerenciar os erros
Se a plataforma detecta uma anomalia quando recebe o formulário, uma mensagem de erro aparece 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 a FAQ - Perguntas mais frequentes
para ajudar a corrigi-la.
Em modo de PRODUÇÃO
A mensagem avisa o comprador que um problema técnico ocorreu.
Em ambos os casos, o vendedor recebe um e-mail de alerta.
Contem:
• a origem do erro
• um link para a FAQ - Perguntas mais frequentes para facilitar o diagnóstico
• todos os campos presentes no formulário.
A FAQ - Perguntas mais frequentes esta neste endereço: http://www.payzen.com.br/faq.php
11. ANALISAR O RESULTADO DO PAGAMENTO
Para processar o resultado dos pagamentos, o site de e-commerce deve possuir um script em uma página
dedicada para isso (exemplo: análise_pagamento.php).
Esta página será automaticamente chamada após todo pagamento (aceito ou recusado): os parâmetros
vinculados ao resultado do pagamento são enviados em modo POST para a plataforma de pagamento.
Requisitos:
• A URL da página que analisa o resultado do pagamento deverá obrigatoriamente ser informada no Back
Office (ver capítulo Configurar as notificações).
• O vendedor deverá garantir que esta URL possa ser alcançada pela plataforma de pagamento, e isso
sem redirecionamento.
Os redirecionamentos provocam a perda de dados presentes no POST.
• Se houver restrições instaladas pelo site de e-commerce, será preciso autorizar a lista de endereços
IP 194.50.38.0/24.
• A página não deverá conter mensagens HTML.
O acesso a recursos tais como imagens ou documentos padrões podem deixar a comunicação mais
lenta entre a plataforma de pagamento e o site de e-commerce.
Além disso, a plataforma lê sistematicamente os 512 primeiros símbolos da resposta do site de ecommerce.
Estes símbolos são depois exibidos no histórico das transações.
• Evite o quanto puder neste script tarefas que necessitam tempo tal como criar uma fatura ou enviar
e-mail.
O tempo de tratamento impacta diretamente o prazo para a exibição da página de resumo do
pagamento. Quanto mais o tratamento demora, mais longo o tempo de espera antes de visualizar.
Após 35s, a plataforma entende que a chamada falhou (timeout).
Falha da chamada para URL de notificação (IPN)
Se houver falha da chamada para a URL de notificação (IPN), um e-mail de alerta é enviado para o endereço
informado no Back Office (ver capítulo Configurar as notificações).
Contém:
• elementos de análise segundo o erro,
• os passos a seguir desde o Back Office para enviar de novo a notificação.
Conceber o script de tratamento
O script de tratamento deve conter pelo menos as etapas a seguir:
• Recuperar a lista dos campos presentes na resposta enviada em POST
• Calcular a assinatura
• 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 que
nã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 do pagamentos salvas etc...).
11.1. Recuperar os dados devolvidos na resposta
Os dados devolvidos na resposta dependem dos parâmetros enviados no formulário de pagamento, do
tipo de pagamento efetuado e das opções da sua loja. Estes dados constituem um lista de campos. Cada
campo contém um valor resposta. A lista de campos pode chegar a mudar.
Os dados são sempre enviados em POST para a plataforma de pagamento.
Exemplos:
• Em PHP, os dados serão armazenados na super global $_POST.
• Em ASP.NET (C#), você deve usar a propriedade Form da classe HttpRequest.
• Em ASP.NET (C#), você deve usar a propriedade getParameter da classe HttpServletRequest.
O script deverá realizar uma volta para recuperar a totalidade dos campos enviados.
Exemplo de dados enviados durante a notificação de um pagamento:
vads_amount = 3000
vads_auth_mode = FULL
vads_auth_number = 3fb0de
vads_auth_result = 00
vads_capture_delay = 0
vads_card_brand = VISA
vads_card_number = 497010XXXXXX0000
vads_payment_certificate = a50d15063b5ec6cb140043138b8d7576470b71a9
vads_ctx_mode = TEST
vads_currency = 986 />
vads_effective_amount = 3000
vads_site_id = 12345678
vads_trans_date = 20140902094139
vads_trans_id = 454058
vads_validation_mode = 0
vads_version = V2
vads_warranty_result = YES
vads_payment_src = EC
vads_sequence_number = 1
vads_contract_used = 5785350
vads_trans_status = AUTHORISED
vads_expiry_month = 6
vads_expiry_year = 2015
vads_bank_code = 17807
vads_bank_product = A
vads_pays_ip = FR
vads_presentation_date = 20140902094202
vads_effective_creation_date = 20140902094202
vads_operation_type = DEBIT
vads_threeds_enrolled = Y
vads_threeds_cavv = Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=
vads_threeds_eci = 05
vads_threeds_xid = WXJsVXpHVjFoMktzNmw5dTd1ekQ=
vads_threeds_cavvAlgorithm = 2
vads_threeds_status = Y
vads_threeds_sign_valid = 1
vads_threeds_error_code =
vads_threeds_exit_status = 10
vads_risk_control = CARD_FRAUD=OK;COMMERCIAL_CARD=OK
vads_result = 00
vads_extra_result = 00
vads_card_country = BR />
vads_language = fr
vads_hash = 299d81f4b175bfb7583d904cd19ef5e38b2b79b2373d9b2b4aab74e5753b10bc
vads_url_check_src = PAY
vads_action_mode = INTERACTIVE
vads_payment_config = SINGLE
vads_page_action = PAYMENT
signature = 3132f1e451075f2408cda41f2e647e9b4747d421
11.2. Calcular a assinatura
A assinatura é calculada segundo a mesma lógica usada durante a criação do formulário de pagamento.
Todos os campos recebidos devem ser levados em conta.
Para calcular a assinatura:
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. Garanta que todos os campos tenham o código UTF-8.
4. Concatene o resultado com o certificado de teste ou de produção, separando-os com o símbolo "+".
5. Aplicar o algoritmo SHA-1 para ter o valor da assinatura.
11.3. Comparar as assinaturas
Para garantir a integridade da resposta, você deve comparar o valor do campo assinatura recebido na
resposta, com o valor calculado na etapa anterior.
Se as assinaturas correspondem,
• você pode 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 vendedor sobre a anomalia (ver capítulo
Tratar os erros).
Se as assinaturas não correspondem por causa de:
• erro de implementação (erro no seu cálculo, problema de codificação UTF8, etc.).
• erro do valor do certificado usado ou no valor do campo vads_ctx_mode (problema frequente quando
passa em produção).
• tentativa de corrupção dos dados.
11.4. Analisar a natureza da notificação
O campo vads_url_check_src permite diferenciar as notificações vinculadas:
• à criação de uma transação.
• ao reenvio da notificação pelo Back Office pelo vendedor.
Ele menciona a regra de notificação aplicada:
Valor
Regra aplicada
PAY
O valor PAY será reenviado nos seguintes casos:
•
pagamento à vista (pagamento à vista ou primeira parcela de um pagamento parcelado)
•
pagamento pré-datado com menos de 7 dias
somente se o vendedor configurou a regra URL de notificação no final do pagamento.
•
o comprador desistiu ou cancelou o pagamento
somente se o vendedor configurou a regra URL servidor de notificação em cancelamento.
BO
Execução da notificação pelo Back Office (clique direito sobre uma transação > Executar a url
servidor).
BATCH_AUTO
O valor BATCH_AUTO será 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 vendedor configurou a regra URL de notificação sobre uma autorização por lote.
A notificação será enviada durante a solicitação de autorização de um pagamento com o status de
"Esperando a autorização".
REC
O valor REC será enviado somente para os pagamentos por assinatura se o vendedor configurou a
regra URL de notificação na criação de um pagamento recorrente
MERCH_BO
O valor MERCH_BO será enviado:
•
durante uma operação efetuada no Back Office (reembolso, modificação, validação, duplicata),
se o vendedor configurou a regra de notificação: URL de notificação sobre uma operação
•
durante um cancelamento efetuado pelo Back Office (reembolso, modificação, validação,
duplicata), se o vendedor configurou a regra de notificação: URL de notificação ao
cancelamento
Tabela 15 : Valorizações do campo vads_url_check_src
Testando seu valor, o script poderá realizar um tratamento diferente segundo a natureza da notificação.
Por exemplo:
Se vads_url_check_src tem o valor de PAY ou de BATCH_AUTO então o script atualizará o status da
solicitação, ...
Se vads_url_check_src tem o valor de REC então o script vai recuperar a referência da assinatura e vai
incrementar o número de parcelas vencidas quando o pagamento for aceito, ...
11.5. Identificar o tipo de operação
O campo vads_operation_type permite diferenciar :
• uma operação de débito
• uma operação de reembolso
Valor
Descrição
DEBIT
Operação de débito
CREDIT
Operação de reembolso
Tabela 16 : Valor do campo vads_operation_type
Por exemplo:
Se vads_operation_type esta preenchido com DEBIT, o script atualiza o pedido e salva as informações da
transação.
Se vads_operation_type esta valorizado em CREDIT, o script atualiza o valor pago ou acrescenta uma nova
linha de transação no pedido.
11.6. Tratar os dados da resposta
Segue abaixo um exemplo de análise para seguir passo a passo o tratamento dos dados da resposta.
1. Identifique o pedido recuperando o valor do campo vads_order_id se você o enviou no formulário de
pagamento.
Verifique que o status do pedido já não foi atualizado.
2. Recupere o resultado do pagamento enviado no campo vads_trans_status.
O valor dele lhe permite definir o status do pedido.
Valor
Descrição
ABANDONED
O comprador desistiu do pagamento.
A transação não foi criada e portanto não esta exibida no Back Office.
AUTHORISED
Captura em andamento
A transação foi aceita e será capturada automaticamente no banco na data
prevista.
Para ser aprovado
A transação, criada em validação manual, esta autorizada. O vendedor deve
validar manualmente a transação para lançar a solicitação de autorização e
a captura no banco.
A transação pode ser aprovada enquanto a data de captura não foi vencida.
Se esta data está vencida, então o pagamento tem o status Expirado. O
status Expirado é definitivo.
CANCELED
Cancelada
A transação foi cancelada pelo vendedor.
CAPTURED
Vencida
A transação foi capturada no banco
EXPIRED
Expirada
A date de captura foi atingida e o vendedor não validou a transação.
REFUSED
Recusada
A transação foi recusada.
Autorização em andamento
Prazo de captura maior que o tempo de validade da autorização ..
Uma autorização de 1 BRL foi aceita.
A solicitação de autorização será automaticamente efetuada a D-1 antes
da data de captura no banco. O pagamento poderá ser aceito ou recusado.
Captura automática no banco.
WAITING_AUTHORISATION_TO
_VALIDATE
Para ser aprovado e autorizado
Prazo de captura maior que o tempo de validade da autorização. .
Uma autorização de 1 BRL a été acceptée.
O vendedor deve validar manualmente a transação para lançar a solicitação
de autorização e a captura no banco.
UNDER_VERIFICATION
Spécifique à PayPal
En attente de vérification par PayPal
PayPal retient la transaction pour suspicion de fraude . Le paiement est
alors dans l’onglet Paiement en cours.
NOT_CREATED
A transação não foi criada e portanto não esta exibida no Back Office.
Tabela 17 : Valores associados a vads_trans_status
3. Recupere a referência do pagamento enviado no campo vads_trans_id.
4. Analise o campo vads_payment_config para determinar se trata-se de um pagamento à vista
(unitário) ou de um pagamento parcelado.
Este campo pode ser valorizado a:
Nome do campo
Valor para um pagamento à vista
Valor para um pagamento parcelado
vads_payment_config
SINGLE
MULTI
Nome do campo
Valor para um pagamento à vista
Valor para um pagamento parcelado
(MULTI:first=X;count=Y;period=Z)
Tabela 18 : Analise o campo vads_payment_config
Se trata-se de um pagamento parcelado, informe o número da parcela recuperando o valor do campo
vads_sequence_number.
Valor
Descrição
1
Primeira parcela
2
Segunda parcela
3
Terceira parcela
n
N parcela
Tabela 19 : Analise o campo vads_sequence_number
Para um pagamento à vista (unitário) o campo vads_sequence_number tem o valor de 1.
5. Recupere o valor do campo vads_trans_date para identificar a data do pagamento.
6. Recupere o valor do campo vads_capture_delay para identificar o número de dias antes da captura
no banco.
Isto lhe permitirá saber se trata-se de um pagamento à vista ou pré-datado.
7. Recupere o valor e a moeda usada. Para isso, recupere os valores dos seguintes campos:
Nome do campo
Descrição
vads_amount
Valor do pagamento na sua menor unidade monetária.
vads_currency
vads_change_rate
Taxa de cambio usada para calcular o valor real do pagamento (ver vads_effective_amount).
vads_effective_amount
Valor do pagamento na moeda efetivamente usada para a captura no banco.
Tabela 20 : Analise do valor e da moeda usada.
Observação:
Quando o campo vads_page_action for valorizado a REGISTER_SUBSCRIBE, o campo vads_amount
será valorizado a0, mesmo se nenhum pagamento tiver sido efetuado.
8. Recupere o valor do campo vads_auth_result para conhecer o resultado da solicitação de
autorização.
A lista completa dos códigos de retorno está disponível no dicionário de dados.
Para entender melhor o motivo da recusa, segue uma lista de códigos frequentemente retornados:
Valor
Descrição
03
Receptor inválido
Este código é emitido pelo banco do vendedor. Devido a um problema de configuração nos servidores de
autorização. (Ex: contrato encerrado, código MCC declaro errado, etc..).
Para conhecer a razão precisa da recusa, o comprador deve entrar em contato com seu banco.
05
Não honrar
Este código é emitido pelo banco que emitiu o cartão. Este código pode aparecer nos seguintes casos:
•
Data de vencimento inválida,
•
CVV inválido,
•
Limite de crédito excedido
•
Saldo insuficiente (etc...)
Para conhecer a razão precisa de recusa, o comprador deve entrar em contato com o banco dele.
51
Provisão insuficiente ou limite de crédito excedido
Este código é emitido pelo banco emissor do cartão. Este código pode aparecer se o comprador não tem um
saldo suficiente para efetuar a compra.
Valor
Descrição
56
Cartão ausente da base
Este código é emitido pelo banco emissor do cartão.
O número de cartão digitado esta errado ou o par número de cartão + data de vencimento não existe
57
Transação interditada para este portador
Este código é emitido pelo banco emissor do cartão. Este código pode aparecer nos seguintes casos:
•
O comprador tenta efetuar o pagamento na internet com um cartão de débito,
•
O limite autorizado pelo cartão esta excedido.
59
Suspeita de fraude
Este código é emitido pelo banco emissor do cartão. Este código pode aparecer quando houve o CVV foi
digitado de maneira repetitiva ou se a data de vencimento estiver errada.
60
O receptor do cartão deve entrar em contato com o adquirente
Este código é emitido pelo banco do vendedor. Devido a um problema de configuração nos servidores de
autorização. Geralmente emitido quando o contrato comerciante não corresponde ao canal de venda usado.
(Ex: uma transação e-commerce com um contrato VAD-digitação manual).
Entre em contato com o serviço de atendimento ao cliente para regularizar a situação.
Tabela 21 : Valorizações do campo vads_auth_result
9. Recupere o resultado da autentificação 3D Secure. Para isso:
a. Recupere o valor do campo vads_threeds_enrolled para determinar o status de alistamento do
cartão.
Valor
Descrição
Vazio
Processo 3DS não realizado (3DS desativado na solicitação, vendedor não alistado ou meio de pagamento
não elegível no 3DS).
Y
Autenticação disponível, portador alistado.
N
Portador não alistado.
U
Identificação do portado impossível ou cartão não elegível com as tentativas de autentificação (ex. Cartões
comerciais ou pré-pagos).
Tabela 22 : Valores do campo vads_threeds_enrolled
b. Recupere o resultado da autentificação 3D Secure recuperando o valor do
campovads_threeds_status.
Valor
Descrição
Vazio
Autentificação 3DS não realizada (3DS desativado na solicitação, portador não alistado ou meio de
pagamento não elegível no 3DS)
Y
Portador identificado com sucesso.
N
Erro de autentificação do portador.
U
Autentificação impossível.
A
Tentativa de autentificação mas autentificação não efetuada.
Tabela 23 : Valores do campo vads_threeds_status
10.Recupere o resultado dos controles associados à fraude identificando o valor do
campovads_risk_control. Este campo é enviado somente se o vendedor:
• selecionou a opção « Ajuda à decisão »
• ativou pelo menos um controle pelo seu Back Office (menu Configuração > Controle dos riscos).
Ele toma como valor uma lista de valores separados por um « ; » cuja sintaxe é: vads_risk_control =
control1=result1;control2=result2
Os diferentes valores possíveis para control são :
Valor
Descrição
CARD_FRAUD
Controla a presença do número de cartão do comprador na lista cinza de cartões.
Valor
Descrição
SUSPECT_COUNTRY
Controla a presença do país emissor do cartão do comprador na lista dos países
proibidos.
IP_FRAUD
Controla a presença do endereço IP do comprador na lista cinza de IP.
CREDIT_LIMIT
Controla a frequência e os valores de compra de um mesmo número de cartão, ou o
valor máximo de um pedido.
BIN_FRAUD
Controla a presença do código BIN do cartão na lista cinza dos códigos BIN.
ECB
Controla se o cartão do comprador é do tipo e-carte bleue.
CARD_COMMERCIAL
Controla se o cartão do comprador é um cartão comercial.
SYSTEMATIC_AUTO
Controla se o cartão do comprador é um cartão com autorização sistemática.
INCONSISTENT_COUNTRIES
Controla se o país do endereço IP, o país emissor do cartão de pagamento, e o país do
endereço do comprador são coerentes entre eles.
NON_WARRANTY_PAYMENT
Controla a transferência de responsabilidade da transação.
SUSPECT_IP_COUNTRY
Controle a presença do país do comprador, identificado pelo endereço IP dele, na lista
dos países proibidos.
Tabela 24 : Lista dos controles associados à fraude
Os diferentes valores possíveis para result são :
Valor
Descrição
OK
OK.
WARNING
Controle informativo não sucedido.
ERROR
Controle bloqueante não sucedido.
Tabela 25 : Lista dos controles associados à fraude
11.Recupere o tipo de cartão usado para o pagamento.
Dois cenários são possíveis:
• Para que um pagamento feito com um único cartão. Os campos a serem tratados são os
seguintes:
Nome do campo
Descrição
vads_card_brand
Tipo de cartão usado para o pagamento.
vads_card_number
Número de cartão usado para efetuar o pagamento.
vads_expiry_month
Mês de vencimento entre 1 e 12 (ex: 3 para março, 10 para outubro).
vads_expiry_year
Ano de vencimento com 4 dígitos (ex: 2023).
vads_bank_code
Código do banco emissor
vads_bank_product
Código produto do cartão
vads_card_country
Código País do país emissor do cartão (Código alpha ISO 3166-2, ex França=FR).
Tabela 26 : Analise do cartão usado para o pagamento.
• Para que um pagamento parcelado (ou seja, uma transação usando diversos meios de
pagamento), os campos a serem abordados são:
Nome do campo
Valor
Descrição
vads_card_brand
MULTI
Diversos tipos de cartões são utilizados para o
pagamento.
vads_payment_seq Formato JSON, veja os detalhes
abaixo.
Detalhes de transações concluídas.
O campo vads_payment_seq (formato JSON) descreve a sequência de pagamento parcelado. Ele
contém os elementos:
1. "trans_id": número de transação global a sequência de pagamento.
2. "transaction": tabela das transações da sequência. Os elementos são os seguintes:
Nome do campo
Descrição
amount
Valor da sequência da transação.
Nome do campo
Descrição
operation_type
Operação de débito.
auth_number
Número de autorização devolvido pelo servidor do banco (se não vazio).
capture_delay
Indica o prazo em número de dias antes da captura no banco.
•
Se este parâmetro não é enviado, então o valor padrão definido no Back Office será
usado. Este último pode ser configurado no Back Office por todas as pessoas devidamente
autorizadas.
card_brand
Meio de pagamento usado.
card_number
Número de cartão.
expiry_month
Mês de vencimento do cartão usado para o pagamento.
expiry_year
Ano de vencimento do cartão usado para o pagamento.
payment_certificate
Certificado do pagamento.
presentation_date
Data de captura no banco solicitada.
trans_id
Número de transação.
ext_trans_id
Campo vazio para o pagamento por cartão
sequence_number
Número de sequência da transação (número de parcela).
trans_status
Status da transação.
Tabela 27 : JSON
Nota: transações canceladas também estão presentes na tabela.
Exemplo de um pagamento com um cartão pré-pago e o complemento com um cartão VISA:
{"trans_id":"599495",
"transactions":
{"amount":"1000",
"operation_type":"DEBIT",
"capture_delay":"0",
"card_brand":"ILLICADO_SB",
"card_number":"925000XXXXXXXXX1581",
"payment_certificate":"5d49440418b44cf957ee509cccdefeb6ebaa3b23",
"presentation_date":"2015-01-26T14:39:10Z",
"trans_id":"599495",
"ext_trans_id":"123456",
"sequence_number":"1",
"trans_status":"CAPTURED"
},
{"amount":"9000",
"operation_type":"DEBIT",
"auth_number":"3fee2a",
"capture_delay":"0",
"card_brand":"VISA",
"card_number":"497010XXXXXX0000",
"expiry_month":"6",
"expiry_year":"2015",
"payment_certificate":"7696aeeb76444595a6c027fa050aa6657764178c",
"presentation_date":"2015-01-26T14:39:30Z",
"trans_id":"599495",
"sequence_number":"2",
"trans_status":"AUTHORISED"
}
]}
12.Recupere todas as informações sobre o detalhe do pedido, o detalhe do comprador e o detalhe da
entrega.
Estes dados estão presentes na resposta somente se eles foram enviadas no formulário de
pagamento.
O valor deles é idêntico ao valor mencionado no formulário.
13.Faça a atualização do pedido.
11.7. Tratar os erros
Implementação de um arquivo de log
Durante a fase de implementação, será útil possuir logs especificamente em caso de dificuldades para
calcular a assinatura.
Nós aconselhamos implementar um arquivar de log diariamente, mesmo depois de ter passado o site de
e-commerce em produção.
Isto lhe permitirá analisar os dados em caso de problemas.
Idealmente, o arquivo de logs terá que conter os dados enviados ou recebidos, o string do cálculo de
assinatura obtido, antes de aplicar o algoritmo SHA-1.
Código de erro HTTP
Em caso de erro durante as notificações, o e-mail de alerta enviado menciona o código de retorno do
protocolo HTTP.
Existe 5 categorias de códigos de retorno:
Categoria de códigos
Descrição
1XX
Informação
2XX
Sucesso
3XX
Redirecionamento
4XX
Erro do cliente
5XX
Erro do cliente
Os códigos de erro mais frequentemente retornados são apresentados na FAQ - Perguntas mais frequentes
https://secure.payzen.eu/html/server_url_error/
Erro frequente:
Um arquivo htaccess pode bloquear a chamada para a URL de notificação instantânea.
Os arquivos .htaccess são arquivos de configuração dos servidores web Apache. Podem ser localizados
em qualquer repertório do site de e-commerce (a configuração se aplica ao repertório e a todo arquivo
contido que não tiver este tipo de arquivo presente).
12. TRATAR O RETORNO PARA A LOJA
De maneira padrão, quando o comprador volta no site de e-commerce, nenhum parâmetro é enviado pelo
navegador dele.
Porém se o campo vads_return_mode foi enviado no formulário de pagamento (ver capítulo Gerenciar o
retorno para o site de e-commerce) será possível recuperar os dados:
• ou em GET: dados presentes na url sob a forma: ?param1=valor1&param2=valor2.
• ou em POST: dados enviados num formulário POST.
Os dados transmitidos para o navegador são os mesmos que os das notificações (IPN).
Somente os campos vads_url_check_src e vads_hash serão enviados na notificação instantânea.
Você pode consultar o capítulo Tratar as modificações para analisar estes dados.
Observação : o retorno para a loja deve permitir somente uma visualização do contexto ao comprador.
Não use os dados recebidos para realizar o tratamento na base de dados.
13. INICIAR A FASE DE TESTE
Antes de passar a loja em produção, é preciso realizar testes para garantir o bom funcionamento da
comunicação entre o site de e-commerce e a plataforma de pagamento.
Estes testes devem obrigatoriamente ser realizados antes de solicitar o início da produção.
13.1. Efetuar testes de pagamento
As solicitações de pagamento de teste enviadas com o formulário HTTP POST devem:
• Ter o dado vads_ctx_mode com o valor TEST.
• Use o certificado de TESTE previamente recuperado para o cálculo da assinatura.
Durante a fase de teste, o vendedor pode testar as configurações 3D Secure (se este último esta alistado
3DS e se a opção 3DS esta ativada).
Diferentes casos de pagamentos podem ser simulados usando números de cartão de teste apresentados
na página de pagamento.
Todas as transações efetuadas em modo teste podem ser consultadas pelas pessoas autorizadas a usar o
Back Office no seguinte endereço.
https://secure.payzen.com.br/vads-merchant/
Estas transações podem ser consultadas no menu Gestão >Transação de teste localizado em cima a
esquerda do Back Office.
13.2. Testar a URL de notificação instantânea (IPN)
Verifique primeiro o status da URL de notificação instantânea (também chama IPN) pelo Back Office.
Para isso:
1. Clique direito em uma transação.
2. Selecione Exibir o detalhe da transação.
3. Verifique o status da URL de notificação instantânea (IPN).
• No caso que o status aparece em Enviado, significa que você não informou a URL no Back Office.
• No caso que o status aparece em URL não definida, significa que você não informou a URL no Back
Office.
1. Verifique o endereço da URL de notificação instantânea digitada em modo TEST e PRODUCTION.
2. Selecionar Configuração > Regras de notificações.
3. Informar a URL de notificações do pagamento instantânea (URL de notificações ao fim do
pagamento).
Não digite um endereço em "localhost". A chamada para esta URL é feita de servidor a servidor.
• No caso que o status aparece em Falhou, consultar o capítulo Tratar os erros.
14. ATIVAR A LOJA EM MODO DE PRODUÇÃO
Este capítulo detalha como você pode:
• Gerar o certificado de produção
• Passar seu site de e-commerce em produção.
• Efetuar um primeiro pagamento em produção.
• Gerar de novo o certificado de produção (se houver problema)
14.1. Gerar o certificado de produção
Você pode gerar o certificado de produção a partir do menu Configuração > Loja > Aba Certificados >
botão Gerar o certificado de produção.
Uma vez que o certificado foi gerado, o valor dele aparece debaixo da aba Certificados.
Um e-mail é enviado para o responsável encarregado do assunto (responsável administrativo da empresa)
para confirmar para ele que o certificado de produção foi gerado.
14.2. Passar seu site de e-commerce em produção.
1. Preencher o campo vads_ctx_mode à PRODUCTION.
2. Modificar o valor do certificado de teste com o valor de seu certificado de produção para calcular a
assinatura.
Você encontrará este valor no menu Configuração > Loja > Aba Certificados.
3. Informar corretamente a URL de notificação (chamada também IPN) em modo PRODUCTION no menu
Configuração > Regras de notificações.
14.3. Efetuar um primeiro pagamento em produção.
Nós aconselhamos que você verifique duas coisas:
• O bom funcionamento de A a Z num ambiente de produção.
Efetuar uma transação real.
Esta transação poderá ser cancelada depois no Back Office no menu Gestão > Transação > aba
Transação em andamento. Esta transação não será capturada no banco.
• O bom funcionamento da URL de notificação (também chamada IPN) informada no Back Office.
Não clicar no botão Voltar para a loja apos um pagamento.
Visualizar o dados do pedido no Back Office e verificar que o status da URL de notificação instantânea
é Enviado.
14.4. Gerar de novo o certificado de produção
Em caso de perda ou corrupção do certificado de produção, o vendedor terá a possibilidade de gerar um
novo certificado pelo Back Office. Para isso:
1. No Back Office, selecionar Configuração > Loja> aba Certificados.
2. Clicar em Gerar de novo.
15. FAQ - PERGUNTAS MAIS FREQUENTES
Uma FAQ - Perguntas mais frequentes esta disponível em o sitehttp://www.payzen.com.br/faq.php.
Ela repertoria as perguntas mais frequentes sobre os códigos de erros retornados durante o envio do
formulário de pagamento.
16. DICIONÁRIO DE DADOS
O dicionário de dados apresenta a lista completa dos campos que podem ser utilizados no formulário de
pagamento.
Ele detalha inicialmente as principais categorias (tais como as informações técnicas, as informações do
pedido…). O conjunto dos campos que pertencem à uma categoria são apresentados.
Estas tabelas são apresentadas da seguinte maneira:
• Nome: indica o nome do parâmetro, como ele será usado em um pedido HTTP.
• Formato: indica o formato dos dados, segundo a seguinte codificação:
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
3
Comprimento fixo até 3 símbolos
..12
Comprimento variável até 12 símbolos
Tabela 28 : Lista campos e formatos
• Descrição: descrição do campo.
O dicionário de dados apresenta em seguida o detalhe para cada um dos campos. Cada campo é descrito
da seguinte maneira:
• Descrição: descrição do campo.
• Formato: formato dos dados (ver a tabela Lista de campos e formatos acima).
• Valores possíveis: valores esperados quando o campo deve ser valorizado com valores específicos.
• Exemplo: representa um exemplo de codificação correta dos dados.
• Código de erro: em caso de erro na passagem de dados entre o site comerciante e a plataforma de
pagamento, esta última irá indicar no campo vads_extra_result o código do parâmetro com problema.
• Aviso: informações adicionais, precisão.
• Categoria: categoria na qual o campo esta associado.
Detalhes de códigos de erro:
Code erreur corresponde ao número de erro quando é apresentado um formulário de pagamento
incorreto.
• Em modo teste este código será exibido na página de pagamento.
• Em modo produção um e-mail de alerta será enviado precisando o código de erro e o nome do
parâmetro incorreto.
Exemplo :Erro 09 corresponde a um erro sobre o valor. O valor enviado não esta conforme ao formato
requerido
Exibir os parâmetros classificados por categoria
Clique na categoria desejada para ter a lista dos parâmetros subjacentes.
• Informações sobre a autentificação 3DS.
• Informações sobre a assinatura.
• Informações sobre o comprador.
• Informações sobre o meio de pagamento.
• Informações sobre o pedido.
• Informações sobre a entrega.
• Informações técnicas.
• Informações sobre a transação.
• Informações sobre as transações de doação.
• Personalização da página de pagamento.
• Redirecionamento automático
Informações técnicas.
Nome do campo
Formato
Descrição
signature
an40
Permite verificar a integridade das solicitações.
vads_action_mode
string
(enum)
Modo de aquisição das informações do cartão
vads_contrib
ans..128
Indica o nome da contribuição usada durante o pagamento (Joomla,
osCommerce...).
vads_ctx_mode
string
(enum)
Modo de comunicação da plataforma de pagamento
vads_extra_result
n2
Código complementar de resposta A significação dela depende do valor
informado em vads_result.
vads_hash
an64
Chave única reenviada somente para a URL de notificação (IPN).
vads_page_action
string
(enum)
Define a operação a ser efetuada.
vads_payment_error
n..3
Códigos de erro sobre um pagamento recusado.
vads_result
n2
Código retorno geral do resultado do pagamento.
vads_site_id
n8
Identificação do site.
vads_url_check
ans..127
URL da página a ser notificada no final do pagamento. Sobrecarrega o valor
digitado na configuração das regras de notificação.
vads_url_check_src
string
(enum)
Este parâmetro define a procedência da chamada URL de notificação (IPN
Server).
vads_version
string
Versão do protocolo de troca com a plataforma de pagamento.
Tabela 29 : Lista dos parâmetros - Informações técnicas
Informações sobre o pedido.
Nome do campo
Formato
Descrição
vads_ext_info
ans
Os campos podem ser personalizados e permitem acrescentar dados
suplementares no e-mail de confirmação enviado para o vendedor e na
URL de notificação.
vads_nb_products
n..12
Detalhe do carrinho. Quantidade de artigos.
vads_order_id
an..32
Número de pedido.
vads_order_info
an..255
vads_order_info2
an..255
vads_order_info3
an..255
Nome do campo
Formato
Descrição
n..12
Detalhe do carrinho. Valor do artigo N.
vads_product_labelN
an..255
Detalhe do carrinho. Denominação do artigo N.
vads_product_qtyN
n..12
Detalhe do carrinho. Quantidade de artigo N.
vads_product_refN
an..64
Detalhe do carrinho. Referência do artigo N.
vads_product_typeN
string
(enum)
Detalhe do carrinho. Tipo do artigo N.
Tabela 30 : Lista dos parâmetros - Detalhes do pedido
Informações sobre o comprador.
Nome do campo
Formato
Descrição
vads_cust_address
ans..255
Caixa postal.
an..5
Número de rua.
an..32
Número de telefone celular.
vads_cust_city
an..128
Cidade.
vads_cust_country
a2
Código país segundo a norma ISO 3166.
vads_cust_district
ans..127
Bairro.
vads_cust_email
ans..150
Endereço e-mail do comprado.
an..63
Nome
vads_cust_id
an..63
Referência do comprado no site de e-commerce.
vads_cust_last_name
an..63
Sobrenome
an..100
vads_cust_name
an..127
Desvalorizado.
Use vads_cust_first_name e vads_cust_last_name.
ans..255
CPF/CNPJ
vads_cust_phone
an..32
vads_cust_state
ans..127
UF / Região.
vads_cust_status
string (enum) Status (pessoa física / pessoa jurídica).
vads_cust_title
an..63
Estado civil do comprador.
vads_cust_zip
an..64
CEP.
Tabela 31 : Lista dos campos - Detalhes do comprador
Informações sobre a entrega.
Nome do campo
Formato
Descrição
vads_ship_to_city
an..128
Cidade.
a2
Código país segundo a norma ISO 3166.
vads_ship_to_delivery_company_name ans..127
Nome do transportador.
ans..127
Bairro.
ans..63
Nome
ans..63
Sobrenome
an..100
Razão social do local de entrega.
vads_ship_to_name
ans..63
Sobrenome do comprador.
ans..32
vads_ship_to_speed
string (enum)
Modo de entrega
vads_ship_to_state
ans..127
UF / Região.
vads_ship_to_status
string (enum)
Status (pessoa física / pessoa jurídica).
vads_ship_to_street
ans..255
Caixa postal.
an..5
Número de rua.
ans..255
Segunda linha do endereço.
vads_ship_to_type
string (enum)
Tipo de entrega
Nome do campo
Formato
Descrição
vads_ship_to_user_info
ans..255
Informações comprador (Identificador legal CPF/CNPJ).
vads_ship_to_zip
an..64
CEP.
Tabela 32 : Lista dos parâmetros - Detalhes de entrega
Informações sobre o meio de pagamento.
Nome do campo
Formato
Descrição
vads_bank_code
n5
Código banco associado ao banco emissor.
vads_bank_product
an..3
Código produto do cartão usado para o pagamento.
vads_birth_day
n..2
Data de nascimento do portador.
vads_birth_month
n..2
Mês de nascimento do portador.
vads_birth_year
n4
Ano de nascimento do portador.
vads_card_brand
an..127
Tipo de cartão usado para o pagamento.
vads_card_country
ISO 3166
Código país do cartão usado para o pagamento.
vads_card_number
n..36
Número do cartão oculto.
vads_cvv
n..4
Código de segurança do cartão de 3 ou 4 dígitos.
vads_expiry_month
n..2
vads_expiry_year
n4
Tabela 33 : Lista dos parâmetros - Informação sobre o meio de pagamento
Informações sobre a transação.
Nome do campo
Formato
Descrição
vads_amount
n..12
Valor da transação expresso na menor unidade da moeda .
vads_auth_mode
string (enum)
Especifica de que maneira é realizada a solicitação de
autorização.
vads_auth_number
an..6
Número de autorização devolvido pelo servidor do banco.
vads_auth_result
n2
Código retorno da solicitação de autorização devolvida pelo
banco emissor.
vads_capture_delay
n..3
Prazo em quantidade de dias antes da captura no banco.
vads_change_rate
string
Taxa de cambio usada para calcular o valor real do pagamento
(pagamento multi-moeda).
vads_contract_used
ans..250
Contrato comercial usado.
vads_contracts
REDE1=contrato1;
REDE2=contrato2;
Contrato comercial a ser usado.
vads_currency
n3
Código numérico da moeda a ser usada para o pagamento.
n..12
Valor da parcela de pagamento expresso na menor unidade da
moeda utilizada para efetuar a captura no banco .
vads_effective_creation_date
n14
Data de registro da transação, no fuso UTC (ou GNT+0) ao
formato horário 24h (AAAAMMJJHHMMSS).
vads_operation_type
string (enum)
Permite fazer a diferença entre uma operação de débito e uma
de crédito (reembolso).
vads_payment_cards
type1;type2
Lista dos meios de pagamento para propor ao comprador.
vads_payment_certificate
an40
Campo informado pela plataforma de pagamento se a
autorização foi efetuada com sucesso.
vads_payment_config
string (enum)
Tipo de pagamento: à vista ou parcelado.
vads_payment_option_code
string
Permite definir o código da opção usada.
vads_payment_seq
json
Descreve a sequência de um pagamento fraccionado.
vads_payment_src
string (enum)
Procedência do pagamento.
vads_risk_analyzer_result
ans
Retorna o resultado da análise de fraude efetuada por um
sistema externo (ClearSale, CyberSource,...).
ans
Retorna o resultado da análise de gerenciamento avançados
dos riscos efetuada pela plataforma de pagamento.
vads_risk_control
controle1=resultado1;
Resultado dos controles associados à fraude.
Nome do campo
Formato
controle2=resultado2
Descrição
vads_sequence_number
n
vads_trans_date
n14
Data e hora, no fuso UTC (ou GMT+0) ao formato horário 24h
(AAAAMMJJHHMMSS).
vads_trans_id
n6
Identificador único de uma transação.
vads_trans_status
string (enum)
vads_trans_uuid
ans32
Referência única da transação gerada pela plataforma de
pagamento.
string (enum)
Modo de validação da transação.
vads_warranty_result
string (enum)
Transferência de responsabilidade se o pagamento foi aceito.
Tabela 34 : Lista dos parâmetros - Informação sobre a transação
Autentificação 3DS
Nome do campo
Formato
Descrição
vads_threeds_cavv
ans..28
Designa a verificação da autentificação do portador pela ACS.
É valorizado pelo servidor de autentificação 3DS (ACS) quando o
comprador se identificou corretamente (vads_threeds_status vale« Y »
ou « A »).
vads_threeds_cavvAlgorithm
n1
Algoritmo usado pela ACS para gerar o valor do cavv.
ou « A »).
vads_threeds_eci
n..2
Designa o Indicador de Comercio Eletrônico
ou « A »).
vads_threeds_enrolled
a1
Designa o status de alistamento do portador.
É valorizado pelos servidores VISA e MASTERCARD (DS) durante o
processo 3D Secure
vads_threeds_exit_status
n..2
Designa o status final do processo 3D Secure.
É valorizado pela plataforma de pagamento
vads_threeds_mpi
n1
Ativa / desativa o processo 3DS durante um pagamento e-commerce
vads_threeds_sign_valid
n1
Designa a validade da assinatura da mensagem PARes.
vads_threeds_status
a1
Designa o status de autentificação do portador.
É valorizado pelo servidor de autentificação 3DS durante o processo 3D
Secure.
vads_threeds_xid
ans..28
Designa a referência única da transação 3DS.
É valorizado pelo servidor de autentificação (ACS) durante o processo
3D Secure.
Tabela 35 : Lista dos parâmetros - Autentificação 3DS
Informações sobre as transações de doação.
Nome do campo
Formato
Descrição
vads_ext_info_donation
n..12
Valor da doação apresentado na menor unidade da moeda .
vads_ext_info_donation_contribution
n..12
Valor em centavos da contribuição apresentada na menor unidade
da moeda .
vads_ext_info_donation_merchant
n8
Identificador da associação que recebeu a doação.
vads_ext_info_donation_recipient
n..20
Identificador HelloAsso da associação que recebeu a doação.
vads_ext_info_donation_recipient_name string
Nome da associação que recebeu a doação.
vads_risk_primery_warranty
Permite sobrescrever a configuração do controle de risco Controle
da transferência de responsabilidade da transação primária.
string
(enum)
Tabela 36 : Lista dos parâmetros - Informação sobre as transações de doação
Personalização da página de pagamento
Nome do campo
Formato
Descrição
vads_available_languages
idioma1;idioma2;idioma3
Permite especificar os idiomas disponíveis na página
de pagamento sob a forma de lista.
vads_language
a2
Definido no mesmo idioma exibido na página de
pagamento (norma ISO 639-1).
vads_shop_name
ans..127
Permite definir o nome da loja que será exibido
nos e-mails de confirmação de pagamento e no
recapitulativo da transação.
vads_shop_url
ans..127
Permite sobrescrever a URL da loja que será exibida
na página de pagamento e nos e-mails de confirmação
de pagamento.
vads_theme_config
Código1=Valor1;Código2=Valor2
Permite personalizar alguns elementos da página de
pagamento.
Tabela 37 : Lista dos parâmetros - Personalização da página de pagamento
Redirecionamento para o site de e-commerce
Nome do campo
Formato
Descrição
ans..255
Redirecionamento automático:
Mensagem exibida antes do redirecionamento depois de um
pagamento aceito/recusado.
n..3
Prazo (em segundo) antes do redirecionamento para o site de ecommerce após um pagamento recusado/aceito.
ans..255
Especifica a mensagem no final de um pagamento aceito no caso de
um redirecionamento automático para o site de e-commerce.
n..3
Prazo em segundo antes do redirecionamento para o site de ecommerce no final de um pagamento aceito. O valor oscila entre 0
et 600s.
vads_return_mode
GET/POST/
NONE
Permite especificar o modo de envio dos dados às URLs de retorno
para o site de e-commerce.
vads_url_cancel
ans..127
URL para qual será redirecionado o comprador depois de clicar em
"cancelar e voltar para a loja" antes de ter efetuado o pagamento.
vads_url_check
ans..127
URL da página a ser notificada no final do pagamento. Sobrecarrega
o valor digitado na configuração das regras de notificação.
vads_url_check_src
string (enum)
Este parâmetro define o evento que dispara a notificação
instantânea (também chamada IPN ou URL de notificação).
vads_url_error
ans..127
URL para qual será redirecionado o comprador em caso de erro de
tratamento interno.
vads_url_refused
ans..127
URL para qual será redirecionado o comprador em caso recusa.
vads_url_return
ans..127
URL padrão para qual será redirecionado o comprador se ele clicar
em "voltar para a loja".
vads_url_success
ans..127
URL para qual será redirecionado o comprador em caso de sucesso.
Tabela 38 : Lista dos parâmetros - Redirecionamento para o site de e-commerce
Informações sobre a assinatura.
Nome do campo
Formato
Descrição
vads_identifier_status
string
Status de registro do mandato.
n
Número da parcela da assinatura.
vads_recurrence_status
string
Status da criação de uma recorrência.
vads_sub_amount
n..12
Valor das parcelas da assinatura para todas as prestações, tirando as
que podem ser definidas por vads_sub_init_amount_number
Nome do campo
Formato
Descrição
vads_sub_currency
n3
Código numérico da moeda a ser usada para a assinatura, segundo a
norma ISO 4217.
vads_sub_desc
string
Regra de recorrência a ser aplicada segundo a especificação iCalendar
RFC5545.
vads_sub_effect_date
n8
Data de início da assinatura.
vads_sub_init_amount
n..12
Valor das parcelas da assinatura para as primeiras parcelas.
vads_sub_init_amount_number
n..3
Quantidade de parcelas pelas quais o valor terá que ser aplicado
vads_sub_init_amount.
vads_subscription
ans..50
Identificador da assinatura a ser criada.
Tabela 39 : Lista dos parâmetros - Informação sobre a assinatura
signature
Descrição
Parâmetro obrigatório.
Permite verificar a integridade das solicitações enviadas.
Se o valor é calculado:
• pelo site de e-commerce durante a solicitação de pagamento
• pela plataforma de pagamento na resposta.
Formato
ano40
Código de erro
00 - signature quando o valor deste campo não esta correto.
70-empty params se o campo esta ausente ou se ele é enviado vazio.
Erros frequentes:
• Os diferentes campos do formulário não foram codificados em UFT8.
• O MODO (teste ou produção) ou o CERTIFICADO usado é incorreto.
• Voltar para a linha e/ou tecla "enter" enviados no formulário.
• Símbolo aspas ["] enviado no formulário.
• A assinatura enviada não é conforme a regra do cálculo da assinatura.
Categoria
vads_action_mode
Descrição
Modo de aquisição das informações do cartão
Formato
string (enum)
Código de erro
47
Valores possíveis INTERACTIVE: digitação das informações do cartão na página de pagamento.
SILENT: digitação das informações do cartão no site de e-commerce (submetido à
opção comercial fornecida pelo seu banco).
Categoria
vads_amount
Descrição
Valor da transação apresentado na menor unidade da moeda .
Exemplo: para uma transação de 10 o valor do parâmetro é 10.
O formulário de pagamento será recusado nos seguintes casos:
• Um valor igual a zero [vads_amount=0],
• Um valor negativo [vads_amount=-100],
• Um valor composto de decimais ou de pontos [vads_amount=100.50],
• Um formulário sem o campo vads_amount (ausência de valor).
Uma mensagem de incidente técnico será associada a um código retorno 09
(vads_extra_result).
Formato
n..12
Código de erro
09
Categoria
vads_auth_mode
Descrição
Campo retornado na resposta.
Especifica de que maneira é realizada a solicitação de autorização.
Formato
Valores possíveis
string (enum)
FULL : corresponde a uma autorização do valor total da transação.
Valor usado no caso de um pagamento à vista, se o tempo entre a data de captura
pedida e a data do dia vigente é exatamente inferior ao tempo de validade da
autorização.
MARK : corresponde a uma autorização de 1 BRL.
Valor usado no caso de um pagamento pré-datado, se o tempo entre a data de
captura pedida e a data do dia vigente é exatamente superior ao tempo de validade
da autorização.
Categoria
vads_auth_number
Descrição
Campo devolvido na resposta
Número de autorização devolvido pelo servidor do banco, se disponível (se não
vazio).
Formato
an..6
Categoria
vads_auth_result
Descrição
Campo reenviado à resposta.
Código retorno da solicitação de autorização devolvida pelo banco emissor, se
disponível.
Formato
n2
Valores possíveis
Motivo
frauduloso
Valor
Descrição
00
Transação aprovada ou realizada
com sucesso
02
Contatar o emissor do cartão
03
Autorizador inválido
SIM
04
Guardar o cartão
05
07
08
Aprovar após identificação
12
Transação inválida
SIM
13
Valor inválido
14
Motivo
frauduloso
Valor
Descrição
38
Data de validade do cartão vencida
41
Cartão perdido
SIM
43
Cartão roubado
SIM
SIM
51
Saldo insuficiente ou limite de
crédito excedido.
Não honrar
SIM
54
Guardar o cartão, condições
especiais
SIM
55
Senha errada
56
Cartão ausente da base
SIM
57
Transação interditada para este
portador
SIM
SIM
58
Transação interditada para este
portador
Número de portador inválido.
SIM
59
Suspeita de fraude
15
Emissor de cartão desconhecido
SIM
60
O autorizador de cartão deve entrar
em contato com o comprador.
17
Cancelamento comprador
61
Valor de saque fora do permitido
19
Repetir a transação posteriormente
63
Regras de segurança não
respeitadas.
20
Resposta errada (erro no domínio do
servidor).
68
Resposta não entregue ou recebida
tarde demais
24
Atualização do arquivo não foi
possível
75
Quantidade de tentativas senhas
excedidas
25
Não foi possível localizar o registro
no arquivo
76
Portador já interditado, antigo
registro salvo
26
Registro duplicado, antigo registro
substituído
90
Parada temporária do sistema
27
Erro em "edit" no campo de lista de
atualizaçã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ça
global
31
Código do organismo comprador
inválido
SIM
98
Servidor indisponível
encaminhamento rede pedido
novamente
33
SIM
99
Incidente domínio iniciador
34
Suspeita de fraude
SIM
SIM
SIM
SIM
SIM
Código retorno Cartão Amex
Valor
Descrição
000
Aprovado
001
Aprovado com carteira de identidade
002
Autorização parcial (Somente Cartões pré-pagos)
100
Recusado
101
Cartão vencido / Data de vencimento inválida
106
Número de tentativas de digitação do NIP ultrapassado
107
Favor entrar em contato com o emissor
109
Vendedor inválido
110
Valor inválido
111
Conta inválida / MICR inválido
115
Função solicitada não assegurada
117
NIP inválido
119
Titular não registrado / não autorizado
122
Código de segurança do cartão inválido (Token Cartão NIC/C4C)
125
Data de entrada em vigor inválida
181
Erro de formato
183
Código de moeda inválido
187
Recusado - Novo cartão emitido
189
Recusado - Conta cancelada
200
Recusado - Retirar Cartão
900
Aceito - Sincronização ATC
909
Falha do sistema (erro criptográfico)
912
Emissor não disponível
Tabela 40 : Código retorno Cartão Amex
Categoria
vads_available_languages
Descrição
Permite especificar os idiomas disponíveis na página de pagamento sob a forma de
lista.
Cada elemento da lista deve estar separado por um ponto e virgula ";".
E exibido com bandeiras na página de pagamento.
Formato
idioma1;idioma2;idioma3
Código de erro
71
Valores possíveis
Idioma
Valor
Bandeira exibida por padrão
Alemão
de
x
Inglês
en
x
Chinês
zh
x
Espanhol
es
x
Francês
fr
x
Italiano
it
x
Japonês
ja
x
Holandês
nl
x
Polonês
pl
Português
pt
x
Russo
ru
x
Sueco
sv
x
Turco
tr
x
Exemplo: para exibir as bandeiras dos idiomas português e inglês, é preciso postar
vads_available_languages=pt ;en
Categoria
Personalização da página de pagamento.
vads_bank_code
Descrição
Campo devolvido na resposta
Código banco associado ao banco emissor.
Formato
n5
Categoria
vads_bank_product
Descrição
Código produto do cartão usado para o pagamento.
Formato
an..3
Valores possíveis
VISA
Désignation
A
Visa Traditional
B
Visa Traditional Rewards
C
Visa Signature
D
Visa Signature Preferred
E
Proprietary ATM
F
Visa Classic
G
Visa Business
G1
Visa Signature Business
G2
Reserved
G3
Visa Business Enhanced
H
Reserved
I
Visa Infinite
J
Reserved
J1
Reserved
J2
Reserved
J3
Visa Healthcare
J4
Reserved
K
Visa Corporate T&E
K1
Visa GSA Corporate T&E
L
Electron
N
Visa Platinium
N1
TBA
P
Visa Gold
Q
Private Label
Q1
Reserved
R
Proprietary
S
Visa Purchasing
S1
Visa Purchasing
S2
Visa Purchasing
S3
Visa Purchasing
S4
Government Services Loan
S5
Commercial Transport EBT
S6
Business Loan
S7
Visa Distribution
T
Reserved
U
Visa TravelMoney
V
Visa VPay
W
Reserved
X
Reserved
Y
Reserved
Z
Reserved
MASTERCARD
Designação
MPN
MASTERCARD PREPAID DEBIT STANDARD-INSURANCE
MPO
MASTERCARD PREPAID DEBIT STANDARD-OTHER
MPP
MASTERCARD PREPAID CARD
MPR
MASTERCARD PREPAID DEBIT STANDARD-TRAVEL
MPT
MASTERCARD PREPAID DEBIT STANDARD-TEEN
MPV
MASTERCARD PREPAID DEBIT STANDARD-VERNMENT
MPW
DEBIT MASTERCARD BUSINESS CARD PREPAID WORK B2B
MPX
MASTERCARD PREPAID DEBIT STANDARD-FLEX BENEFIT
MPY
MASTERCARD PREPAID DEB STANDARD-EMPLOYEE INCENTIVE
MRG
MRH
MASTERCARD UNKNOWN PRODUCT
MRW
PREPAID MASTERCARD BUSINESS CARD
MSG
PREPAID MAESTRO CONSUMER RELOADABLE CARD
MSI
MAESTRO CARD
MWB
WORLD MASTERCARD FOR BUSINESS CARD
MWE
WORLD ELITE MASTERCARD CARD
DLS
DEBIT MASTERCARD CARD-DELAYED DEBIT
MCB
MASTERCARD BUSINESSCARD CARD
MCC
MASTERCARD CREDIT CARD (MIXED BIN)
MVOIR
MASTERCARD FLEET CARD
MCG
LD MASTERCARD CARD
MCO
MASTERCARD CORPORATE CARD
MCP
MASTERCARD PURCHASING CARD
MCS
STANDARD MASTERCARD CARD
MCW
WORLD MASTERCARD CARD
MDG
LD DEBIT MASTERCARD CARD
MDH
WORLD DEBIT EMBOSSED MASTERCARD CARD
MDP
PLATINUM DEBIT MASTERCARD CARD
MDS
DEBIT MASTERCARD CARD
MIU
DEBIT MASTERCARD UNEMBOSSED
MNW
MASTERCARD WORLD CARD
MOC
MPG
DEBIT MASTERCARD STANDARD PREPAID-GENERAL SPEND
MPL
PLATINUM MASTERCARD CARD
MPP
MRG
MRO
MASTERCARD REWARDS ONLY
MRW
PREPAID MASTERCARD BUSINESS CARD
MSB
MAESTRO SMALL BUSINESS CARD
MSI
MAESTRO CARD
MSO
MAESTRO PREPAID OTHER CARD
MSW
PREPAID MAESTRO CORPORATE CARD
OLS
MAESTRO-DELAYED DEBIT
TCB
MASTERCARD BUSINESS CARD-IMMEDIATE DEBIT
TCC
MASTERCARD (MIXED BIN)-IMMEDIATE DEBIT
TCG
LD MASTERCARD CARD-IMMEDIATE DEBIT
TCS
MASTERCARD STANDARD CARD-IMMEDIATE DEBIT
TCW
WORLD SIGNIA MASTERCARD CARD-IMMEDIATE DEBIT
TNW
MASTERCARD NEW WORLD-IMMEDIATE DEBIT
TPL
PLATINUM MASTERCARD-IMMEDIATE DEBIT
WBE
Categoria
vads_birth_day
Descrição
Data de nascimento do portador.
Formato
n..2
Código de erro
76
Categoria
vads_birth_month
Descrição
Mês de nascimento do portador.
Formato
n..2
Código de erro
76
Categoria
vads_birth_year
Descrição
Ano de nascimento do portador.
Formato
n4
Código de erro
78
Categoria
vads_capture_delay
Descrição
Se este parâmetro não é enviado, então o valor padrão definido no Back Office
será usado. Este último pode ser configurado no Back Office por todas as pessoas
devidamente autorizadas.
Formato
n..3
Código de erro
06
Categoria
vads_card_brand
Descrição
Meio de pagamento usado, se disponível (se não vazio).
O valor é procedente dos arquivos de classificação BIN.
Formato
an..127
Valores possíveis
Consultar o parâmetro vads_payment_cards.
Categoria
vads_card_country
Descrição
Campo devolvido na resposta.
Código país do cartão usado para o pagamento segundo a norma ISO 3166.
Formato
ISO 3166
Categoria
vads_card_number
Descrição
Na solicitação de pagamento:
Número de cartão em claro (caso do pagamento silencioso).
Na resposta:
• Número do cartão oculto. Contém os 6 primeiros números, seguido por
"XXXXXX" e finalmente os 4 últimos números.
• IBAN e BIC usados para o pagamento, separados por um "_" no caso de um
pagamento por débito no cartão de crédito.
Formato
an..36
Código de erro
40
Categoria
vads_change_rate
Descrição
Taxa de cambio utilizada para calcular o valor real do pagamento (durante um
pagamento multi-moeda).
Formato
string
Categoria
vads_contracts
Descrição
Permite especificar, para cada rede de aceitação, o contrato comercial a ser usado
sob a forma de lista.
Formato
REDE1=contrato1;REDE2=contrato2;REDE3=contrato3
Código de erro
62
Valores possíveis
As diferentes redes possíveis são:
Valor
Descrição
BANCODOBRASIL_IB
rede Bancodobrasil
BANRISUL_IB
rede Barisul
BOLETO
rede Boleto
BRADESCO_IB
rede Bradesco
CIELO
rede Cielo
ELAVONBR
rede Elavon
ITAU_IB
rede Itau
REDECARD
rede Redecard
SCOPETEF
rede Scopetef
Por exemplo, se você possui um segundo contrato VAD de número 12312312
no seu banco, e que você deseja salvar para um dado pedido um pagamento
por cartão de banco (Visa, MasterCard) neste contrato, então precisará informar
vads_contracts da seguinte forma:
Exemplo:
Observação: este parâmetro é facultativo e é útil somente se você possuir vários
contratos VAD na mesma rede e se você desejar trocar eles dinamicamente em
função do pagamento. Se este parâmetro não é preenchido ou ausente, então o
pagamento será salvo de maneira padrão no seu contrato comercial VAD.
Categoria
vads_contract_used
Descrição
Este campo estabelece o valor do contrato associado à transação. É informado pelo
contrato salvo por padrão na sua loja ou toma o valor do campo vads_contracts
passado na solicitação de pagamento.
Formato
ans..250
Categoria
vads_contrib
Descrição
Informação complementar facultativa destinada a mencionar o nome da
contribuição usada durante o pagamento (Joomla, osCommerce...). Se você usa
uma implementação proprietária, este campo pode receber seu número de lote
interno do módulo que você desenvolveu, por exemplo.
Formato
ans..128
Código de erro
31
Categoria
vads_ctx_mode
Descrição
Estabelecer o modo de solicitação da plataforma de pagamento
Influencia a escolha do certificado a ser usado (certificado de teste ou certificado
de produção) para o cálculo da assinatura.
O modo TEST esta sempre disponível, mesmo depois da criação do certificado de
produção.
Se você esta criando um novo site de e-commerce (ou possui ambiente onde
fatura), você poderá realizar seus testes sem impacto para o site atualmente em
funcionamento.
Formato
string (enum)
Código de erro
11
Erros frequentes:
• O modo não foi enviado para a plataforma de pagamento.
• Não codificar PROD no lugar de PRODUCTION
• Não codificar o valor em minúsculas (teste ou produção). Este campo espera
exclusivamente valores em maiúsculas e sem abreviações.
Valores possíveis
TEST, PRODUCTION
Categoria
vads_currency
Descrição
Código numérico da moeda a ser usada para o pagamento, segundo a norma ISO
4217 (código numérico).
Formato
n3
Código de erro
10
Valor possível
Moeda
Codificação ISO 4217
Real do Brasil
986
Categoria
vads_cust_address
Descrição
Caixa postal do comprador.
Formato
ans..255
Remarque : Les caractères > et < ne sont pas autorisés.
Código de erro
19
Observação:
Parâmetro obrigatório para 3xCB Cofinoga.
Categoria
Descrição
Número de rua do comprador.
Formato
an..5
Código de erro
112
Categoria
Descrição
Número de telefone celular do comprador.
Formato
an..32
Código de erro
77
Categoria
vads_cust_city
Descrição
Cidade do comprador
Formato
an..128
Código de erro
21
Observação:
Categoria
vads_cust_country
Descrição
Permite especificar o código do país do comprador segundo a norma ISO 3166.
Formato
a2
Código de erro
22
Exemplos
de País
valores possíveis
BRASIL
Código
BR
CORSEGA
FR
FRANÇA
FR
GUADALUPE
GP
MARTINICA
MQ
NOVA-CALEDONIA
NC
ST-PIERRE-ET-MIQUELON
PM
POLINÉSIA FRANCESA
PF
Observação:
Categoria
vads_cust_district
Descrição
Bairro do comprador
Formato
ans..127
Código de erro
113
Categoria
vads_cust_email
Descrição
Endereço e-mail do comprador, necessário se você deseja que a plataforma de
pagamento envie um e-mail para o comprador.
Para receber um e-mail, não esqueça de postar este parâmetro no formulário
quando você gera uma solicitação de pagamento.
Formato
ans..150
Código de erro
15
Categoria
Descrição
Nome do comprador
Formato
an..63
Código de erro
104
Observação:
Categoria
vads_cust_id
Descrição
Código do comprado para o vendedor.
Formato
an..63
Código de erro
16
Categoria
vads_cust_last_name
Descrição
Formato
an..63
Código de erro
105
Observação:
Categoria
Descrição
Formato
an..100
Código de erro
121
Categoria
vads_cust_name
Descrição
Este campo esta desvalorizado. Ele foi
vads_cust_first_name e vads_cust_last_name
Formato
an..127
Código de erro
18
Categoria
substituído
pelos
campos
Descrição
CPF/CNPJ
Possibilita identificar de maneira única cada cidadão dentro de um país.
Por exemplo, no Brasil, ClearSale impõe que este campo seja informado com o CPF/
CNPJ (formato numérico, de 11 até 20 dígitos.
Formato
ans..255
Categoria
vads_cust_phone
Descrição
Número de telefone do comprador.
Formato
an..32
Código de erro
23
Observação:
Categoria
vads_cust_state
Descrição
UF / Região do comprador
Formato
an..127
Código de erro
88
Categoria
vads_cust_status
Descrição
Tipo de comprador
Formato
string (enum)
Código de erro
92
Valores possíveis
PRIVATE, COMPANY
Categoria
vads_cust_title
Descrição
Estado civil do comprador (Exemplo Sr., Sra., Srta.).
Formato
an..63
Código de erro
17
Observação:
Categoria
vads_cust_zip
Descrição
CEP do comprado.
Formato
an..64
Código de erro
20
Observação:
Categoria
vads_cvv
Descrição
Código de segurança do cartão (caso do pagamento silencioso).
Na resposta:
Código de segurança oculto.
O comprimento dele pode variar entre 3 ou 4 dígitos em função do tipo de cartão.
Formato
n..4
Código de erro
43
Categoria
Descrição
Valor do pagamento na moeda efetivamente usada para a captura no banco.
Formato
n..12
Exemplos
EXEMPLO PARA UMA LOJA ONDE O DESCONTO É FEITO EM BRL
Pagamento de 10 BRL
Parâmetros enviados no formulário de pagamento
•
vads_amount = 1000
•
vads_currency = 986
Parâmetros devolvidos
•
vads_amount = 1000
•
vads_currency = 986
•
Pagamento de 10 dólares americanos
•
vads_amount = 1000
•
vads_currency = 840
Parâmetros devolvidos
•
vads_amount = 1000
•
vads_currency = 840
•
vads_change_rate= 1.3118 (taxa usada)
•
vads_effective_amount = 762 (vads_amount / vads_change_rate)
Pagamento múltiplo 90 BRL em 3 vezes
•
vads_amount = 9000
•
vads_currency = 986
•
vads_payment_config=MULTI_EXT:data1=3000;data2=2000;data3=4000
Parâmetros devolvidos para a primeira parcela
•
vads_amount = 9000
•
vads_currency = 986
•
Pagamento múltiplo 90 dólares americanos em 3 vezes
•
vads_amount = 9000
•
vads_currency = 840
•
vads_payment_config=MULTI_EXT:20121025=3000;20121026=2000;20121027=4000
Parâmetros devolvidos para a primeira parcela
Categoria
•
vads_amount = 9000
•
vads_currency = 840
•
vads_change_rate= 1.3118 (taxa usada)
•
vads_effective_amount = 2287 (valor 1a parcela 30$ / vads_change_rate)
vads_effective_creation_date
Descrição
Data de registro da transação, no fuso UTC (ou GNT+0) ao formato horário 24h
(AAAAMMJJHHMMSS).
Formato
n14
Categoria
vads_expiry_month
Descrição
Formato
n..2
Código de erro
41
Categoria
vads_expiry_year
Descrição
Formato
n4
Código de erro
42
Categoria
vads_ext_info
Descrição
Permite acrescentar um campo suplementar exibido no e-mail de confirmação de
pagamento para o vendedor.
Esta informação será exibida no Back Office no detalhe da transação (aba Extras),
e será também retornada na URL de notificação.
O nome deve começar por vads_ext_info para ser levado em conta.
vads_ext_info_onomedocampo=valor
Formato
ans
Código de erro
91
Categoria
vads_ext_info_bil_address_complement
Descrição
Exclusivo para o Brasil e ao analisador de fraude ClearSale.
Permite acrescentar um complemento de endereço para o faturamento.
Formato
ans..250
Categoria
vads_ext_info_deadline
Descrição
Permite indicar o prazo de entrega em dia (D dias).
Formato
n
Categoria
vads_ext_info_bil_date_of_birth
Descrição
Permite acrescentar na fatura a data de nascimento do comprador.
Formato : yyyy-mm-ddThh:mm:ss)
Formato
Datetime
Categoria
vads_ext_info_bil_gender
Descrição
Permite mencionar na fatura se o comprador é um homem ou uma mulher.
Formato
n1
Categoria
vads_ext_info_fingerprint_id
Descrição
Identificador único de sessão.
• Ou este código de sessão é gerado pela plataforma.
Neste caso, este parâmetro não deve ser informado.
• Ou este código de sessão é gerado pelo site de e-commerce.
Neste caso, esta parâmetro deve ser informado com o valor do código desejado.
Cuidado, cabe ao site de e-commerce garantir o caráter único dos códigos
de usuários. Toda solicitação de registro contendo um código de usuário já
existente, será recusada, e será exibido uma mensagem de erro.
Formato
string
Codificado em 128 octetos, pode conter maiúsculas ou minúsculas, números ou
hífen ([A-Z] [a-z], 0-9, _, -).
Categoria
vads_ext_info_ship_address_complement
Descrição
Permite acrescentar um complemento de endereço para a entrega.
Formato
ans..250
Categoria
vads_ext_info_ship_date_of_birth
Descrição
Permite indicar para a entrega a data de nascimento do comprador.
Formato
Datetime
Categoria
vads_ext_info_ship_gender
Descrição
Permite mencionar nas informações de entrega se o comprador é um homem ou
uma mulher.
Formato
n1
Categoria
vads_ext_info_donation
Descrição
Parâmetro retornado somente para a url de notificação instantânea (também
chamada IPN) em caso de doação.
Formato
n..12
Categoria
Informação sobre as transações de doação.
vads_ext_info_donation_recipient
Descrição
Identificador HelloAsso da associação que recebeu a doação.
Formato
n..20
Categoria
vads_ext_info_donation_recipient_name
Descrição
Nome da associação que recebeu a doação.
Formato
string
Categoria
vads_ext_info_donation_merchant
Descrição
Identificador da associação que recebeu a doação.
Formato
n8
Categoria
vads_ext_info_donation_contribution
Descrição
Formato
n..12
Categoria
vads_extra_result
Descrição
Código complementar de resposta A significação dela depende do valor informado
em vads_result.
• Quando vads_result vale 30 (erro de solicitação), então vads_extra_result
contém o código numérico do campo que apresenta um erro de preenchimento
ou de formato. Este valor pode ser preenchido a 99 no caso de um erro
desconhecido na solicitação.
Exemplo : se vads_extra_result contém o valor 09, isto significa que o valor
especificado em vads_amount não esta correto .
• Quando vads_result vale 05 (recusado) ou 00 (aceito), então vads_extra_result
contém o código numérico do resultado dos controles de riscos.
Categoria
vads_extra_result
Descrição
Vazio
Nenhum controle efetuado.
00
Todos os controles ocorreram com sucesso.
02
O cartão excedeu o limite autorizado.
03
O cartão pertence à lista cinza do vendedor.
04
O país emissor do cartão pertence à lista cinza do vendedor.
05
O endereço IP pertence à lista cinza do vendedor.
06
O código BIN pertence à lista cinza do vendedor.
07
Detecção de um e-carte bleue.
08
Detecção de um cartão comercial nacional.
09
Detecção de um cartão comercial estrangeiro.
14
Detecção de um cartão com autorização sistemática.
20
Controle de coerência: nenhum país corresponde (país IP, país
cartão, país do comprador).
30
O país do endereço IP pertence à lista cinza.
99
Problema técnico servidor durante o tratamento dos controles
locais.
vads_hash
Descrição
Chave única reenviada somente para a URL de notificação (IPN).
Formato
an64
Categoria
vads_identifier
Descrição
Código único (alias ou referência única de mandato) associado a um meio de
pagamento.
• Ou este código é gerado pela plataforma.
• Ou este código é gerado pela site de e-commerce.
Neste caso, esta parâmetro deve ser informado com o valor do código desejado.
Cuidado, cabe ao site de e-commerce garantir o caráter único códigos de
usuários. Toda solicitação de registro contendo um código de usuário já
existente, será recusada, e será exibido uma mensagem de erro.
Formato
ans..50
Código de erro
30
Categoria
vads_identifier_status
Descrição
Somente presente se a ação solicitada corresponde à criação ou à atualização de
um:
• Token Cartão (assinatura).
• RUM ou referência única de mandato (SEPA)
Formato
Valores possíveis
Categoria
string
Valor
Descrição
CREATED
A solicitação de autorização foi aceita.
O Token Cartão ou RUM foi criado com sucesso.
NOT_CREATED
A solicitação de autorização foi recusada.
O Token Cartão ou RUM não foi criado e não será exibido no Back Office.
UPDATED
O Token Cartão ou RUM foi atualizado com sucesso.
NOT_UPDATED
O Token Cartão ou RUM não foi atualizado.
ABANDONED
O comprador desistiu da ação (devedor).
O Token Cartão ou RUM não foi criado e não será exibido no Back Office.
vads_insurance_amount
Descrição
Valor do seguro para a totalidade do pedido.
Específico ao meio de pagamento PayPal.
Formato
n..12
Código de erro
110
Categoria
vads_language
Descrição
Definido no mesmo idioma exibido na página de pagamento (norma ISO 639-1).
Se o campo não for enviado ou se ele permanecer vazio na solicitação de
pagamento, a página de pagamento será exibida no mesmo idioma do navegador
do comprador.
Na resposta:
Devolve o valor especificado no formulário se o comprador não mudou o idioma
na página de pagamento.
Devolve o idioma selecionado pelo comprador se ele mudou de idioma na página
de pagamento selecionando uma outra bandeira.
Formato
a2
Código de erro
12
Valores possíveis
Categoria
Idioma
Codificação ISO 639-1
Alemão
de
Inglês
en
Chinês
zh
Espanhol
es
Francês
fr
Italiano
it
Japonês
ja
Holandês
nl
Polonês
pl
Português
pt
Russo
ru
Sueco
sv
Turco
tr
Personalização da página de pagamento
vads_nb_products
Descrição
Permite definir a quantidade de produtos contidos no carrinho
Formato
n..12
Categoria
vads_operation_type
Descrição
Permite fazer a diferença entre uma operação de débito e uma de crédito
(reembolso).
Observação:
O campovads_operation_type não é retornado na resposta quando um
pagamento for cancelado ou não finalizado.
Formato
string (enum)
Valores possíveis
DEBIT, CREDIT
Categoria
vads_order_id
Descrição
Número de pedido. Número de pedido relembrado no e-mail de confirmação de
pagamento enviado para o comprador.
Campo no formato alfanumérico. Somente o símbolo especial "-" é autorizado.
Se ele contém um símbolo especial (&, ;, @, etc...), a plataforma de pagamento
retorna um erro.
Formato
an..32
Código de erro
13
Categoria
vads_order_info
Descrição
Formato
an..255
Código de erro
14
Categoria
vads_oder_info2
Descrição
Formato
an..255
Código de erro
14
Categoria
vads_order_info3
Descrição
Formato
an..255
Código de erro
14
Categoria
vads_page_action
Descrição
Define a operação a ser efetuada.
Formato
string (enum)
Código de erro
46
Valores possíveis
• PAYMENT
• REGISTER
• REGISTER_UPDATE
• REGISTER_PAY
• REGISTER_SUBSCRIBE
• REGISTER_PAY_SUBSCRIBE
• SUBSCRIBE
• REGISTER_UPDATE_PAY
• ASK_REGISTER_PAY
Categoria
vads_payment_cards
Descrição
Apresenta a lista dos meios de pagamento que serão propostos ao comprador,
separados por " ;".
Se a lista tem somente um meio de pagamento, a página para preencher os dados
deste meio de pagamento será diretamente exibida. Se não, a página de seleção
dos meios de pagamentos será exibida.
Se este parâmetro esta vazio (aconselhado) então os meios de pagamento elegíveis
(moedas, obrigações técnicas, etc) associadas à loja serão propostas.
Precisões dadas para o meio de pagamento Itau Internet Banking :
Para o meio de pagamento Itau Internet Banking, vads_payment_cards deve ser
preencher a ITAU_IB. Se o campo estiver vazio, o pagamento é cancelado
Formato
typo1;typo2;typo3
Código de erro
08
O formulário de pagamento será recusado nos seguintes casos:
• o valor transmitido não está presente na lista abaixo.
• TODOS, ALL não são valores aceitos. Para oferecer todos os meios de pagamento
este parâmetro não deve ser enviado ou postado vazio.
• o valor passado não corresponde ao meio de pagamento da sua loja.
• Seu contrato e-commerce foi fechado pelo seu banco. Entrar em contato com
o serviço de atendimento ao cliente da sua plataforma de pagamento.
Valores possíveis
Valor
Descrição
AMEX
American Express
AURA
Aura
BANCODOBRASIL_IB
BANRISUL_IB
Banrisul
BOLETO
Boleto
BRADESCO_IB
CIELO_ELO
Elo
DINERS
Diners
DISCOVER
Discover
E_SITEF
E_SITEF
HIPERCARD
Hipercard
ITAU_IB
Para o meio de pagamento Itau Internet
Banking, vads_payment_cards deve ser
preencher a ITAU_IB. Se o campo estiver vazio,
o pagamento é cancelado
JCB
Jcb
MAESTRO
Maestro
MASTERCARD
MasterCard
VISA
Visa
VISA_ELECTRON
Visa Electron
Categoria
vads_payment_certificate
Descrição
Campo retornado à resposta.
Este campo é informado pela plataforma de pagamento nos casos em que a
autorização foi efetuada com sucesso.
Formato
an40
Categoria
vads_payment_config
Descrição
Designa o tipo de pagamento: à vista ou parcelado.
• Para um pagamento simples, o valor deve ser igual a SINGLE.
• Para um pagamento parcelado com valores e datas fixas, o valor deve ser igual
a MULTI: seguido dos pares chave=valor separados por « ; ».
Os parâmetros são os seguintes:
• « first » indica o valor do primeiro pagamento (na sua menor unidade
monetária).
• « count » indica o número total do parcelas.
• « period » indica o intervalo em quantidade de dias entre 2 pagamentos.
A ordem dos campos associados aMULTI é imposta.
• Para um pagamento parcelado, com um calendário de pagamento, o valor deve
ser igual a MULTI_EXT: seguido dos pares data=valor separados por « ; ».
As datas não podem ser vencidas.
O uso do valor MULTI_EXT precisa da ativação da opção Pagamento parcelado
adiantado.
Formato
string (enum)
Código de erro
07
Valores possíveis
• SINGLE
• MULTI:first=valor_Init;count=Qtde_parcelas;period=QtdeDeDia
• MULTI_EXT:data1=valor1;data2=valor2;data3=valor3
Exemplo 1
MULTI permite definir um pagamento parcelado.
O valor de cada prestação corresponde ao valor divido pela quantidade de parcelas.
O valor da primeira prestação pode ser diferente e especificado no parâmetrofirst.
Se houver uma sobra diferente de zero, será recolocado sobre o valor da última
parcela.
Solicitação de pagamento:
• vads_capture_delay=2
• vads_currency=986
• vads_amount=20000
• vads_payment_config=MULTI:first=10000;count=4;period=30
Resultado:
Um primeiro pagamento de 100 BRL será entregue no banco a D+2
(vads_capture_delay).
Um segundo pagamento de 33.33 BRL será efetuado a D+32vads_capture_delay
+ period.
Um segundo pagamento de 33.33 BRL será efetuado a D+62.
Um quarto e último pagamento de 33.34 BRL será efetuado a D+92.
O total é de 200 BRL (vads_amount= 20000). O restante foi acrescentado ao valor
da última parcela.
Esta instrução permite criar imediatamente 4 pagamentos com o mesmo
número de transação mas com uma quantidade de parcelas diferentes
(vads_sequence_number).
Exemplo 2
MULTI_EXT permite definir um pagamento parcelado. Você poderá definir a data
e o valor de cada parcela.
Solicitação de pagamento MULTI_EXT :
• vads_currency=986
• vads_amount=10000
• vads_payment_config= MULTI_EXT:20150601 =5000; 20150701 =2500;
20150808 =2500
Resultado:
O primeiro pagamento ocorrerá dia 1° de junho de 2015, de um valor de 50 BRL.
O segundo pagamento ocorrerá dia 1° de julho de 2015, de um valor de 25 BRL.
O último pagamento ocorrerá dia 8 de agosto de 2012 , de um valor de 25 BRL.
Observação:
A soma total dos valores deve ser igual ao valor do campo vads_amount. A data da
última parcela não pode ser superior a 12 mezes em relação à data de apresentação
do formulário. Se a data da última parcela é posterior à data de vencimento do
cartão, nenhum vencimento será salvo e o comprador será notificado por uma
mensagem escrita.
Categoria
vads_payment_error
Descrição
Códigos de erros que podem ser exibidos quando um pagamento for recusado.
Formato
n..3
Valores possíveis
Código
de erro
Mensagem de erro
Código de
Mensagem de erro
erro
1
A transação não foi encontrada.
72
Autorização recusada pela Cofinoga.
2
A transação não foi encontrada.
73
Autorização de 1 BRL.
3
Esta ação não esta autorizada para uma
transação com este status {0}.
74
Configuração de pagamento inválida.
4
Esta transação não esta autorizada neste
contexto.
75
A PayPal recusou a operação.
5
A transação já existe.
76
Devido a um problema técnico, não podemos
responder a sua solicitação.
6
Valor de transação inválida.
77
7
Esta ação não é mais possível para uma
transação criada nesta data.
78
Identificador de transação não definido.
8
A data de vencimento do cartão não autoriza
esta ação.
79
Identificador de transação não definido.
9
CVV obrigatório para o cartão.
80
Identificador de transação vencido.
10
O valor do reembolso é superior ao valor
inicial.
81
Conteúdo do tema config inválido.
11
A soma dos reembolsos efetuados é superior
ao valor inicial.
82
O reembolso não é autorizado.
12
A duplicação de um crédito (reembolso) não é
autorizado.
83
Valor de transação fora dos valores permitidos.
13
84
14
85
15
86
16
87
17
A configuração remota do contrato Aurore
falhou.
88
18
A análise da resposta Cetelem falhou.
89
A modificação não é autorizada.
19
Moeda desconhecida.
90
Um erro foi encontrado durante o reembolso desta
transação.
20
Tipo de cartão inválido.
91
Nenhuma opção de pagamento ativada para este
contrato.
21
Nenhum contrato encontrado para este
92
pagamento Favor mudar os dados ou entrar
em contato com seu gerente em caso de falhas
repetidas.
Um erro ocorreu durante o cálculo do canal de
pagamento.
22
Loja não encontrada.
93
Um erro ocorreu durante o retorno do comprador
para a página de finalização de pagamento.
23
Contrato ambíguo.
94
Um erro técnico ocorreu.
24
Contrato inválido.
95
25
96
Um erro foi encontrado durante a captura desta
transação.
26
Número de cartão inválido.
97
Data de apresentação esta distante demais.
Código
de erro
Mensagem de erro
Código de
Mensagem de erro
erro
27
98
Data de transação inválida.
28
99
Um erro ocorreu durante o cálculo da procedência
do pagamento.
29
100
Controle cartão comercial falhou.
30
Número de cartão inválido (Luhn).
101
Recusado porque a primeira parcela foi recusada.
31
Número de cartão inválido (comprimento).
102
Buyster recusou a operação.
32
Número de cartão inválido (não encontrado)
103
A sincronização do status da transação com o
sistema externo falhou.
33
Número de cartão inválido (não encontrado)
104
Um erro foi encontrado durante a captura desta
transação.
34
Controle cartão com autorização sistemática
falhou.
105
Um erro de segurança foi encontrado durante o
processo 3DS desta transação.
35
Controle e-Carte Bleue falhou.
106
Moeda não adequada para este contrato e/ou esta
loja.
36
A transação foi recusada pelo controle dos
riscos.
107
O cartão associado ao alias não esta mais válido.
37
Interrupção não gerenciada durante o
pagamento.
108
38
109
Prazo de espera excedido quando o comprador foi
redirecionado.
39
A transação foi recusada pelo 3D Secure.
110
Cartão de pagamento não adequado para este
contrato.
40
111
Transações sem transferência de responsabilidade
recusadas.
41
112
O cancelamento não é autorizado.
42
Um erro interno ocorreu durante a consulta do 113
número de cartão.
A duplicação não é autorizada.
43
Um erro interno ocorreu durante a consulta do 114
número de cartão.
Forçar não é autorizado.
44
Não é possível forçar uma autorização de 1
BRL.
115
O reembolso não é autorizado.
45
Moeda inválida para a modificação.
116
Pagamento manual não autorizado para este
cartão.
46
O valor é superior ao valor autorizado.
118
Pagamento manual parcelado não autorizado para
este cartão.
47
A data de apresentação desejada é posterior à
data de validade da autorização.
119
A data submetida é inválida.
48
A modificação requerida é inválida.
120
A opção de pagamento da transação inicial não
pode ser aplicada.
49
Definição do pagamento múltiplo inválido.
124
Cartão inativo.
50
Loja desconhecida.
125
Pagamento recusado pelo comprador.
51
Taxa desconhecida.
126
Esta ação é impossível porque a sequência de
pagamento não acabou.
52
O contrato acabou desde o {0}.
132
53
A loja {0} fechou desde o {1}.
135
A integração da página de pagamento dentro de
uma iframe não é autorizada.
54
Parâmetro recusado porque pode conter
dados sensíveis {0}.
136
Transações derivadas recusadas, sem transferência
de responsabilidade na primeira transação.
55
137
A transação já existe.
57
Erro na recuperação do alias.
138
O reembolso parcial não é permitido para esta
transação.
58
O status do alias não é compatível com esta
operação.
139
Reembolso recusado.
59
Erro na recuperação do alias.
141
O analisador de risco recusou esta transação.
Código
de erro
Mensagem de erro
Código de
Mensagem de erro
erro
60
Alias existente.
142
O tipo de cartão usado não é válido com o modo
de pagamento solicitado.
61
Alias inválido.
143
62
Criação de alias recusada.
144
Uma transação em modo produção foi marcada em
modo teste pelo adquirente.
63
A assinatura já existe.
145
Uma transação em modo teste foi marcada em
modo produção pelo adquirente.
64
Esta assinatura já foi cancelada.
146
Código sms inválido.
65
Este assinatura não é válida.
147
O módulo de gestão de fraudes solicitou a recusa
desta transação.
66
A regra de recorrência não é válida.
148
responder a sua solicitação. A transação não foi
criada.
67
Criação da assinatura recusada.
149
O tempo limite da sessão de pagamento acabou
(caso do comprador redirecionado para o ACS e
que não finaliza a autentificação 3D Secure).
69
150
responder a sua solicitação. A transação não foi
criada.
70
Código país inválido.
71
Configuração do serviço web inválido.
Categoria
vads_payment_option_code
Descrição
Permite definir o código da opção usada.
Formato
string
Código de erro
103
Categoria
vads_payment_seq
Descrição
Detalhes de transações realizadas.
Formato
json
vads_payment_seq (formato JSON) descreve a sequência de pagamento
fracionado. Ele contém os elementos:
• "trans_id" : número de transação global a sequência de pagamento.
• "transaction" : tabela das transações da seqüência. Os elementos são os
seguintes:
Nome do campo
Descrição
amount
Valor da sequência da transação.
operation_type
Operação de débito.
auth_number
Número de autorização devolvido pelo servidor do banco (se não vazio).
capture_delay
•
Se este parâmetro não é enviado, então o valor padrão definido no Back
Office será usado. Este último pode ser configurado no Back Office por
todas as pessoas devidamente autorizadas.
card_brand
Meio de pagamento usado.
card_number
Número de cartão.
expiry_month
expiry_year
payment_certificate Certificado do pagamento.
presentation_date
Data de captura no banco solicitada.
trans_id
Número de transação.
ext_trans_id
Campo vazio para o pagamento por cartão
sequence_number
trans_status
Tabela 41 : JSON
Nota: as transações canceladas também estão presentes na tabela (informação
dada no parâmetro trans_status de JSON).
Categoria
vads_payment_src
Descrição
Permite definir a origem do pagamento.
Formato
string (enum)
Código de erro
60
Valores possíveis
Categoria
Valor
Descrição
EC
E-commerce: pagamento efetuado na página de pagamento.
MOTO
MAIL OR TELEPHONE ORDER :pagamento efetuado por um operador decorrente de
um pedido por telefone ou e-mail.
CC
Call center : pagamento efetuado via um call center.
OTHER
Outro : pagamento efetuado em uma outra fonte como por exemplo o Back Office.
vads_pays_ip
Descrição
Código país do endereço IP do comprador segundo a norma ISO 3166.
Formato
a2
Categoria
vads_presentation_date
Descrição
• Data de captura no banco solicitada.
Formato
n14
Categoria
Descrição
Permite definir o valor dos diferentes artigos contidos no carrinho.
N corresponde ao índice do artigo. (0 para o primeiro;1 para o segundo)
O valor será expresso na menor unidade da moeda.
Formato
n..12
Código de erro
102
Categoria
vads_product_labelN
Descrição
Permite definir a denominação de cada um dos artigos contidos no carrinho.
Formato
an..255
Observação:
Favor não utilizar dígitos que não sejam alfabéticos ou numéricos (os espaços não
são autorizados, por exemplo) e respeitar a RegEx ^[a-zA-Z0-9]{1,255}$ .
Código de erro
97
Categoria
vads_product_qtyN
Descrição
Permite definir a quantidade de cada um dos artigos contidos no carrinho.
Formato
n..12
Código de erro
101
Categoria
vads_product_refN
Descrição
Permite definir uma referência para cada um dos artigos contidos no carrinho.
Formato
an..64
Código de erro
100
Categoria
vads_product_typeN
Descrição
Permite definir o tipo de produto contido no carrinho.
Formato
string (enum)
Código de erro
98
Valores possíveis
Valor
Descrição
FOOD_AND_GROCERY
Produtos alimentares e de mercadinho
AUTOMOTIVE
Automóveis / Motos
ENTERTAINMENT
Entretenimento / Cultura
HOME_AND_GARDEN
Casa e jardim
HOME_APPLIANCE
Equipamentos para a casa
AUCTION_AND_GROUP_BUYING
Leilões e compras em grupo
FLOWERS_AND_GIFTS|
Flores e presentes
COMPUTER_AND_SOFTWARE
Computadores e softwares
HEALTH_AND_BEAUTY
Saúde e beleza
SERVICE_FOR_INDIVIDUAL
Serviços para pessoa física
SERVICE_FOR_BUSINESS
Serviços para pessoa jurídica
SPORTS
Esportes
CLOTHING_AND_ACCESSORIES
Roupas e acessórios
TRAVEL
Viagem
HOME_AUDIO_PHOTO_VIDEO
Som, imagem e vídeo
TELEPHONY
Telefonia
Tabela 42 : Valores associados a vads_product-type0
Categoria
Descrição
Número da parcela da assinatura.
Formato
n
Categoria
vads_recurrence_status
Descrição
Status da assinatura.
Somente presente se a ação solicitada corresponde à criação de uma assinatura
(REGISTER_SUBSCRIBE, SUBSCRIBE, REGISTER_PAY_SUBSCRIBE).
Formato
Valores possíveis
string
Valor
Descrição
CREATED
A assinatura foi criada com sucesso.
O detalhe da assinatura está disponível no Back Office.
NOT_CREATED
A assinatura não foi criada e portanto não esta disponível no Back
Office.
ABANDONED
O comprador desistiu da solicitação de criação da assinatura (devedor).
Valor
Categoria
Descrição
A assinatura não foi criada e portanto não esta disponível no Back
Office.
Descrição
Permite especificar a mensagem se o pagamento for recusado no caso de um
redirecionamento automático para o site de e-commerce.
Formato
ans..255
Código de erro
37
Categoria
Descrição
Permite definir um prazo em segundos antes do redirecionamento automático
para o site de e-commerce no final de uma pagamento recusado.
O valor oscila entre 0 e 600s.
Após este tempo, o comprador será redirecionado para a URL informada no
vads_url_refusal. Se este campo não foi enviado, o comprador será redirecionado
para a URL informada no vads_url_return ou para a URL de retorno informada no
Back Office. Se o URL de retorno não é definida, o comprador será redirecionado
para a URL da loja.
Formato
n..3
Código de erro
36
Categoria
Redirecionamento para o site de e-commerce.
Descrição
Permite especificar a mensagem no final de um pagamento aceito no caso de um
redirecionamento automático para o site de e-commerce.
Formato
ans..255
Código de erro
35
Categoria
Descrição
Permite definir um prazo em segundos antes do redirecionamento automático
para o site de e-commerce no final de um pagamento aceito.
O valor oscila entre 0 et 600s.
Após este tempo, o comprador será redirecionado para a URL informada no
vads_url_success. Se este campo não foi enviado, o comprador será redirecionado
para a URL informada no vads_url_return ou para a URL de retorno informada no
Back Office. Se o URL de retorno não é definida, o comprador será redirecionado
para a URL da loja.
Formato
n..3
Código de erro
34
Categoria
vads_result
Descrição
Código de retorno da ação solicitada.
Formato
n2
Valores possíveis
Categoria
Valor
Descrição
00
Ação efetuada com sucesso.
02
O vendedor deve entrar em contato com o banco do portador. Desvalorizado.
05
Ação recusada.
17
Cancelamento comprador.
30
Erro de formato da solicitação. Associar com o preenchimento do campo
vads_extra_result.
96
Erro técnico.
vads_return_mode
Descrição
Permite especificar o método de envio dos dados para o site de e-commerce.
Formato
string (enum)
Código de erro
48
Valores possíveis
Nome do campo
vads_return_mode
Categoria
Valor
Descrição
ausente, vazio
ou NONE
Nenhum parâmetro será transmitido à URL de
retorno para o site de e-commerce.
GET
Os campos de retorno serão enviados à URL de
retorno sob a forma de um formulário HTTP GET
(na "query string").
POST
Os campos de retorno serão enviados à URL de
retorno sob a forma de um formulário HTTP POST.
Se a volta para a loja ocorre em um ambiente não
httpsentão o navegado exibirá para o comprador
um pop-up de segurança.
vads_risk_analyzis_result
Descrição
Reenvia o resultado da análise de fraude efetuada por um sistema externo (ClearSale,
CyberSource,...).
Reenviado para a url de notificação instantânea (também chamada IPN) e nos
parâmetros de retorno.
Formato
ans
Valores possíveis
Valores comuns a todos os analisadores de riscos
INVALID_CREDENCIAL
Falha de configuração do contrato de análise de riscos.
COMUNICATION_PROBLEM
Não foi possível se comunicar com o analisador de riscos.
DATA_PROCESSING_PROBLEM
Falha durante o tratamento do envio ou da resposta do analisador de
riscos.
MISSING_MANDATORY_ORDER_INFO
Dados relativos ao pedido estão faltando.
MISSING_MANDATORY_SHIPPING_INFO
Dados relativos à entrega estão faltando.
MISSING_MANDATORY_SHIPPING_ADDRESS_INFO Dados relativos ao endereço de entrega estão faltando.
MISSING_MANDATORY_BILLING_INFO
Dados relativos ao faturamento estão faltando.
MISSING_MANDATORY_BILLING_ADDRESS_INFO
Dados relativos ao endereço de faturamento estão faltando.
MISSING_MANDATORY_CARD_INFO
Dados sobre o meio de pagamento estão faltando.
MISSING_MANDATORY_CUSTOMER_INFO
Dados sobre o comprador estão faltando.
Tabela 43 : Valores associados a vads_risk_analyzis_result comuns a todos os tipos de analisadores de riscos
ClearSale
APA
Automatically approved
A transação esta automaticamente aprovada conforme as
configurações.
APM
Manually approved - order manually
approved by analyst's decision
A transação foi manualmente aprovada por um analista.
RPM
Reproved with no suspect
O pedido foi recusado devido a uma falta de informações sobre
o comprador conforme à política aplicada.
AMA
Waiting for manual analysis - order is in a
queue waiting for analysis
Análise manual em espera. O pedido esta na lista de espera para
análise.
ERR
Error
Erro
NVO
New order - order waiting for score
Novo pedido. Tratamento e classificação em andamento.
SUS
Suspended order - order suspended by fraud
suspicion
Pedido manualmente suspenso. O pedido esta suspenso por
suspeita de fraude.
CAN
Canceled - order canceled by user
Pedido cancelado. O pedido foi cancelado pelo vendedor.
FRD
Order confirmed as a fraud
Fraude confirmada com o operador do cartão de crédito ou do
titular do cartão.
RPA
Automatically reproved based on parameters Pedido recusado automaticamente. O pedido foi recusado
within risk analyzer
conforme à aplicação das configurações da análise de fraude
externa.
RPP
Automatically reproved based customer or
ClearSale policy
Pedido recusado automaticamente. O pedido foi recusado
conforme à aplicação da política cliente ou ClearSale.
Tabela 44 : Valores associados a vads_risk_analyzis_result - ClearSale
CyberSource
100
SUCCESS
A transação foi efetuada com sucesso.
101
MISSING_FIELDS
A transação foi recusada. Um ou mais campos estão faltando.
102
INVALID_FIELDS
A transação foi recusada. Um ou mais campos contém dados
inválidos.
150
ERROR_GENERAL_SYSTEM_FAILURE
Erro.
151
SERVER_TIME_OUT
Erro. A solicitação foi recebida mas o prazo foi excedido. Este
erro não inclui prazos excedidos entre o cliente e o servidor.
CyberSource
152
SERVICE_TIME_OUT
Erro. A solicitação foi recebida mas um serviço não foi concluído
no devido tempo.
202
CARD_EXPIRED
Recusada. Cartão vencido.
231
ACCOUNT_NUMBER_INVALID
Recusada. Número de conta inválido.
234
ACCOUNT_PROBLEM
Recusado. Um problema ocorreu com a configuração
CyberSource do vendedor.
400
FRAUD_SCORE_TOO_HIGH
Recusada. O valor da fraude excede o limiar de tolerância.
480
SUCCESS_TO_REVIEW
O pedido esta marcado para ser examinado pelo Decision
Manager.
481
SUCCESS_TO_REJECT
O pedido foi recusado pelo Decision Manager.
Tabela 45 : Valores associados a vads_risk_analyzis_result - Cybersource
Categoria
Descrição
Retorna o resultado da análise de gerenciamento dos riscos avançados efetuada pela
plataforma de pagamento.
Re-enviado na URL de notificação instantânea (também chamada IPN) e nas
configurações de retorno.
Formato
ans
Valores possíveis
Valores
Descrição
ENABLE_3DS
3D Secure ativado
DISABLE_3DS
3D Secure desativado
MANUAL_VALIDATION
A transação foi criada em validação manual.
A captura do pagamento esta bloqueada temporariamente para permitir ao vendedor
efetuar todas as verificações desejadas.
REFUSE
RUN_RISK_ANALYSIS
Chamada para um analisador de riscos externos sob a condição que o vendedor
possua um contrato
Consultar a descrição do campo vads_risk_analysis_result para identificar a lista dos
valores possíveis e a descrição deles.
INFORM
Uma alerta apareceu.
O vendedor é avisado quando um risco é identificado.
O vendedor é informado via uma ou mais regras do centro de notificação (URL de
notificação, e-mail ou SMS).
Categoria
vads_risk_control
Descrição
Permite definir o resultado do controle de riscos.
Formato
Valores possíveis
controle1=resultado1;controle2=resultado2
Valor
Descrição
CARD_FRAUD
Controla a presença do número de cartão do comprador
na lista cinza de cartões.
SUSPECT_COUNTRY
Controla a presença do país emissor do cartão do
comprador na lista dos países proibidos.
IP_FRAUD
Controla a presença do endereço IP do comprador na lista
cinza de IP.
CREDIT_LIMIT
Controla a frequência e os valores de compra de um
mesmo número de cartão, ou o valor máximo de um
pedido.
BIN_FRAUD
Controla a presença do código BIN do cartão do
comprador na lista cinza dos códigos BIN.
ECB
Controla se o cartão do comprador é do tipo e-carte bleue.
CARD_COMMERCIAL
Controla se o cartão do comprador é um cartão comercial.
SYSTEMATIC_AUTO
Controla se o cartão do comprador é um cartão com
autorização sistemática.
INCONSISTENT_COUNTRIES
Controla se o país do endereço IP, o país emissor do
cartão de pagamento, e o país do endereço do comprador
estão coerentes entre eles.
NON_WARRANTY_PAYMENT
Controla a transferência de responsabilidade da transação.
SUSPECT_IP_COUNTRY
Controle a presença do país do comprador, identificado
pelo endereço IP dele, na lista dos países proibidos.
Os diferentes valores possíveis para resultado’ são :
Categoria
Valor
Descrição
OK
OK
WARNING
Controle informativo não sucedido.
ERROR
Controle bloqueante não sucedido.
vads_risk_primary_warranty
Descrição
Especifico à doação (ou transação secundária).
Permite sobrescrever a configuração do controle de risco Controle da
transferência de responsabilidade da transação primária.
Formato
string (enum)
Código de erro
117
Valores possíveis
Categoria
Valor
Descrição
DEFAULT ou vazio
Valor por padrão. Uso da configuração da loja alva.
IGNORE
Ignora o valor da transferência de responsabilidade da transação
primária antes de criar a transação secundária.
CHECK
Força o controle da transferência de responsabilidade da transação
primária antes de criar a transação secundária.
Informações sobre as transações de doação.
vads_sequence_number
Descrição
Contém o número de sequência da transação.
Esta campo é sempre preenchido com 1 no caso de um pagamento à vista
(vads_payment_config=SINGLE).
Para um pagamento parcelado, este campo tomará o valor 1 para a primeira
parcela, o valor 2 para a segunda parcela, o valor 3 para a terceira parcela etc.
Observação:
O campo vads_sequence_number não é retornado na resposta quando um
pagamento for cancelado ou não finalizado.
Categoria
vads_ship_to_city
Descrição
Permite definir a cidade do comprador.
Formato
an..128
Código de erro
83
Categoria
Descrição
Permite definir o código do país do comprador segundo a norma ISO 3166.
Formato
a2
Código de erro
86
Exemplos
de País
valores possíveis
BRASIL
Categoria
Código
BR
CORSEGA
FR
FRANÇA
FR
GUADALUPE
GP
MARTINICA
MQ
NOVA-CALEDONIA
NC
ST-PIERRE-ET-MIQUELON
PM
POLINÉSIA FRANCESA
PF
vads_ship_to_delivery_company_name
Descrição
Permite definir o nome do transportador.
Formato
ans..127
Código de erro
96
Categoria
Descrição
Permite definir o bairro.
Formato
ans..127
Código de erro
115
Categoria
Descrição
Permite definir o nome do comprador.
Formato
ans..63
Código de erro
106
Categoria
Descrição
Permite definir o sobrenome do comprador.
Formato
ans..63
Código de erro
107
Categoria
Descrição
Razão social do local de entrega.
Formato
an..100
Código de erro
125
Categoria
vads_ship_to_name
Descrição
Permite definir o sobrenome do comprador.
Formato
ans..63
Código de erro
80
Categoria
Descrição
Permite definir o número de telefone do comprador.
Formato
ans..32
Código de erro
87
Categoria
vads_ship_to_speed
Descrição
Permite definir o modo de entrega.
Formato
string (enum)
Código de erro
95
Valores possíveis
STANDARD, EXPRESS
Categoria
vads_ship_to_status
Descrição
Permite definir o tipo de endereço de entrega.
Formato
string (enum)
Código de erro
93
Valores possíveis
PRIVATE, COMPANY
Categoria
vads_ship_to_state
Descrição
Permite definir a UF do comprador.
Formato
ans..127
Código de erro
84
Categoria
vads_ship_to_street
Descrição
Permite definir o endereço do comprador.
Formato
ans..255
Código de erro
81
Categoria
Descrição
Permite definir a segunda linha do endereço do comprador.
Formato
ans..255
Código de erro
82
Categoria
Descrição
Permite definir o número de rua.
Formato
an..5
Código de erro
114
Categoria
vads_ship_to_type
Descrição
Permite definir o tipo de entrega.
Formato
string (enum)
Código de erro
94
Valores possíveis
• RECLAIM_IN_SHOP para retirar a mercadoria na loja.
• RELAY_POINT para a utilização de uma rede de pontos de entrega terceirizada
(Kiala, Alveol, etc).
• RECLAIM_IN_STATION para retirar num aeroporto, uma agência de viagens ou
outros.
• PACKAGE_DELIVERY_COMPANY para a entrega por transportadora (Colissimo,
UPS, etc).
• ETICKET para emitir de uma passagem eletrônica, baixar.
Categoria
vads_ship_to_user_info
Descrição
Informação sobre o usuário na origem do pagamento.
Este parâmetro será reenviado na resposta com o valor enviado na solicitação
Observação:
Por razões de retro-compatibilidade, pode-se utilizar este campo para informar o
CPF/CNPJ (Identificação legal, em formato numérico, tendo entre 11 e 20 dígitos)
exigido pelo módulo de gerenciamento de fraude ClearSale. No entanto, o CPF/
CNPJ pode ser informado no campo vads_cust_national_id.
Formato
ans..255
Código de erro
116
Categoria
vads_ship_to_zip
Descrição
Permite definir o CEP do comprador.
Formato
an..64
Código de erro
85
Categoria
vads_shipping_amount
Descrição
Permite definir o valor das despesas de entrega para a totalidade do pedido.
Formato
n..12
Código de erro
109
Categoria
vads_shop_name
Descrição
Permite definir o nome da loja que será exibido nos e-mails de confirmação de
pagamento.
Formato
ans..127
Código de erro
72
Categoria
vads_shop_url
Descrição
URL da loja que será exibida na página de pagamento e nos e-mails de confirmação
de pagamento.
Este parâmetro pode sobrescrever o valor padrão da sua loja.
Formato
ans..127
Código de erro
73
Categoria
vads_site_id
Descrição
Valor gerado durante o cadastro na plataforma de pagamento.
O valor pode ser consultado na interface do Back Office no menu Configuração >
Loja > Certificados por todas as pessoas autorizadas.
No caso de um valor não correto, durante um pagamento, o comprador recebe
uma mensagem de erro exibida no seu navegador.
O pagamento fica então impossível e a transação é definitivamente interrompida.
Um e-mail de alerta é então enviado para o contato administrativo da loja. Contém
o formulário que a plataforma não conseguiu tratar com o valor da assinatura.
Formato
n8
Código de erro
02
Categoria
vads_subscription
Descrição
Parâmetro facultativo usado quando criar uma assinatura. Designa o identificador
da assinatura a ser criada.
Duas opções são possíveis:
• Ou a gestão destes identificadores é delegada à plataforma.
Se a criação da plataforma foi bem sucedida, a resposta apresentará o valor
gerado pela plataforma.
• Ou este identificador é feito pelo site de e-commerce.
Neste caso, esta parâmetro deve ser informado com o valor do identificador
de assinatura desejado. Cuidado, cabe ao site de e-commerce garantir o
caráter único dos identificadores de assinatura. Toda solicitação de assinatura
contendo um identificador de assinatura já existente, será recusada, e será
exibido uma mensagem de erro.
Formato
ans..50
Código de erro
63
Categoria
vads_sub_amount
Descrição
Parâmetro obrigatório usado quando criar uma assinatura.
Faz referência ao valor das parcelas da assinatura para todas as parcelas, tirando
as que podem ser definidas por vads_sub_init_amount_number.
O valor deve ser apresentado na menor unidade monetária da moeda .
Formato
n..12
Código de erro
65
Categoria
vads_sub_currency
Descrição
Indica a moeda a ser usada para a assinatura, segundo a norma ISO 4217.
Formato
n3
Exemplos de valores As moedas possíveis são as seguintes:
possíveis
Moeda
Codificação ISO 4217
Real do Brasil
986
Código de erro
67
Categoria
vads_sub_desc
Descrição
Designa a regra da assinatura a ser criada.
O valor esperado neste parâmetro é um string de símbolos conforme a
especificação iCalendar, ou Internet Calendar, descrita na RFC5545 (ver http://
tools.ietf.org/html/rfc5545).
Esta especificação permite, dentro de outras coisas, definir regras complexas de
assinatura, via a propriedade RRULE.
Por razões técnicas. não é possível definir períodos de assinatura inferiores a um
dia.
As palavras chaves SECONDLY" / "MINUTELY" / "HOURLY não são levados em conta.
Exemplos:
• Para definir parcelas de pagamento que ocorrem o último dia de cada mês,
durante 12 meses, a regra se escreve:
RRULE:FREQ=MONTHLY;BYMONTHDAY=28,29,30,31;BYSETPOS=-1;COUNT=12
Esta regra significa que se o mês corrente não contém um dia 31, então o motor
levará em conta o dia 30. Se o dia 30 não existe, então ele levará em conta o
dia 29, e assim por diante até o dia 28.
Outra
versão
desta
RRULE:FREQ=MONTHLY;COUNT=5;BYMONTHDAY=-1
regra
é:
• Para definir parcelas de pagamento que ocorrem o dia 10 de cada mês,
durante 12 meses, a regra de assinatura se escreve da seguinte forma:
RRULE:FREQ=MONTHLY;COUNT=12;BYMONTHDAY=10
• Para definir parcelas de pagamento que ocorrem todo trimestre, até o
31/12/2016:
RRULE:FREQ=YEARLY;BYMONTHDAY=1;BYMONTH=1,4,7,10;UNTIL=20161231
As parcelas ocorrerão todo dia 1° de janeiro, abril, julho e outubro. A
quantidade total deles depende da data de início da assinatura (ver parâmetro
vads_sub_effect_date).
Para maiores detalhes e exemplos, você pode consultar o site http://
recurrance.sourceforge.net/.
Formato
string
Código de erro
64
Categoria
vads_sub_effect_date
Descrição
Parâmetro obrigatório usado para criar uma assinatura que permite definir a data
de inicio na assinatura.
Este parâmetro não coincide sistematicamente com a data da primeira parcela,
que depende somente do parâmetrovads_sub_desc.
A data de inicio indica quando a assinatura inicia. O formato desta data
éAAAAMMJJ
Exemplo : para o 1° de fevereiro 2015, use o valor 20150201
Formato
n8
Código de erro
69
Categoria
vads_sub_init_amount
Descrição
Parâmetro facultativo usado quando criar uma assinatura. Representa o valor das
parcelas da assinatura para as primeiras parcelas.
A quantidade destas primeiras
parcelas
é
definido
pelo
parâmetro
Este valor é apresentado na moeda definida pelo parâmetro vads_sub_currency e
esta expresso na sua unidade indivisível .
Formato
n..12
Código de erro
66
Categoria
Descrição
Parâmetro facultativo usado quando criar uma assinatura. Representa
a quantidade de parcelas pelas quais o valor terá que ser aplicado
vads_sub_init_amount.
Uma vez esta quantidade de parcelas excedida, é o valor vads_sub_amount que
será usado.
Exemplo: para definir uma assinatura cujas 3 primeiras parcelas são de 25 BRL, e
o resto prestações de 30 BRL, os seguintes valores serão usados:
• vads_sub_currency = 986
• vads_sub_init_amount_number = 3
• vads_sub_init_amount = 2500
• vads_sub_amount = 3000
Formato
n..3
Code erreur
68
Categoria
vads_tax_amount
Descrição
Parâmetro que permite definir o valor das taxas para a totalidade do pedido.
O valor deve ser apresentado na menor unidade monetária da moeda .
Específico ao meio de pagamento PayPal.
Formato
n..12
Código de erro
108
Categoria
vads_theme_config
Descrição
Permite personalizar alguns elementos da página de pagamento: logomarcas,
faixas e algumas mensagens (Algumas funcionalidades são submetidas à opção
comercial).
Este parâmetro contém uma lista de palavras-chaves (códigos) associadas a
elementos das páginas de pagamento (denominações, imagens), com os quais um
valor é associado.
Exemplo
vads_theme_config=
SUCCESS_FOOTER_MSG_RETURN=Voltar
para
site;CANCEL_FOOTER_MSG_RETURN=Cancelar e voltar para o site
o
As funcionalidades de base são descritas no capítulo Personalizar a página de
pagamento do Guia de Implementação do formulário de pagamento.
As funcionalidades avançadas (submetidas à opção) são descritas no guia
Personalização avançada da página de pagamento.
Formato
Código1=Valor1;Código2=Valor2
Código de erro
32
Valores possíveis
Código
Descrição
SUCCESS_FOOTER_MSG_RETURN
Denominação que substitui "Voltar para a loja" quando
um pagamento é efetuado com sucesso.
CANCEL_FOOTER_MSG_RETURN
Denominação que substitui "Cancelar e voltar para a
loja" durante as etapas de seleção e de digitação de
cartão, em caso de falha do pagamento.
SECURE_ MESSAGE
Valor por padrão: O endereço deste site de pagamento
prefixado por https mostra que você esta em um site
seguro e que você pode fazer seu pagamento com toda
tranquilidade".
SECURE_MESSAGE_REGISTER
Valor por padrão: O endereço deste site de pagamento
prefixado por https mostra que você esta em um site
seguro e que você pode digitar seus dados bancários
com toda tranquilidade
SITE_ID_LABEL
Valor por padrão: Código de usuário do vendedor
CSS_FOR_PAYMENT
CSS_FOR_PAYMENT_MOBILE
HEADER_FOR_MAIL
FOOTER_FOR_MAIL
SHOP_LOGO
Ver guia Personalização avançada da página de
pagamento.
CTRL_RISK_CARD_NOT_ACCEPTED
Valor por padrão: O seu pedido de pagamento foi
recusado pelo seu banco.
Código
Categoria
Descrição
Esta mensagem é condicionada pelo retorno do serviço
de controle de risco.
O contrato tem de suportar todos os tipos de cartões
incluídos no contrato, e não o subconjunto que o
comerciante quer aceitar.
Permite sobrecarregar o denominação da recusa
quando um e-carte bleue é usado enquanto ele não é
aceito no controle do risco.
vads_threeds_cavv
Descrição
Designa a verificação da autentificação do portador pela ACS. É valorizado
pelo servidor de autentificação 3DS (ACS) quando o comprador se identificou
corretamente (vads_threeds_status vale « Y » ou « A »).
Formato
ans..28
Código de erro
52
Categoria
Autentificação 3DS.
vads_threeds_cavvAlgorithm
Descrição
Algoritmo usado pela ACS para gerar o valor do cavv.
É valorizado pelo servidor de autentificação 3DS (ACS) quando o comprador se
identificou corretamente (vads_threeds_status vale « Y » ou « A »).
Formato
n1
Código de erro
55
Valores possíveis
Categoria
Valor
Descrição
0
HMAC
1
CVV
2
CVV_ATN
3
MasterCard SPA
vads_threeds_eci
Descrição
Designa o Indicador de Comercio Eletrônico
É valorizado pelo servidor de autentificação 3DS (ACS) quando o comprador se
identificou corretamente (vads_threeds_status vale« Y » ou « A »).
status =Y
status = A
status = U
status =N
VISA
5
6
7
-
MasterCard
02
01
-
-
Formato
n..2
Código de erro
53
Categoria
vads_threeds_enrolled
Descrição
Designa o status de alistamento do portador. É valorizado pelos servidores VISA e
MASTERCARD (DS) durante o processo 3D Secure.
Formato
a1
Código de erro
51
Valores possíveis
Categoria
Valor
Descrição
Y
Portador alistado, autentificação 3D Secure possível.
N
Portador não alistado.
U
Não foi possível verificar o status de alistamento.
vads_threeds_exit_status
Descrição
Status final do processo 3D Secure.
Formato
Valores possíveis
n..2
Valor
Descrição
0
Status inicial
1
Status não aplicável (global, razão não detalhada)
2
Status não aplicável (integrator disabled)
3
Não é um pagamento e-commerce
4
Pagamento sem 3DS (pagamento por "token", PayPal, Cetelem, etc.)
5
Vendedor não alistado, sem 3DS*
6
Erro técnico durante o processo 3DS, sem 3DS
7
Portador não alistado, sem 3DS
8
Assinatura inválida
9
Problema proveniente do ACS
10
O processo 3DS foi concluído corretamente
11
O processo 3DS foi feito pelo integrador
12
Problema proveniente do DS
13
Timeout de conexão com o DS
15
O 3DS não esta disponível para este canal de pagamento (pagamentos por
arquivo)
16
Tipo de cartão e rede elegíveis para o 3DS, mas não "marca" associada ao
cartão (CB pura).
98
A inicialização do processo 3DS esta OK
99
Status desconhecido
* Estes status dizem respeito aos pagamentos para os quais o 3DS ocorreu mas sem
digitação de cartão (por código de usuário "token").
Categoria
vads_threeds_mpi
Descrição
Ativa / desativa o processo 3DS durante um pagamento e-commerce.
Formato
n1
Código de erro
50
Valores possíveis
Categoria
Valor
Descrição
ausente Autentificação 3DS gerada pela plataforma de pagamento (configuração do vendedor).
ou
vazio
0
1
Autentificação 3DS integralmente gerada pelo vendedor somente se vads_card_number
foi preenchido (digitação dos dados cartões no site do vendedor).
Os dados que resultam da autentificação 3D Secure efetuada pelo MPI do vendedor
devem agora ser enviados para os campos do formulário previstos para isso
(vads_threeds_enrolled, vads_threeds_cavv, vads_threeds_eci, vads_threeds_xid,
vads_threeds_ cavvAlgorithm, vads_threeds_status).
2
Autentificação 3DS desativada para a transação, seja qual for a configuração padrão do
vendedor.
vads_threeds_sign_valid
Descrição
Designa a validade da assinatura da mensagem PARes. É valorizado pela plataforma
de pagamento
Formato
Valores possíveis
Categoria
n1
Valor
Descrição
Vazio
Sem 3DS.
0
Assinatura incorreta.
1
Assinatura correta.
vads_threeds_status
Descrição
Designa o status de autentificação do portador. É valorizado pelo servidor de
autentificação 3DS durante o processo 3D Secure.
Formato
a1
Código de erro
56
Valores possíveis
Categoria
Valor
Descrição
Y
Autentificação sucedida.
N
Erro de autentificação.
U
Autentificação impossível.
A
Tentativa de autentificação.
vads_threeds_xid
Descrição
Designa a referência única da transação 3DS.
É valorizado pelo servidor de autentificação (ACS) durante o processo 3D Secure.
Formato
ans..28
Código de erro
54
Categoria
vads_trans_date
Descrição
Corresponde à marcação do tempo no formato AAAAMMJJHHMMSS.
A marcação do tempo deve necessariamente estar em adequação com a data e
a hora comum, no fuso horário GMT+0 (ou UTC) no formato horário 24h.
Observação: Se você usa os Webservices, a variável vads_trans_date corresponde
ao campo transmissãoData. Nós aconselhamos salvar este valor na base para
valorizar corretamente o campo transmissãoData durante as suas chamadas via os
Webservices.
Formato
n14
Código de erro
04
Erros frequentes:
• A data não é enviada no formato AAAAMMJJHHMMSS (ano, mês, dia, hora,
minuto, segundo).
• A data não esta conforme ao fuso horário UTC (tempo universal coordenado).
Não esqueçam de usar funções data na sua linguagem de programação gerando
uma hora UTC (gmdate em PHP por exemplo)
• O hora deve ser calculada na base de 24h e não de 12h.
• O comprador esperou tempo demais antes de clicar no botão Pagar.
• O comprador usou o histórico do navegador dele.
Categoria
vads_trans_id
Descrição
É constituído de 6 dígitos numéricos e deve ser único para cada transação para um
loja dada por dia.
Cabe ao site de e-commerce garantir o caráter único por dia. Deve variar entre
000000 e 899999.
A faixa 900000 e 999999 é reservada aos reembolsos e às operações realizadas no
Back Office.
Formato
n6
Código de erro
03
Erros frequentes:
O formulário é recusado:
• se o valor enviado é inferior a 6 dígitos.
• se o valor é nulo
• se o campo é ausente
• se um número de transação idêntico já foi enviado o mesmo dia.
Se o comprador cliqua no botão "Cancelar e voltar para a loja", o número de
transação deverá ser diferente na próxima tentativa porque considera que ele
já foi usado.
Caso contrário, a mensagem "A transação foi cancelada" será exibida.
Categoria
vads_trans_status
Descrição
Permite definir o status da transação.
Formato
Valores possíveis
string (enum)
Valor
Descrição
ABANDONED
O comprador desistiu do pagamento.
A transação não foi criada e portanto não esta exibida no
Back Office.
AUTHORISED
Captura em andamento
A transação foi aceita e será capturada automaticamente no
banco na data prevista.
Para ser aprovado
A transação, criada em validação manual, esta autorizada. O
vendedor deve validar manualmente a transação para lançar
a solicitação de autorização e a captura no banco.
A transação pode ser aprovada enquanto a data de
captura não foi vencida. Se esta data está vencida, então
o pagamento tem o status Expirado. O status Expirado é
definitivo.
CANCELED
Cancelada
A transação foi cancelada pelo vendedor.
CAPTURED
Vencida
A transação foi capturada no banco
EXPIRED
Expirada
A date de captura foi atingida e o vendedor não validou a
transação.
REFUSED
Recusada
Autorização em andamento
Prazo de captura maior que o tempo de validade da
autorização ..
Uma autorização de 1 BRL foi aceita.
A solicitação de autorização será automaticamente efetuada
a D-1 antes da data de captura no banco. O pagamento
poderá ser aceito ou recusado. Captura automática no
banco.
WAITING_AUTHORISATION_TO
_VALIDATE
Para ser aprovado e autorizado
Prazo de captura maior que o tempo de validade da
autorização. .
Uma autorização de 1 BRL a été acceptée.
O vendedor deve validar manualmente a transação para
lançar a solicitação de autorização e a captura no banco.
UNDER_VERIFICATION
Spécifique à PayPal
En attente de vérification par PayPal
PayPal retient la transaction pour suspicion de fraude . Le
paiement est alors dans l’onglet Paiement en cours.
NOT_CREATED
A transação não foi criada e portanto não esta exibida no
Back Office.
Tabela 46 : Valores associados a vads_trans_status
Categoria
vads_trans_uuid
Descrição
Referência única gerada pela plataforma de pagamento após a criação de uma
transação de pagamento.
Oferece uma garantia de unicidade para cada transação.
Formato
ans32
Categoria
vads_url_cancel
Descrição
URL para qual será redirecionado o comprador depois de clicar em Cancelar e
voltar para a loja antes de ter efetuado o pagamento.
Formato
ans..127
Código de erro
27
Categoria
vads_url_check
Descrição
URL da página a ser notificada no final do pagamento. Sobrecarrega o valor digitado
na configuração das regras de notificação.
Observação
Este campo deve ser utilizado excepcionalmente porque:
• Esta URL será utilizada somente na chamada da URL de notificação de
pagamento (IPN) imediato,
• o valor sobrecarregado não será utilizado se houver um relançamento
automático.
Esta funcionalidade não é compatível com a execução, pelo Back Office, da
solicitação enviada à url de notificação instantânea. A URL chamada será a
mesma que foi configurada na regra de notificação (ver capítulo Configurar as
notificações).
Formato
ans..127
Código de erro
33
Categoria
vads_url_check_src
Descrição
Este parâmetro define a procedência da chamada URL de notificação (também
chamada IPN).
Formato
string (enum)
Valores possíveis
Categoria
Valor
Descrição
PAY
Criação de um pagamento por formulário.
BO
Execução de URL de notificação pelo Back Office.
BATCH_AUTO
Chamada durante a solicitação de autorização de um pagamento que tinha o
status de autorização em andamento.
REC
Pagamentos criados a partir de uma recorrência.
MERCH_BO
Operação efetuada na transação pelo Back Office.
RETRY
Re-chamada automática a URL de notificação.
vads_url_error
Descrição
URL para qual será redirecionado o comprador em caso de erro de tratamento
interno.
Formato
ans..127
Código de erro
29
Categoria
vads_url_referral
Descrição
Campo desvalorizado. Use vads_url_refused.
URL para qual será redirecionado o comprador se a autorização foi recusada
(código 02 Entrar em contato com o emissor do cartão) depois de clicar em Voltar
para a loja.
Formato
ans..127
Código de erro
26
Categoria
vads_url_refused
Descrição
URL para qual será redirecionado o comprador, depois de clicar no botão voltar
para a loja.
Formato
ans..127
Código de erro
25
Categoria
vads_url_return
Descrição
URL para qual será redirecionado por padrão o comprador depois de clicar
no botão voltar para a loja, se as URL vads_url_error, vads_url_refused,
vads_url_success, vads_url_cancel não são informadas.
Se este campo não foi enviado, a configuração do Back Office será levada em conta.
É possível configurar URL de retorno, em modo TEST e em modo PRODUCTION.
Estes campos são chamados URL de retorno da loja e URL de retorno da loja em
modo teste, e são acessíveis no menu Configuração > Loja > aba Configurações.
Se nenhuma URL foi definida no Back Office ou no formulário, então o botão voltar
para a loja redirecionará o comprador para a URL do site de e-commerce (campo
URL na configuração da loja).
Formato
ans..127
Código de erro
28
Categoria
vads_url_success
Descrição
URL para qual será redirecionado o comprador se o pagamento for aceito, depois
de clicar no botão voltar para a loja.
Formato
ans..127
Código de erro
24
Categoria
vads_user_info
Descrição
Informação sobre o usuário na origem do pagamento.
No caso de um pagamento por formulário, este parâmetro será reenviado na
resposta com o valor enviado na solicitação.
No caso de um pagamento manual pelo Back Office, este campo será preenchido
com o nome de usuário (login) que efetuou o pagamento.
Observação:
Por razões de retro-compatibilidade, pode-se utilizar este campo para informar o
CPF/CNPJ (Identificação legal, em formato numérico, tendo entre 11 e 20 dígitos)
exigido pelo módulo de gerenciamento de fraude ClearSale. No entanto, o CPF/
CNPJ pode ser informado no campo vads_cust_national_id.
Formato
ans..255
Código de erro
61
Categoria
Descrição
Apresenta o modo de validação da transação.
Formato
string (enum)
Código de erro
05
Valores possíveis
Categoria
Valor
Descrição
Ausente ou
vazio
Configuração padrão da loja escolhida (pode ser configurado no Back Office).
0
Validação automática pela plataforma de pagamento
1
Validação manual pelo vendedor
vads_version
Descrição
Versão do protocolo de troca com a plataforma de pagamento.
Formato
string (enum)
Código de erro
01
Valor possível
V2
Categoria
vads_warranty_result
Descrição
Mostra a garantia do pagamento se o pagamento foi aceito.
Formato
Valores possíveis
Categoria
string (enum)
Valor
Descrição
YES
O pagamento é garantido.
NO
O pagamento não é garantido.
UNKNOW
Por causa de um erro técnico, o pagamento não pode ser garantido.
Não
valorizado.
Garantia de pagamento não aplicável

PDF

Transcrição

Documentos relacionados

Post To MySpace Documentation

PHP e Formulários HTML Enviando informações para um

Website: Centro Oftalmológico de Diagnose e Terapêutica

DeBakey LVAD

Guia de Integração

anexo xxxi - DFPC - Exército Brasileiro

formulário de solicitação de serviços eleitorais - Consulado

MANUAL PARA CONFIGURAR CLIENTE WinSCP 1 2 3

I authorize PASB to add to the next month`s tuition bill the amount

Máquina de diversão - comunicação de substituição do tema de jogo