Aprova Fácil
Integração via STAC
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
1
Prezado Cliente,
Apresentamos a seguir o Manual de integração do Aprova Fácil – Modo STAC.
O modo STAC é uma forma de integração simples, e que dispensa a instalação da solução Aprova Fácil no servidor do Lojista.
Ao optar pelo modo de integração STAC, a tela de digitação dos dados do cartão de crédito será hospedada no ambiente seguro da Cobre Bem Tecnologia.
Esperamos através desta documentação orientá­lo da melhor forma possível e aproveitamos a oportunidade para colocarmo­nos inteiramente à sua disposição para maiores esclarecimentos.
Para entrar em contato conosco utilize os canais de contato disponibilizados na URL abaixo:
http://www.cobrebem.com/contato.html
Nota: De acordo com as exigências do PCI­DSS a Cobre Bem Tecnologia não é autorizada a receber números de cartão de crédito. Caso necessite de suporte em relação a alguma transação efetuada, nos informe o número da transação.
Boas cobranças e Cobre Bem!
Equipe Cobre Bem
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
2
ÍNDICE
1. Introdução..........................................................................................................................................................................5
2. Integração...........................................................................................................................................................................6
2.1. Meios de Pagamento Suportados................................................................................................................................6
2.2. Tecnologias de Conectividade....................................................................................................................................7
2.3. Etapas da Automatização............................................................................................................................................7
2.4. Tempo de Captura de uma Transação Aprovada........................................................................................................7
2.5. Desfazimento de uma Transação Aprovada................................................................................................................9
3. Página de Digitação de Dados.........................................................................................................................................10
3.1. Imagens......................................................................................................................................................................10
4. Envio dos Dados do Pedido para o STAC.....................................................................................................................11
4.1. Método de Envio ......................................................................................................................................................11
4.2. TokenID.....................................................................................................................................................................12
5. Cartão de Crédito – Pedido de Aprovação – APC.......................................................................................................15
5.1. Descrição...................................................................................................................................................................15
5.2. Métodos de Envio......................................................................................................................................................15
5.3. URL Chamada...........................................................................................................................................................15
5.4. Parâmetros do Pedido................................................................................................................................................16
5.5. Agendamento ­ Descrição.........................................................................................................................................19
5.6. Consulta AVS (Adress Verification Service)...........................................................................................................20
5.7. Exemplo de Pedido....................................................................................................................................................21
5.8. Resultado do Processamento.....................................................................................................................................22
6. Cartão de Crédito – Pedido de Captura – CAP ..........................................................................................................24
6.1. Descrição...................................................................................................................................................................24
6.2. Métodos de Envio......................................................................................................................................................24
6.3. URL...........................................................................................................................................................................24
6.4. Parâmetros de Requisição.........................................................................................................................................25
6.5. Exemplos de Requisição GET..................................................................................................................................25
6.6. Resultado de Captura com Sucesso..........................................................................................................................25
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
3
6.7. Resultados de Erro Comuns......................................................................................................................................26
7. Cartão de Crédito – Cancelamento de Transações – CAN.........................................................................................27
7.1. Descrição...................................................................................................................................................................27
7.2. Métodos de Envio......................................................................................................................................................27
7.3. URL...........................................................................................................................................................................27
7.4. Parâmetros de Requisição.........................................................................................................................................28
7.5. Exemplos de Requisição...........................................................................................................................................28
7.6. Resultado de Cancelamento com Sucesso................................................................................................................28
8. Transferências Bancárias On Line – Pedido de Aprovação........................................................................................29
8.1. Descrição...................................................................................................................................................................29
8.2. Métodos de Envio......................................................................................................................................................29
8.3. URL...........................................................................................................................................................................29
8.4. Parâmetros de Requisição.........................................................................................................................................29
8.5. Exemplo de Requisição.............................................................................................................................................30
9. Transferências Bancárias On Line – Retorno de Confirmação de Pedido................................................................31
9.1. Descrição...................................................................................................................................................................31
9.2. Métodos de Envio......................................................................................................................................................31
9.3. URL...........................................................................................................................................................................31
9.4. Parâmetros de Envio..................................................................................................................................................31
9.5. Exemplo de Retorno..................................................................................................................................................31
9.6. Resultados de Erros Comuns....................................................................................................................................32
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
4
1. Introdução
O STAC é uma das formas disponíveis para efetuar a integração de sua loja virtual/aplicativo com a solução de automatização de vendas através de diversos meios de pagamento, o Aprova Fácil.
Este, tem como objetivo suprir a necessidade da instalação do CGIAprovaFacil ou CobreBemX.dll em seu servidor, bem como, prover um certificado SSL para os estabelecimentos (lojas virtuais) que não possuem e/ou não desejam adquiri­lo. Ressaltamos que o STAC é utilizado somente para a página onde serão digitados os dados sensíveis informados no momento da compra.
Nota: O certificado SSL (128 bits) é exigido pelas Administradoras de Cartões na tela/página onde serão digitados os dados do cartão de crédito.
Nesta forma de implementação, o consumidor após ter realizado o pedido na loja, será redirecionado para o ambiente seguro da Cobre Bem Tecnologia denominado STAC, onde informará os seus dados do cartão de crédito para finalizar o processo de compra.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
5
2. Integração
2.1. Meios de Pagamento Suportados
O Aprova Fácil realiza a automatização de diversos meios de pagamento simultaneamente com Bancos e Administradoras de Cartões de Crédito utilizando a internet como meio de captura.
Veja abaixo os meios de pagamento e a lista de instituições financeiras suportados no Aprova Fácil para esta forma de integração.
2.1.1. Cartão de Crédito
Veja na URL abaixo a lista de todas as Administradoras de Cartões e suas respectivas Bandeiras e Tecnologias de Conectividade suportadas pelo Aprova Fácil:
http://www.cobrebem.com/administradoras.html
Nota : Multibandeiras: consiste na aceitação de várias bandeiras de cartão por um mesmo adquirente. É pré­requisito estar habilitado junto aos adquirentes em todas as bandeiras que atenderem às suas necessidades comerciais. Sem isso não é possível beneficiar­se da funcionalidade multibandeira. Veja abaixo a relação das Administradoras de Cartões e suas respectivas bandeiras:
­ Cielo (Visa, Mastercard, Diners, Amex)
­ Redecard (Mastercard, Diners, Visa, Hipercard*)
­ Santander Adquirência (Visa, Mastercard)
­ Elavon Brasil (Visa, Mastercard, Diners)
2.1.2. Cartão de Débito O Aprova Fácil suporta o Visa Electron através da tecnologia de conectividade Buy Page Cielo. É importante ressaltar que em situações de venda à distância como Comércio Eletrônico as compras somente poderão ser realizadas por portadores de cartões emitidos pelos bancos: Banco do Brasil, Bradesco, HSBC e Santander.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
6
2.1.3. Transferência Eletrônica On Line (Débito On Line)
Consulte através da URL abaixo a lista de todos os bancos suportados pelo Aprova Fácil para esse meio de pagamento: http://www.cobrebem.com/bancostransferencia.html
2.2. Tecnologias de Conectividade
­ TEF Dedicado (Cielo, Redecard, Sorocred, JCB, Aura)
­ TEF GetNet (Santander Adquirência)
­ TEF Elavon do Brasil (Elavon Brasil)
­ Buy Page Cielo, Buy Page Loja (Cielo)
­ Komerci, Komerci Web Service (Redecard)
2.3. Etapas da Automatização
2.3.1. Cartão de Crédito
a) Envio dos dados do pedido para o STAC;
b) Requisição de aprovação;
c) Requisição de captura;
d) Requisição de cancelamento.
2.3.2. Transferência Eletrônica On line (Débito On Line)
a) Requisição de aprovação;
b) Retorno de confirmação de pagamento.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
7
2.4. Tempo de Captura de uma Transação Aprovada
Nas vendas realizadas através do meio de pagamento Cartão de Crédito é possível realizar confirmação (captura) da transação de 02 (duas) formas:
–
Manual;
–
Automática.
A confirmação/captura de uma transação se refere ao processo entre a aprovação da transação e o débito efetivo no cartão do cliente. A confirmação/captura pode ser realizada de forma manual ou automática, dependendo da implementação realizada pelo desenvolvedor. O lojista determina o modo da confirmação/captura de acordo com o tipo de venda/negócio adotado. Geralmente, o lojista adota o modo de confirmação com captura manual, quando deseja realizar uma verificação do pedido antes de confirmar/capturar a transação junto às Administradora de Cartões de Crédito. Abaixo segue um quadro ilustrativo, contendo os prazos de confirmação (captura) da transação de acordo com a tecnologia de conectividade e Adquirente para sua análise.
Adquirente
Tecnologia de Conectividade
TEF Dedicado Cielo
Buy Page Cielo
Buy Page Loja
Prazo de Confirmação
47 horas
até 5 dias
TEF Dedicado
47 horas
Komerci
2 minutos
Komerci WebService
5 minutos
Redecard
Somente é possível captura Manual com Pré­Autorização, neste caso são 5 dias. (*) veja Nota 1
Hipercard
Cetelem
Elavon Brasil
Santander Adquirencia
TEF Dedicado
47 horas
TEF Elavon do Brasil 47 horas
TEF GetNet
47 horas
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
8
As tecnologias de conectividade Komerci e Komerci WebService da Redecard não permitem a confirmação (captura) do tipo manual, somente automática com prazo de confirmação (captura) máximo de 2 e 5 minutos, respectivamente.
Nota 1: Caso o estabelecimento esteja habilitado na tecnologia de conectividade Komerci WebService com “Pré­Autorização”, junto à Administradora Redecard, a captura poderá ser realizada de forma manual. Neste caso, o prazo para realizar a confirmação (captura) é de 5 dias corridos a partir da data do processamento realizado pela Administradora Redecard.
2.5. Desfazimento de uma Transação Aprovada
Caso o lojista não realize a captura da transação no prazo estipulado pelas Administradoras de Cartões , de acordo com a tecnologia de conectividade, a mesma será desfeita automaticamente. Neste caso, o débito não é realizado no cartão de crédito do cliente.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
9
3. Página de Digitação de Dados
Todo cliente que utiliza a forma de integração via STAC já possui uma página de digitação de dados padrão, que deve ser personalizada. Ela pode ser acessada através da url abaixo.
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Para personalizar sua página de digitação de dados, utilize como base a página exemplo que pode ser baixada através da url abaixo e envie­a para a nossa equipe através de um dos nossos e­mails de contato. Ao realizar a personalização, deve­se requisitar as informações de acordo com o que exigido pelas administradoras de cartão de crédito conforme tecnologia de conectividade utilizada.
http://www.cobrebem.com/downloads/apf/PaginaSTAC.zip
Importante: Para que a página STAC enviada para nós seja cadastrada para o seu estabelecimento, a mesma deve ter o tamanho máximo de 50KB, estar compactada em formato .zip ou .rar. e o e­mail do remetente necessita estar cadastrado em nosso sistema como responsável pelo estabelecimento ou desenvolvedor.
3.1. Imagens
É possível colocar imagens na página de digitação de dados, como por exemplo, o logo da sua empresa. Para fazer isso envie­nos as imagens e, no código da página, a referência a cada imagem deve ser feita conforme segue abaixo. Se a extensão do arquivo for omitida será assumido o tipo JPEG.
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
10
4. Envio dos Dados do Pedido para o STAC
O envio dos dados do pedido ocorre após o cliente selecionar o meio de pagamento na loja virtual.
Esta passagem de parâmetros pode ocorrer de duas formas, através de GET/POST ou através do TokenID.
4.1. Método de Envio Nesta forma, os parâmetros serão passados da loja para o STAC diretamente através de GET ou POST.
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Importante: O código de usuário STAC identifica a loja perante o sistema Aprova Fácil e sempre deverá ser escrito com letras minúsculas.
4.1.1. Parâmetros
Todos os parâmetros de requisição enviados para a página STAC e que serão utilizados no processamento devem ser resgatados através da sintaxe <#NomeParametro>, onde NomeParametro será substituído pelo nome do parâmetro proveniente da loja virtual.
Supondo que a sua loja virtual envie um parâmetro de requisição denominado UsuarioID, o qual será exibido na página do STAC, será necessário acrescentar no local desejado do código HTML desta página a tag <#UsuarioID>.
Uma outra maneira de resgatar todos os parâmetros de requisição da loja é utilizar uma única tag denominada <#ParametrosCliente>, neste caso, todos os parâmetros de requisição serão automaticamente resgatados e inclusos como input do form, exceto os parâmetros que são utilizados internamente pelo STAC que estão listados abaixo:
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
11
<#ValorDocumento >
<#ValorDocumentoExibicao >
<#QuantidadeParcelas >
<#NumeroDocumento >
<#NumeroCartao> <#MesValidade >
<#AnoValidade >
<#CodigoSeguranca >
<#ParcelamentoAdministradora>
<#Moeda >
<#TransacaoAnterior >
<#Bandeira >
<#AVS >
<#NomePortadorCartao >
<#CPFPortadorCartao> <#EnderecoPortadorCartao >
<#CEPPortadorCartao >
<#URLImagemSuperior> <#FrameRetorno> <#Idioma >
<#VisaElectron >
<#BancoEmissor> <#PreAutorizacao >
<#ValorEntrada >
<#ParametrosCliente> <#URLAprovacao >
<#AnosValidos>
4.2. TokenID
Nesta forma de envio de dados para o STAC os parâmetros serão substituídos por um identificador denominado TokenID.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
12
Diferente do formato GET/POST nesta forma há duas chamadas ao STAC, a primeira passando os parâmetros, para que o TokenID seja gerado (invisível ao cliente da loja virtual) e uma segunda chamada passando o TokenID para o STAC (visível ao cliente da loja virtual).
4.2.1. Gerando o TokenID
O TokenID é gerado quando há uma chamada ao STAC com o parâmetro /TOKEN.
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Importante: O código de usuário STAC identifica a loja perante o sistema Aprova Fácil e sempre deverá ser escrito com letras minúsculas.
A resposta dessa chamada será uma string (TokenID) contendo números e letras.
Exemplo: O6S1SPVwcADHd7Id43u3pI7E0Ws1wl83idU7JXmiA8iZz1Gtwx
4.2.2. Enviando o TokenID para o STAC
Neste passo o TokenID gerado deverá ser passado ao STAC como único parâmetro já que este é o identificador de todos os parâmetros passados anteriormente.
O único parâmetro então denominado TokenID deverá ser resgatado pela página do STAC através da sintaxe <#TokenID>. Exemplo:
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
13
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
14
5. Cartão de Crédito – Pedido de Aprovação – APC
5.1. Descrição
A diretiva de execução, o APC, deverá ser utilizado toda vez que o estabelecimento necessitar solicitar a aprovação financeira para uma venda realizada através de cartão de crédito.
O pedido de aprovação ocorre após a digitação dos dados do cartão de crédito na página do STAC, nessa solicitação serão utilizados também os dados provenientes da loja, tais como, valor e quantidade de parcelas.
5.2. Métodos de Envio
Como os dados passados no envio do pedido são sigilosos, então o método de envio a ser adotado é o POST, através de HTTPS.
5.3. URL Chamada
5.3.1. Servidor principal:
5.3.2. Servidor de teste:
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
15
5.4. Parâmetros do Pedido
Os parâmetros de requisição a serem utilizados na página do STAC dependem da tecnologia de conectividade habilitada para seu estabelecimento em cada Administradora. Sendo assim, seguem abaixo 03 tabelas que ilustram os parâmetros a serem adotados em cada tecnologia de conectividade:
Tecnologias: TEF Dedicado / Buy Page Loja / WebPos / Komerci WebService / TEF Elavon do Brasil / TEF GetNet
Nome
NumeroDocumento
Descrição
Formatação
Identificação da venda pela loja.
Até 50 caracteres alfanuméricos.
Numérico, sendo as casas Exemplo
Obrigatório
123ABC
Não
123.56
Sim
Sim
ValorDocumento*
Valor da transação
QuantidadeParcelas
Quantidade de parcelas
02 dígitos numéricos
01
NumeroCartao
Número do cartão de crédito
Até 19 dígitos numéricos
4551870000000183 Sim
MesValidade
Mês em que o cartão expira
02 dígitos numéricos
11
Sim
AnoValidade
Ano em que o cartão expira
02 dígitos numéricos
08
Sim
CodigoSeguranca**
CVC2/CVV2 do cartão
Até 04 dígitos numéricos
123
Sim, se decimais separadas por ponto (.)
tecnologia diferente de Komerci Web Service
Bandeira
Bandeira do Cartão de VISA
Crédito
MASTERCARD
VISA
Sim
S
Não
DINERS
AMEX
HIPERCARD
JCB
SOROCRED
AURA
ParcelamentoAdmini Utilizado para acionar o stradora
Apenas um caracter: S
parcelamento administradora
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
16
Nome
Descrição
CPFPortadorCartao
Formatação
Exemplo
CPF do portador do cartão de 14 dígitos numéricos
12345678123412
crédito
12345678912
11 dígitos numéricos
NomePortadorCartao Nome que está gravado no Até 50 caracteres alfanuméricos
Obrigatório
Não
José da Silva
Não
AAAAMMDD
20071027
Não
Valores válidos: BRL, MXN, BRL
Não
cartão
DataNascimentoPort Data de nascimento do adorCartao
portador do cartão
Moeda
Moeda utilizada na venda (caso não seja informado, será CLP (Demais valores ISO para assumido o valor BRL)
definições de moeda ­ ISO 4217) * O Aprova Fácil não efetua nenhum tipo de conversão de moedas. Sendo assim, o valor da transação informado ao Aprova Fácil deverá sempre ser em Real.
** É possível controlar o resultado no ambiente de testes do Aprova Fácil. Para isto, utilize o parâmetro “CodigoSeguranca”. Veja abaixo o resultado esperado. Essa modalidade não está disponível para Aura e Sorocred.
CodigoSeguranca Informado
Retorno
555 ou 123
Autorizado
501
05 ­ 05NAO AUTORIZADA 502
78 ­ 78CAR BLOQ1.USO 503
41 ­ 41 RETER CARTAO 504
14 ­ 14CARTAOINVALIDO 506
60 ­ Valor Inválido. Por favor, ent 507
68 ­ T68TRANSACAO JA EFETUADA 508
54 ­ 54CARTAO VENCIDO 509
56 ­ Dado Inválido. Por favor, entr 444
N7 ­ N7COD.SEG.INVAL 333
84 ­ T84REFACA TRANS
Nota: Por determinação da Redecard o CVV2 não deve ser solicitado do comprador quando a tecnologia utilizada for Komerci Web Service.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
17
Tecnologia: Buy Page Cielo
Nome
Descrição
Formatação
NumeroDocumento
Identificação da venda pela loja. Até 50 caracteres alfanuméricos.
ValorDocumento*
Valor da transação
QuantidadeParcelas
Quantidade de parcelas
NumeroCartao
Idioma
VisaElectron
Exemplo
Obrigatório
123ABC
Não
123.56
Sim
2 dígitos numéricos
01
Sim
Bin do cartão de crédito
6 dígitos numéricos
455187
Sim
Define o idioma da janela da PTB=Português ENG=Inglês ESP
Não
Cielo
ESP=Espanhol
Informa se o cartão a ser S ou N N
Não
VISA
VISA
Não
Numérico, sendo as casas decimais separadas por ponto (.)
debitado é Visa Electron
Bandeira
Bandeira do Cartão de Crédito
* O Aprova Fácil não efetua nenhum tipo de conversão de moedas. Sendo assim, o valor da transação informado ao Aprova Fácil deverá sempre ser em Real.
Tecnologia: Komerci
Nome
NumeroDocumento
Descrição
Formatação
Identificação da venda pela loja.
Até 50 caracteres alfanuméricos.
Numérico, sendo as casas Exemplo
Obrigatório
123ABC
Não
123.56
Sim
ValorDocumento*
Valor da transação
QuantidadeParcelas
Quantidade de parcelas
2 dígitos numéricos
01
Sim
Bandeira
Bandeira do cartão de crédito
Caracteres em maiúsculo
MASTERCARD Sim
ESP
Não
N
Não
decimais separadas por ponto (.)
Preechimento: DINERS ou MASTERCARD
Idioma
AVS
Define o idioma da janela da PTB=Português ENG=Inglês Redecard
ESP=Espanhol
Valores: N – Não realizar
1 caracter
S – Para realizar consulta
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
18
Nome
Descrição
UrlImagemSuperior
Formatação
Exemplo
Obrigatório
Define a imagem a ser exibida URL
http://www.seusite Não
na Redecard. .com.br/imagem.j
pg
PreAutorizacao
Char. S=Sim e N= Não **Veja descrição abaixo
S
Não
* O Aprova Fácil não efetua nenhum tipo de conversão de moedas. Sendo assim, o valor da transação informado ao Aprova Fácil deverá sempre ser em Real.
** A Pré­autorização é o bloqueio temporário de uma quantia no cartão de crédito com objetivo de garantir a sua reserva sendo um recurso utilizado na tecnologia de conectividade Komerci WebService (Redecard). Note que este tipo de venda que contém o recurso de Pré­Autorização somente é utilizada em projetos especiais que tenham esta necessidade.
5.5. Agendamento ­ Descrição
O agendamento de transações é utilizado, quando há a necessidade de efetuar mensalmente o débito no cartão de crédito do cliente mantendo sempre as mesmas condições: –
Mesmo valor;
–
Débito mensal realizado sempre no mesmo dia.
O agendamento é realizado de forma automática pelo Aprova Fácil, obedecendo as regras de débito informadas através dos parâmetros de agendamentos descritos no item 5.5.2 deste manual.
Importante: Para que o agendamento seja aceito é necessário que a primeira transação tenha sido aprovada pela Administradora de Cartões de Crédito e confirmada pelo Lojista. Caso contrário, não será realizado o agendamento.
5.5.1. Agendamento – Tecnologia de Conectividade O agendamento é suportado nas tecnologias de conectividade TEF Dedicado, TEF GetNet,
TEF Elavon do Brasil, Buy Page Loja (Cielo), Komerci WebService (Redecard) e WebPos (Amex).
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
19
5.5.2. Agendamento ­ Parâmetros Utilizados para Agendar uma Transação
Os parâmetros de requisição exibidos na tabela abaixo, devem ser enviados na primeira solicitação de débito do cartão de crédito juntamente com os demais dados do pedido. Neste caso o parâmetro NumeroDocumento passa a ser obrigatório, não poderá ser nulo e deverá ser único.
Nome
Agendamento
DiaParaAgendar
Descrição
Formatação
Exemplo
Utilizado para incluir, Apenas um caracter: I I
excluir ou alterar um (Incluir), E (Excluir) agendamento ou A (Atualizar)
Dia de cada mês em que dd
09
será feito o débito
QuantidadeMesesParaAgendar
Quantidade de meses para 2 dígitos numéricos
08
Se Agendamento ≠ Se Agendamento ≠ E
Número de tentativas para 2 dígitos numéricos
04
a transação ser aprovada
QuantidadeDiasEntreTentativas
Sim
E
agendar
NumeroTentativasNaoAprovado
Obrigatório
Quantidade de dias entre Se Agendamento ≠ E
2 dígitos numéricos
03
cada tentativa
Se Agendamento ≠ E
5.6. Consulta AVS (Adress Verification Service)
O AVS é um serviço oferecido pelas Administradoras de Cartão de Crédito para que o lojista possa realizar uma consulta para confirmação dos dados de CPF (Cadastro Pessoa Física) e do endereço de entrega da fatura do titular do cartão no ato da compra .
Para disponibilizar essa consulta, o estabelecimento deverá habilitar esse serviço junto às Administradoras de Cartão de Crédito e, após, informar à Cobre Bem Tecnologia que a mesma será utilizada.
A consulta AVS é suportada para as bandeiras Amex e Mastercard, nas tecnologias de conectividade WebPos, Komerci e Komerci WebService, respectivamente.
Se o estabelecimento do lojista possuir habilitação para realizar vendas com AVS, no momento da solicitação dos dados, deverão ser informados também os parâmetros de requisição a seguir:
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
20
Tecnologia: Komerci
Nome
Descrição
Valores: N – Não realizar
AVS
S – Para realizar consulta
Formatação
1 caracter
Exemplo
S
Obrigatório
Sim, caso deseja que a transação complete consulta AVS
Tecnologia: Komerci Web Service
Nome
Descrição
Formatação
Valores: N – Não realizar
AVS
1 caracter
S
CPF do Portador do cartão 14 dígitos numéricos
12345678123412
de crédito
11 dígitos numéricos
12345678912
Endereço do portador do Até 50 caracteres
cartão de crédito
Endereço + número
S – Para realizar consulta
CPFPortadorCartao
EnderecoPortadorCartao
CEPPortadorCartao
Exemplo
CEP do Portador do cartão de crédito
08 dígitos numéricos
Obrigatório
Sim
Se AVS = S
Av. das flores 123
Se AVS = S
20555000
Se AVS = S
5.7. Exemplo de Pedido
Segue abaixo um trecho de código de exemplo do envio dos dados, para solicitar a aprovação de uma transação:
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
21
5.8. Resultado do Processamento
5.8.1. Parâmetros de Retorno via POST / GET
A resposta do processamento de uma transação também pode ocorrer através de parâmetros através dos métodos GET e POST.
Nome
TransacaoAprovada
Descrição
Resultado do pedido de aprovação
Formatação
True = Aprovado
Exemplo
Obrigatório
True
Sim
veja tabela Sim
False = Negado
ResultadoSolicitacaoAprovacao Descrição da aprovação do resultado CodigoAutorizacao
Texto varchar
do pedido
abaixo
Código de autorização retornado pela Texto de 6 dígitos
N12345
administradora do cartão de crédito
Transacao
CartaoMascarado
NumeroDocumento
Sim se aprovado
Número da transação no Aprova Fácil 14 dígitos 73263868827
numéricos
369
Número mascarado do cartão de Até 19 dígitos 444433*****
crédito
numéricos
*1111
Identificação da venda pela loja
Até 50 caracteres 123ABC
Sim
Sim
Sim
alfanuméricos
NumeroSequencialUnico
Número de aprovação da 6 dígitos numéricos 123456
não
Administradora
ComprovanteAdministradora
Texto comprovante da administradora
Texto varchar
N/A
Não
NacionalidadeEmissor
País emissor
Texto nulo
N/A
Não
ResultadoAVS
Resultado da verificação de endereço Texto nulo
N/A
Não
N/A
Não
(Veja a tabela do item 4.8.3)
EnderecoAVS
Tag de grupo para endereço verificado N/A
Endereco
Endereço de rua verificado
Texto nulo
Numero
Número de endereço verificado
Texto nulo
N/A
Não
Complemento
Complemento do endereço verificado
Texto nulo
N/A
Não
Cep
CEP do endereço verificado
Texto nulo
N/A
Não
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
Não
22
5.8.2. Tabela de Valores retornados para o parâmetro ResultadoAVS
Amex
Código
Descrição
X
Endereço e CEP 9 ­ dígitos coincidem.
Y
Endereço e CEP 5 ­ dígitos coincidem.
W
Somente o CEP 9 ­ Dígitos coincide.
S
Serviço não suportado.
G
Emissor não participa do AVS.
A
Endereço coincide. Cep não coincide ou não verificado.
Z
Cep 5 ­ dígitos coincide. Endereço não coincide.
R
Emissor não disponível.
U
Endereço indisponível.
N
Nada coincide.
E
Endereço e Cep não informado.
Redecard
Código
Descrição
W
Sim, todos os dígitos coincidem.
X
O CEP e CPF coincidem, endereço não coincide.
Z
Endereço e CPF coincidem, CEP não coincide.
Y
O CEP coincide, CPF e endereço não coincidem.
A
CPF coincide, CEP e endereço não coincidem.
U
O CEP e CPF não coincidem, endereço coincide.
S
O CEP e endereço coincidem, CPF não coincide. N
Nada coincide.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
23
6. Cartão de Crédito – Pedido de Captura – CAP 6.1. Descrição
A diretiva de execução CAP efetua a captura de uma transação. Entende­se por captura o processo de confirmação de uma transação, o que caracteriza a venda efetivada, sendo realizada assim, o débito no cartão de crédito do cliente.
De acordo com os padrões ISO 8583 todas as transações aprovadas pelas Administradoras de Cartões de Crédito devem ser capturadas (confirmadas) pela aplicação do lojista.
Caso a transação não seja capturada (confirmada) pela aplicação do lojista, no prazo estipulado elas Administradoras de Cartões de Crédito, a mesma será automaticamente desfeita, não havendo assim o débito efetivo no cartão de crédito do cliente.
6.2. Métodos de Envio
Os métodos de envio dos parâmetros podem ser o POST ou GET utilizando conexões HTTP ou HTTPS, já que não são trafegados dados sigilosos.
6.3. URL
6.3.1. Servidor principal:
6.3.2. Servidor de teste: Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
24
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
6.4. Parâmetros de Requisição
Nome
Descrição
NumeroDocumento
Transação
Formatação
Identificação da venda Até 50 caracteres pela loja.
alfanuméricos
Número da transação no 14 dígitos Aprova Fácil
numéricos
Exemplo
123ABC
73263500055432
Obrigatório
Não
Se NumeroDocumento for nulo
6.5. Exemplos de Requisição GET
6.5.1. Captura utilizando o número documento gerado pelo estabelecimento
6.5.2. Captura Utilizando o número da transação gerado pelo Aprova Fácil
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
6.6. Resultado de Captura com Sucesso
O resultado de uma transação de captura bem sucedida começará com a palavra “Confirmado”, seguida de um carácter de espaço, e do número de transação Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
25
6.7. Resultados de Erro Comuns
Texto do Resultado
Descrição
Erro ­ Transação Inválida
Transação Inválida
Erro ­ Transação a confirmar não encontrada ou já confirmada
Transação a confirmar não encontrada ou já confirmada
Erro ­ IP não permitido
IP não permitido
Erro ­ Estabelecimento não cadastrado para a Bandeira XXX Estabelecimento não cadastrado para a Bandeira XXX Adquirinte YYY
Adquirinte YYY
Erro ­ Estabelecimento não habilitado para a Bandeira XXX XXX não habilitada para o estabelecimento
Adquirinte YYY
Erro ­ Captura Já Efetuada
Captura já efetuada
Erro ­ Parâmetros Incorretos
Parâmetros incorretos
Erro ­ Código Cliente Inválido
Código cliente inválido
Erro ­ Código de Cliente Forjado
Código de cliente forjado
Erro ­ Modo de Operação Inválido
Modo de operação inválido
Erro ­ Conexão para confirmação não Estabelecida
Conexão para confirmação não estabelecida
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
26
7. Cartão de Crédito – Cancelamento de Transações – CAN
7.1. Descrição
A diretiva de execução CAN é utilizada no processo de cancelamento da transação.
O cancelamento de uma transação somente poderá ser realizado quando a mesma for aprovada pela administradora e confirmada pelo lojista. Por isso para que o Aprova Fácil possa realizar o cancelamento, este deve ser solicitado no mesmo dia em que a transação foi processada, ou seja, foi aprovada pela administradora.
7.2. Métodos de Envio
O método de envio utilizado pode ser o POST ou GET e as informações podem ser enviadas através de HTTP ou HTTPS, já que não são trafegados dados sigilosos.
7.3. URL
7.3.1. Servidor principal:
7.3.2. Servidor de teste:
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
27
7.4. Parâmetros de Requisição
Nome
Descrição
NumeroDocumento
Formatação
Identificação da venda Até 50 caracteres pela loja.
alfanuméricos.
Número da transação no 14 dígitos numéricos
Transacao
Aprova Fácil
Exemplo
123ABC
73263500055432
Obrigatório
Não
Se NumeroDocumento for nulo
7.5. Exemplos de Requisição
7.5.1. Cancelamento utilizando o número do documento gerado pelo estabelecimento
7.5.2. Cancelamento utilizando o número da Transação gerado pelo Aprova Fácil
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
7.6. Resultado de Cancelamento com Sucesso
No ambiente de Testes do Aprova Fácil, o resultado de uma requisição de cancelamento bem sucedida será “Cancelado XXXXXXXXXXXXXX”, onde XXXXXXXXXXXXXX será o valor informado ao parâmetro Transação quando do envio da requisição.
No ambiente de Produção do Aprova Fácil, o resultado de uma requisição de cancelamento bem sucedida será a mensagem "Cancelamento OK". Nota: Uma requisição é considerada de cancelamento quando feita até às 23:59:59 do dia da aprovação da transação.
Obs: Uma requisição é considerada de cancelamento quando feita até às 23:59:59 do dia da aprovação da transação. Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
28
Obs: Uma requisição de cancelamento feita no dia subsequente à aprovação ou após, será considerada reembolso. O resultado de um reembolso bem sucedido será "Cancelamento marcado para envio XXXXXXXXXXXXXX", onde XXXXXXXXXXXXXX será o número da transação a ser reembolsada. Para mais informações sobre esta funcionalidade, entre em contato com nosso suporte técnico.
Obs: No ambiente de Testes do Aprova Fácil não é possível testar a funcionalidade reembolso.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
29
8. Transferências Bancárias On Line – Pedido de Aprovação
8.1. Descrição
O pedido de aprovação será realizado toda vez que a aplicação do lojista necessitar obter aprovação financeira de uma venda por meio de transferência eletrônica on line. O pedido de transferência eletrônica on line retornará um código HTML que redirecionará o navegador do cliente para o site do banco selecionado.
8.2. Métodos de Envio
O método a ser utilizado deverá ser o POST e as informações devem ser enviadas através de HTTPS, já que serão trafegados dados sigilosos.
8.3. URL
Segue um exemplo:
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
8.4. Parâmetros de Requisição
Nome
NumeroDocumento
Descrição
Formatação
Identificação da venda pela Até 50 caracteres loja.
alfanuméricos.
Exemplo
123ABC
Obrigatório
Não
Numérico, sendo as casas ValorDocumento*
Valor da transação
decimais separadas por ponto 123.56
Sim
(.)
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
30
Nome
Descrição
Formatação
Exemplo
Obrigatório
Valores válidos são:
Bandeira
BBRASIL
Nome do banco
BANRISUL/ BRADESCO
BRADESCO
Sim
Sim
HSBC / ITAU
QuantidadeParcelas
CNPJCPFSacado
Quantidade de parcelas
02 dígitos numéricos
01
CNPJ ou CPF do sacado
14 dígitos numéricos
12345678123412
11 dígitos numéricos
12345678912
Não
* O Aprova Fácil não efetua nenhum tipo de conversão de moedas. Sendo assim, o valor da transação informado ao Aprova Fácil deverá sempre ser em Real.
8.5. Exemplo de Requisição
Nota: <usuariostac> deverá ser substituído pelo seu usuário de acesso ao extrato do Aprova Fácil.
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
31
9. Transferências Bancárias On Line – Retorno de Confirmação de Pedido
9.1. Descrição
O retorno de uma transferência será feita do Aprova Fácil para o site do lojista. O desenvolvedor deverá fornecer uma URL para receber o POST ou GET dos servidores do Aprova Fácil, esta conterá a informação de confirmação de pagamento do pedido de transferência bancária on line.
9.2. Métodos de Envio
O método pode ser o POST ou GET e as informações podem ser enviadas através de HTTP ou HTTPS.
9.3. URL
Segue um exemplo: https://pagamento.lojacliente.com/RetornoTransacao.php
9.4. Parâmetros de Envio
Nome
NumeroDocumento
Descrição
Formatação
Identificação da venda pelo loja Até 50 caracteres Exemplo
Obrigatório
123ABC
Não
True
Sim
alfanuméricos
TransacaoAprovada
CodigoAutorizacao
Resultado do pedido de True = Aprovado
aprovação
False = Negado
Código de autorização retornado pelo banco
Transacao
Texto de 6 dígitos
Número da transação no Aprova 14 dígitos numéricos
Sempre retornará vazio.
Sim
73263868827369
Sim
Número mascarado do cartão de Até 19 dígitos Será sempre Sim
crédito
preenchido com Fácil
CartaoMascarado
numéricos “Cartao%20Nao
%20Informado”
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
32
Nome
ValorDocumento
Descrição
Formatação
Valor da transação Exemplo
Numérico, sendo as Será sempre casas decimais preenchido de Obrigatório
Sim
separadas por ponto (.) acordo com o valor da transação em questão
QuantidadeParcelas
Quantidade de parcelas ResultadoSolicitacaoA Descrição da aprovação do provacao
2 dígitos numéricos 01
Sim
Texto varchar Será preenchido Sim
resultado do pedido
com o status retornado pelo banco
Bandeira
Nome do banco Valores válidos são: Será sempre BBRASIL
preenchido de BANRISUL/ acordo com a BRADESCO
bandeira da HSBC / ITAU
transação em Sim
questão
MesValidade
Mês em que o cartão expira 02 dígitos numéricos Será sempre Sim
preenchido com “00”
AnoValidade
Ano em que o cartão expira 02 dígitos numéricos
Será sempre Sim
preenchido com “00”
NumeroSequencialUni Número de aprovação da 6 dígitos numéricos Sempre retornará co
Administradora 123456 vazio.
ResultadoAVS
Resultado da verificação de Texto nulo Sempre retornará endereço Sim
Sim
vazio.
Nota: O parâmetro de retorno <NUMPEDIDO> sempre será preenchido com o número da transação
em questão.
9.5. Exemplo de Retorno
https://pagamento.lojacliente.com/RetornoTransacao.php?
NumeroDocumento=123ABC&TransacaoAprovada=True&CodigoAutorizacao=123456&Transacao=73561234567898
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
33
9.6. Resultados de Erros Comuns
Texto Resultante
Descrição
Erro ­ Transação Inválida
Transação inválida
Erro ­ Transação a cancelar não encontrada ou já cancelada
Transação a cancelar não encontrada ou já cancelada
Erro ­ Cancelamento Já Efetuado
Cancelamento já efetuado
Erro ­ Conexão para cancelamento não Estabelecida
Conexão para cancelamento não estabelecida
Aprova Fácil – Integração Via STAC ­ Versão 1.2.6.9.13
http://www.cobrebem.com/
34