Manual Técnico. Gateway de Pagamentos HSBC Débito Online PUBLIC. Versão 2.3 Maio/2013

Transcrição

1 Manual Técnico Gateway de Pagamentos HSBC Débito Online Versão 2.3 Maio/2013 PUBLIC

2 Sumário INTRODUÇÃO INICIANDO A INTEGRAÇÃO PROCESSO OPERACIONAL Pré Requisitos Glossário PROCESSOS E CONFIGURAÇÕES Cliente comprador (Sacado (Pagador)) Site da Loja/Empresa (Cedente (Beneficiário)) Cliente comprador (Sacado (Pagador)) Ambiente HSBC CRIAÇÃO DO PEDIDO O Post realizado ENTRADA NO GATEWAY O POST dispara o Aplicativo Servidor do HSBC A página de entrada do Gateway de Pagamentos Cliente se autentica no seu canal HSBC Aplicativo Servidor do HSBC A URL dispara o Aplicativo Servidor da Loja CONFIGURAÇÕES NO SITE DO CLIENTE Na página que lista as opções de Pagamento Definir como ação/link da referida opção Desenvolver no Aplicativo Servidor da Loja Desenvolver no Aplicativo Servidor CONSULTA STATUS DO PEDIDO O Post realizado dispara o Aplicativo Servidor do HSBC PUBLIC - 2

3 5. ARQUIVO DE RETORNO LEIAUTE DO ARQUIVO DE RETORNO LOGOTIPO HSBC TESTES FINAIS ANEXO I EXEMPLO DE DESENVOLVIMENTO EM PHP PUBLIC - 3

4 Prezado Cliente, O banco HSBC Bank Brasil S.A. Banco Múltiplo desenvolveu o Manual Técnico de Integração com o Gateway de Pagamentos HSBC. Este manual tem o objetivo de detalhar a modalidade de recebimento por Débito Online que funciona como uma transferência entre contas HSBC. Aqui você encontrará informações e passos a serem seguidos para tornar disponível no seu WebSite à opção de meio de pagamentos HSBC através do Gateway de Pagamentos na modalidade Débito Online. Por favor, leia atentamente todos os passos e recomendações antes de iniciar qualquer desenvolvimento ou customização em seu WebSite. INTRODUÇÃO O Gateway de Pagamentos HSBC é um canal voltado a empresas que possuem loja virtual ecommerce e desejam disponibilizar aos seus clientes métodos ágeis de pagamentos para suas compras online. A modalidade de recebimento por transferência entre contas HSBC, consiste em uma transferência online. Através dela os compradores do seu WebSite, clientes correntistas do HSBC poderão efetuar o pagamento de suas compras de forma online, diretamente no site do HSBC, utilizando os canais Connect Bank ou Meu HSBC Internet com toda a segurança e comodidade. PUBLIC - 4

5 1. INICIANDO A INTEGRAÇÃO Após a confirmação dos trâmites contratuais, o seu Gerente de Relacionamentos HSBC informará qual é o seu CÓDIGO IDENTIFICADOR DA LOJA. Este código será utilizado durante os processos de autenticação, crédito em conta, efetivação e confirmação do pagamento e entre outros processos envolvidos. 2. PROCESSO OPERACIONAL 2.1. Pré Requisitos Loja/Empresa (Cedente (Beneficiário)) cadastrada no sistema Gateway de Pagamentos do HSBC, com as informações: CNPJ e Razão Social; Código Identificador da loja; URL de Notificação de Status de Pedidos; URL de Retorno. Loja/Empresa (Cedente (Beneficiário)) habilitada no Gateway de Pagamentos pela equipe de HTS (HSBC Technology and Services). Esta habilitação é realizada em até (10) dez dias úteis a partir da contratação do serviço. Para a mesma, a Loja/Empresa (Cedente (Beneficiário)) deve fornecer as seguintes informações: Endereço(s) IP(s) do(s) servidor (es) do Site da Loja/Empresa (Cedente (Beneficiário)), que realizarão comunicação com o Gateway de Pagamentos do HSBC. Estes serão habilitados no firewall do HSBC para acesso ao serviço do Gateway. Informações do Certificado Cliente SSL que será utilizado para autenticar as comunicações entre o Site da Loja/Empresa (Cedente (Beneficiário)) e o Gateway de Pagamentos do HSBC. Estas serão configuradas no Servidor Web do Gateway para permitir o acesso de certificado cliente com as referidas informações. PUBLIC - 5

6 Loja/Empresa (Cedente (Beneficiário)) realizou as alterações e configurações necessárias em seu Site e Aplicativo, para realizar as interações necessárias do processo Glossário Cliente Comprador (Sacado (Pagador)) Cliente navegando no site da loja com web browser, realizando uma compra (Para pagar pelo Gateway, deve ser correntista do HSBC). Site da Loja/Empresa (Cedente (Beneficiário)) Site de responsabilidade do Cedente (Beneficiário). Dentro deste, além das páginas Web, é executado o Aplicativo Servidor da Loja. Site Gateway de Pagamentos do HSBC Site de responsabilidade do HSBC. Dentro deste, é executado o Aplicativo Servidor do HSBC. Aplicativo Servidor da Loja Sistema de software Internet de responsabilidade do Cedente (Beneficiário), usado para catálogo eletrônico, carrinho de compras, montagem de pedidos e seleção de métodos de pagamento. Deverá ser alterado para realizar comunicação com o Gateway de Pagamentos do HSBC. Aplicativo Servidor do HSBC Sistema de software Internet de responsabilidade do HSBC, usado para registro de pedidos para pagamento, notificação de status de pagamentos para a loja, e navegação do usuário para realizar o pagamento. Sistema de Software Internet Ações neste tipo de sistema são disparadas através de URLs / Endereços de Internet. Certificado de cliente SSL Certificado Digital para identificação pessoal ou de uma empresa. Usado para finalidades como seguro ou WebSites seguros que exijam este tipo de autenticação. Comercializado por empresas especializadas, que funcionam como Autoridades Certificadoras ou CA s, como Verisign (Digital Id) ou Certisign. Também pode ser gerado através de CA interna ou ser Auto- Assinado, neste caso não precisa ser comprado de uma autoridade certificadora, no entanto não proporciona o mesmo nível de segurança. PUBLIC - 6

7 3. PROCESSOS E CONFIGURAÇÕES A figura abaixo, ilustra o comportamento sistêmico entre as conexões dos WebServers HSBC e cliente: Fonte: HSBC Bank Brasil S.A. Banco Múltiplo Cliente comprador (Sacado (Pagador)) acessa o Site da Loja/Empresa (Cedente (Beneficiário)) e seleciona vários produtos para compra, adicionando os mesmo ao seu Carrinho de Compras, ou outro mecanismo utilizado pela PUBLIC - 7

8 Loja, cadastra-se na Loja (quando aplicável) e seleciona finalizar o pedido Site da Loja/Empresa (Cedente (Beneficiário)) calcula o valor total do pedido, incluindo frete e quaisquer outros valores aplicáveis, e lista as formas de pagamento disponíveis para o cliente. Entre elas estará à forma de pagamento intitulada "Transferência entre contas HSBC", com imagem de logotipo fornecida pelo HSBC Cliente comprador (Sacado (Pagador)) seleciona forma de pagamento Transferência entre contas HSBC clicando em um link ou botão no Site da Loja/Empresa (Cedente (Beneficiário)) Ambiente HSBC. Como resultado da ação de clique no link ou botão, o site da Loja abre uma nova janela (pop up), com tamanho mínimo de 1024X768, e abre nesta Janela uma URL do Aplicativo Servidor da Loja CRIAÇÃO DO PEDIDO: Aplicativo servidor da Loja efetua uma conexão HTTPS direta (Server to Server) com o Site Gateway de Pagamentos do HSBC, realizando um POST para o endereço abaixo: URL de Inclusão de Pedidos: O POST enviado pela Loja para o Servidor do HSBC deve conter os seguintes dados (parâmetros de requisição) para que o registro do pedido ocorra com sucesso: Nome do Campo Tipo de Dados Tamanho Máximo Formato Preenchimento Obrigatório Observações codigoloja NUMÉRICO S Código Identificador da Loja. PUBLIC - 8

9 Código de pedido interno da codigopedidoloja ALFANUMÉRICO 20 AAAAAAAAAA S valorpedido NUMÉRICO (6,2) S loja, gerado pelo Aplicativo Servidor da Loja. Valor a ser pago pelo cliente SACADO (PAGADOR). * IMPORTANTE: Campos numéricos não deverão ser preenchidos com zero a esquerda para completar tamanho do campo. Os caracteres maiúsculos e minúsculos devem ser respeitados, tanto na URL, quanto no nome dos parâmetros do post O Post realizado dispara o Aplicativo Servidor do HSBC. Este realiza as seguintes ações: Valida se a conexão vem de um Site de Loja/Empresa (Cedente (Beneficiário)) com contrato vigente no Gateway, com base em: A) Endereço IP de origem da conexão está habilitado no HSBC para comunicação com o Gateway. B) Certificado digital de segurança (Client Certificate) enviado na conexão segura (SSL/HTTPS) está habilitado para o Gateway. C) Parâmetro codigoloja, passado na requisição está cadastrado no sistema Valida se os dados de pedido já foram usados anteriormente Gera um código de pedido interno do HSBC Registra no sistema do HSBC os dados do pedido para pagamento, e define tempo limite de 30 minutos para que o mesmo seja pago antes que expire e se torne inválido para pagamento. (Vide item exceções) Envia como resposta à conexão, o código de pedido interno do HSBC gerado para o Pedido ou, caso tenha ocorrido uma falha no processo, a string ERRO. Exceções: Se os dados do pedido já foram usados e o mesmo ainda não foi pago pelo Gateway, revalida o pedido (reinicia seu tempo de expiração e atualiza o PUBLIC - 9

10 valor). Se o pedido já havia sido pago, devolve mensagem de erro para o Aplicativo Servidor da Loja ENTRADA NO GATEWAY: O Aplicativo Servidor da Loja recebe a resposta do Site Gateway de Pagamentos do HSBC, captura o código de pedido interno do HSBC recebido, e retorna como resposta para o cliente uma página que realize um POST automático (ex: Form HTML escondido, Ajax) para a URL abaixo: URL de Entrada no Gateway: O Form HTML deve conter os dados/parâmetros abaixo: Nome do Campo Tipo de Dados Tamanho Máximo Formato Preenchimento Obrigatório Observações codigoloja NUMÉRICO S Código Identificador da Loja. codigopedidoloja ALFANUMÉRICO 20 AAAAAAAAAA S codigopedidogat NUMÉRICO S eway Código de pedido interno da loja, gerado pelo Aplicativo Servidor da Loja. Código de pedido interno do HSBC, capturado no passo anterior. *IMPORTANTE: Campos numéricos não deverão ser preenchidos com zero a esquerda para completar tamanho do campo. Os caracteres maiúsculos e minúsculos devem ser respeitados, tanto na URL, quanto no nome dos parâmetros do post O POST dispara o Aplicativo Servidor do HSBC, o qual recebe a requisição, valida se os dados informados são válidos e se o pedido ainda está no tempo limite. Se estiver válido retorna como resposta a página de entrada do Gateway de Pagamentos. Caso contrário retorna como resposta uma página de erro com a mensagem: O pedido de origem deste pagamento não existe PUBLIC - 10

11 ou o tempo de acesso ao HSBC expirou. Por favor reinicie o processo acessando novamente o website do fornecedor A página de entrada do Gateway de Pagamentos é exibida para o cliente na mesma janela pop-up aberta pela loja Cliente se autentica no seu canal HSBC de escolha (Meu HSBC Internet ou Connect Bank), e realiza o pagamento, utilizando as funcionalidades e infraestrutura de segurança dos canais HSBC Aplicativo Servidor do HSBC fecha a janela pop up no browser do cliente, e redireciona o browser do mesmo para o Endereço/URL de Retorno cadastrado para a loja, passando como parâmetro o campo abaixo: Tamanho Preenchimento Nome do Campo Tipo de Dados Formato Máximo Obrigatório codigopedidoloja ALFANUMÉRICO 20 AAAAAAAAAA S Observações Código de pedido interno da loja, gerado pelo Aplicativo Servidor da Loja A URL dispara o Aplicativo Servidor da Loja. Este deverá: Exibir tela de conclusão do pedido para o cliente, indicando ao cliente a situação do pedido conforme abaixo: 4. CONFIGURAÇÕES NO SITE DO CLIENTE 4.1. Na página que lista as opções de Pagamento para o cliente, acrescentar a opção de pagamento Transferência entre contas HSBC, com logotipo fornecido. PUBLIC - 11

12 4.2. Definir como ação/link da referida opção, a abertura de uma janela pop up com tamanho 1024X768, tendo como conteúdo uma chamada ao Aplicativo Servidor da própria Loja Desenvolver no Aplicativo Servidor da Loja a funcionalidade de inclusão de pedido no Gateway de Pagamentos, e redirecionamento para o Gateway de Pagamentos. A mesma consiste nas seguintes atividades: Desenvolver Conexão HTTPS direta (Server to Server) com o Site Gateway de Pagamentos do HSBC, realizando um HTTP POST para a URL de inclusão de Pedido, passando os dados do pedido a pagar, e capturando a resposta (Código de pedido interno do HSBC) Realizar configuração do arquivo de chaves (Key Store) da Loja para conter o Certificado Cliente SSL para ser enviado ao HSBC Desenvolver redirecionamento para a URL de Entrada do Gateway de Pagamentos, passando entre os parâmetros o código interno de pedido do HSBC capturado Desenvolver no Aplicativo Servidor da Loja a página que responderá na URL de Retorno. Esta é a página que é chamada após a conclusão do pagamento do pedido pelo Gateway de Pagamentos HSBC. A mesma pode já existir no sistema da Loja e ser apenas alterada conforme o caso. A mesma consiste nas seguintes atividades: Verificar status do pedido na base de dados da loja Se tiver sido recebida a Notificação de Conclusão do HSBC, o status do pedido estará como Aguardando Confirmação do Pagamento ou similar, e deve ser exibida uma mensagem ao cliente indicando que o pagamento foi concluído Se não tiver sido recebida a Notificação de Conclusão do HSBC, deve ser exibida uma mensagem para o cliente indicando que o pagamento pode não ter sido realizado, e que o cliente verifique com seu banco se o pagamento foi realizado. PUBLIC - 12

13 4.5. CONSULTA STATUS DO PEDIDO: Aplicativo servidor da Loja efetua uma conexão HTTPS direta (Server to Server) com o Site Gateway de Pagamentos do HSBC, realizando um POST para o endereço abaixo: URL de Consulta Status de Pedido: O POST enviado pela Loja para o Servidor do HSBC deve conter os seguintes dados (parâmetros de requisição) para que a consulta do status dos pedidos ocorra com sucesso: Nome do Campo Tipo de Dados Tamanho Máximo Formato Preenchimento Obrigatório Observações codigoloja NUMÉRICO S Código Identificador da Loja. codigopedidoloja ALFANUMÉRICO 20 AAAAAAAAAA S valorpedido NUMÉRICO (6,2) S Código de pedido interno da loja, gerado pelo Aplicativo Servidor da Loja. Valor a ser pago pelo cliente SACADO (PAGADOR). *IMPORTANTE: Campos numéricos não deverão ser preenchidos com zero a esquerda para completar tamanho do campo Os caracteres maiúsculos e minúsculos têm de ser respeitados, tanto os da URL quanto os do nome dos parâmetros do post. Os pedidos (status) são atualizados diariamente (inclusive feriados e finais de semanas), das 09:00 à 01:00, a cada 30 minutos O Post realizado dispara o Aplicativo Servidor do HSBC. Este realiza as seguintes ações: Valida se a conexão vem de um Site de Loja/Empresa (Cedente (Beneficiário)) com contrato vigente no Gateway, com base em: A) Endereço IP de origem da conexão está habilitado no HSBC para comunicação com o Gateway. PUBLIC - 13

14 B) Certificado digital de segurança (Client Certificate) enviado na conexão segura (SSL/HTTPS) está habilitado para o Gateway. C) Parâmetro codigoloja, passado na requisição está cadastrado no sistema Valida se os dados de pedido estão corretos Envia como resposta à conexão, o status do pedido ou, caso tenha ocorrido uma falha no processo, a string ERRO. Os status de retorno disponíveis são: Pedido inexistente: 0 Pedido solicitado: 1 Pagamento pendente: 3 Pagamento efetuado: 4 Pagamento recusado: 5 5. ARQUIVO DE RETORNO Diariamente é disponibilizado arquivo retorno (OFB) com as informações de todos os pagamentos realizados no dia anterior. Por meio desse arquivo a loja dará o tratamento necessário para confirmar os pagamentos recebidos. *IMPORTANTE: Apenas os pedidos com status 4 serão enviados no arquivo de retorno. Clientes cadastrados com a opção de tarifa mensal, receberão o arquivo de retorno com o campo valor da tarifa em branco. A única exceção será no dia do mês em que a cobrança da tarifa for realizada. Este arquivo pode ser disponibilizado de duas formas para o cliente: via VAN ou via Connect Bank. Caso o cliente tenha interesse em receber o arquivo de retorno, ele deverá entrar em contato com o seu Gerente de Relacionamento, ou enviar um para a chave suporte.gtw@hsbc.com.br. PUBLIC - 14

15 6. LEIAUTE DO ARQUIVO DE RETORNO Header do Arquivo Retorno Campo Posição Tipo Conteúdo A Alfa (001) Código do registro "A" A Num (001) Código de remessa "2" (débito online) A Num (006) Código da empresa A Alfa (040) Nome da empresa A Alfa (020) Uso futuro A Num (003) Código do banco A Alfa (020) Nome do banco A Num (008) Data da geração do arquivo - formato AAAAMMDD A Num (006) Número sequencial do arquivo A Alfa (045) Uso futuro Detalhe do Arquivo Retorno Campo Posição Tipo Conteúdo G Alfa (001) Código do registro "G" G Alfa (020) Conta corrente crédito G Alfa (005) Uso futuro G Num (008) Data do pedido - formato AAAAMMDD G Num (008) Data do pagamento - formato AAAAMMDD G Alfa (007) Código pedido HSBC G Alfa (020) Código pedido da Empresa G Num (008) Valor do pedido G Num (006) Valor da tarifa G Num (008) Número sequencial de registro G Num (002) Canal de pagamento - 01 pessoa física 08 pessoa jurídica G Alfa (057) Uso futuro Trailer do Arquivo Retorno Campo Posição Tipo Conteúdo Z Alfa (001) Código do registro "Z" Z Num (006) Total de registros do arquivo, inclusive header e trailer Z Num (017) Valor total recebido dos registros do arquivo Z Alfa (126) Uso futuro PUBLIC - 15

16 7. LOGOTIPO HSBC Para incluir em seu WebSite o logo do HSBC, entre em contato com seu Gerente de Relacionamento. 8. TESTES FINAIS Antes de colocar a opção de Pagamento por transferência entre contas HSBC em seu site, entre em contato com seu Gerente de Relacionamento para que ele sinalize a iniciação dos testes de conexão, assim todo o ambiente será submetido às devidas homologações técnica. Este procedimento é indispensável para se garantir a qualidade da conexão, segurança e efetivação das transações. 9. ANEXO I EXEMPLO DE DESENVOLVIMENTO EM PHP <?php /* */ // Parâmetros: // $url: URL de destino para o post // (ex.: // $request: string com os parâmentros a serem enviados // (ex.: codigoloja=10&codigopedidoloja=99&valorpedido=110.00) function postservertoserver($url, $request) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $request); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_VERBOSE, '0'); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, '0'); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, '0'); // caminho absoluto da localização do arquivo.crt do certificado curl_setopt($ch, CURLOPT_CAINFO, '/var/www/vhosts/seu.dominio/ssl/certificado.crt'); // caminho absoluto da localização do arquivo no formato.pem do certificado (o arquivo pode ter outras extensões desde que esteja no formato PEM) curl_setopt($ch, CURLOPT_SSLCERT, '/var/www/vhosts/seu.dominio/ssl/certificado.pem'); // caminho absoluto da localização do arquivo contendo a chave SSL privada curl_setopt($ch, CURLOPT_SSLKEY, '/var/www/vhosts/seu.dominio/ssl/certificado. key'); // A senha necessária para usar o certificado curl_setopt($ch, CURLOPT_SSLCERTPASSWD, Gateway de Pagamentos 'password'); HSBC - 8/8/2013 // documentação de como gerar o.pem corretamente, a partir do.pfx do certificado // podem ser conferidas no seguinte link: // PUBLIC - 16

17 Fonte: Polvo Tecnologia Comunicação e Sépha Perfurmaria PUBLIC - 17