Você está na página 1de 13

Manual de Integrao WebCheckout

Contedo
1. 2. 2.1. 2.2. 2.2.1. 2.3. 2.4. 2.5. 2.5.1. 2.5.2. 2.5.3. 3. 3.1. 3.2. 3.3. 3.4. Introduo..................................................................................................................... 3 Integrao WebCheckout ............................................................................................. 3 Campos Obrigatrios ................................................................................................. 3 Integrao Ideal ......................................................................................................... 4 Cdigo exemplo com os campos necessrios para a Integrao Ideal .................. 5 Dados do pedido ........................................................................................................ 5 Dados do comprador e de entrega ............................................................................ 6 Recursos opcionais .................................................................................................... 7 Pr-seleo dos meios de pagamento ................................................................... 8 Transao dependente ........................................................................................... 9 Validao dos Dados da Transao ....................................................................... 9

Retorno automtico dos dados ................................................................................... 10 URL de Retorno ....................................................................................................... 11 URL de Aviso ........................................................................................................... 11 Diferena entre URL de Retorno e URL de Aviso .................................................... 12 Consultar Dados de Transao ............................................................................... 13

1. Introduo
Esse manual tem como objetivo auxiliar desenvolvedores e plataformas a integrar o sistema da Bcash em suas lojas virtuais.

2. Integrao WebCheckout
A integrao com o Bcash pode ser realizada independente da linguagem ou sistema utilizado pela loja virtual. A comunicao com nosso sistema ser realizada atravs de um POST enviado pela loja com as informaes do pedido. Para uma melhor experincia de compra e maior converso de vendas, sugerimos que utilize a Integrao Ideal, enviando os dados do comprador e de entrega junto aos Campos Obrigatrios. A seguir veremos os campos que podem ser enviados.

2.1. Campos Obrigatrios


Veja abaixo os campos necessrios para que uma transao seja gerada com sucesso no Bcash.
Nome do campo Envio Necessrio? Formato N mx de caractres Descrio

Dados do Vendedor
email_loja Sim Alfa-Numrico 80 E-mail cadastrado no Bcash.

Dados do Pedido
produto_codigo_1 produto_descricao_1 produto_qtde_1 produto_valor_1 Sim Sim Sim Sim Alfa-Numrico Texto Numrico Numrico 50 255 11 11 Cdigo que identifica o produto em sua loja. Descrio ou nome do produto. Essa informao ser visualizada pelo comprador. Quantidade comprada deste produto. Valor unitrio do produto. Usar ponto (.) para separar os decimais.

Ateno: o nmero 1 nos campos acima caracteriza as informaes do primeiro produto, caso o pedido possua dois ou mais produtos, os mesmos devero obrigatoriamente ser informados da mesma maneira, porm, o nmero 1 dever ser substitudo por 2, 3 e assim sucessivamente (Exemplo). Importante: Os campos acima so obrigatrios para gerar uma transao com sucesso em nosso sistema, porm, recomendamos que no envie apenas esses campos e integre a loja virtual utilizando todos os campos sugeridos na Integrao Ideal.

2.2. Integrao Ideal


Para que uma transao seja finalizada com sucesso no Bcash, necessrio que alguns dados pessoais e de entrega sejam informados no processo de pagamento, sendo assim, visando uma melhor experincia de compra e uma maior converso das vendas, sugerimos que utilize a Integrao Ideal. Para isso, basta solicitar no processo de compra da prpria loja virtual, os dados necessrios para finalizar uma transao em nosso sistema e envi-los via POST no momento em que a transao criada. Segue abaixo os dados necessrios para uma Integrao Ideal:
Nome do campo Envio necessrio? Formato N mx de caractres Descrio

Dados do Vendedor
email_loja Sim Alfa-Numrico 80 E-mail cadastrado no Bcash.

Dados do Pedido
produto_codigo_1 Produto_descricao_1 Produto_qtde_1 Produto_valor_1 Sim Sim Sim Sim Alfa-Numrico Texto Numrico Numrico 50 255 11 11 Cdigo que identifica o produto em sua loja. Descrio ou nome do produto. Essa informao ser visualizada pelo comprador. Quantidade comprada deste produto. Valor unitrio do produto. Usar ponto (.) para separar os decimais.

Ateno: o nmero 1 nos campos acima caracteriza as informaes do primeiro produto, caso o pedido possua dois ou mais produtos, os mesmos devero obrigatoriamente ser informados da mesma maneira, porm, o nmero 1 dever ser substitudo por 2, 3 e assim sucessivamente (Exemplo).

Dados de Entrega
cep endereco cidade estado Sim Sim Sim Sim Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico 9 100 255 2 CEP do comprador Endereo e nmero do comprador separados por vrgula (Ex: Av. Paulista, 1070). Cidade do comprador Estado do comprador

Dados do Comprador
email nome cpf telefone celular cliente_razao_social cliente_cnpj Sim Sim Sim Sim* Sim* Sim** Sim** Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Numrico 80 80 17 20 20 255 30 E-mail do comprador Nome do comprador CPF do comprador. Telefone do comprador Celular do comprador Razo social do cliente. CNPJ do cliente.

* Basta enviar um dos campos, ou seja, Telefone ou Celular. ** Campo necessrio apenas quando comprador for uma Pessoa Jurdica. Observao: Mesmo enviando os campos necessrios para o cadastro de Pessoa Jurdica, o comprador poder se cadastrar como Pessoa Fsica. Essa escolha ser feita pelo comprador em nosso sistema.

2.2.1. Cdigo exemplo com os campos necessrios para a Integrao Ideal


Segue exemplo de cdigo com os campos necessrios para a Integrao Ideal:
<form name="bcash" action="https://www.bcash.com.br/checkout/pay/" method="post"> <!-- Identificao do vendedor --> <input name="email_loja" type="hidden" value="sualoja@sualoja.com.br"> <!-- Dados do Pedido / Produtos --> <input name="produto_codigo_1" type="hidden" value="1001"> <input name="produto_descricao_1" type="hidden" value="Camisa Seleo Brasileira"> <input name="produto_qtde_1" type="hidden" value="1"> <input name="produto_valor_1" type="hidden" value="250.00"> <input name="produto_codigo_2" type="hidden" value="1002"> <input name="produto_descricao_2" type="hidden" value="Raquete de Tnis"> <input name="produto_qtde_2" type="hidden" value="2"> <input name="produto_valor_2" type="hidden" value="85.26"> <!-- Dados do Comprador --> <input name="email" type="hidden" value="email.comprador@dominio.com.br"> <input name="nome" type="hidden" value="Nome do Comprador"> <input name="cpf" type="hidden" value="67882081744"> <input name="telefone" type="hidden" value="1126267469"> <input name="cliente_cnpj" type="hidden" value=""> <input name="cliente_razao_social" type="hidden" value=""> <!-- Dados de Entrega --> <input name="cep" type="hidden" value="04001001"> <input name="endereco" type="hidden" value="Av. Paulista, 1070"> <input name="cidade" type="hidden" value="So Paulo"> <input name="estado" type="hidden" value="SP"> <input type="image" src=https://www.bcash.com.br/webroot/img/bt_comprar.gif value="Comprar" alt="Comprar" border="0" align="absbottom" > </form> * Substitua sualoja@sualoja.com.br pelo e-mail cadastrado no Bcash

2.3. Dados do pedido


Seguem os dados do pedido que podem ser enviados ao nosso sistema:
Nome do campo Envio necessrio?
Sim Sim Sim Sim No No No No

Formato

N mx de caractres
50 255 11 11 50 11 30 255

Descrio

Dados do Pedido
produto_codigo_1 produto_descricao_1 produto_qtde_1 produto_valor_1 id_pedido frete tipo_frete produto_extra_x Alfa-Numrico Texto Numrico Numrico Alfa-Numrico Numrico Alfa-Numrico Alfa-Numrico Cdigo que identifica o produto em sua loja. Descrio ou nome do produto. Essa informao ser visualizada pelo comprador. Quantidade comprada deste produto. Valor unitrio do produto. Usar ponto (.) para separar os decimais. Nmero do pedido gerado pela loja virtual. Valor total do frete. Tipo de Frete (Ex: Sedex, PAC, e-Sedex) Descrio adicional do produto

Ateno: o nmero 1 nos campos acima caracteriza as informaes do primeiro produto, caso o pedido possua dois ou mais produtos, os mesmos devero obrigatoriamente ser informados da mesma maneira, porm, o nmero 1 dever ser substitudo por 2, 3 e assim sucessivamente (Exemplo).

2.4. Dados do comprador e de entrega


Assim como os dados do pedido, tambm possvel enviar os dados do comprador e de entrega, veja abaixo:
Nome do campo Envio necessrio? Formato N mx de caractres Descrio

Dados de Entrega
cep endereco bairro cidade estado complemento Sim Sim No Sim Sim No Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico 9 100 50 255 2 80 CEP do comprador Endereo do comprador Bairro do comprador Cidade do comprador Estado do comprador Complemento do endereo

Dados do Comprador
email nome cpf telefone celular cliente_razao_social cliente_cnpj sexo data_nascimento rg data_emissao_rg orgao_emissor_rg estado_emissor_rg Sim Sim Sim Sim* Sim* Sim** Sim** No No No No No No Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico Alfa-Numrico 80 80 17 20 20 255 30 1 10 20 10 20 2 E-mail do comprador Nome do comprador CPF do comprador. Telefone do comprador Celular do comprador Razo social do comprador. CNPJ do comprador. Sexo do comprador (M ou F) Data de Nascimento (dd/mm/aaaa) RG do comprador Data de emisso do RG (dd/mm/aaaa) rgo emissor do RG Estado onde foi emitido o RG

* Basta enviar um dos campos, ou seja, Telefone ou Celular. ** Campo necessrio apenas quando comprador for Pessoa Jurdica. Observao: Mesmo enviando os campos necessrios para o cadastro de Pessoa Jurdica, o comprador poder se cadastrar como Pessoa Fsica. Essa escolha ser feita pelo comprador em nosso checkout. Ateno: Os campos marcados com Sim no so campos obrigatrios, porm, so informaes necessrias para que uma transao seja finalizada. Enviando-as o comprador no ter que preench-las novamente em nosso sistema, o que torna a experincia de compra melhor e aumenta a converso de vendas da loja virtual.

2.5. Recursos opcionais


Para uma melhor usabilidade do nosso sistema, tambm disponibilizamos recursos opcionais que podem ser utilizados na integrao, so eles:
Nome do campo Formato N mx de caracteres Campos Opcionais Usabilidade
URL que indica uma pgina em sua loja virtual para onde o comprador ser direcionado aps finalizar o pagamento e que tambm poder receber as atualizaes de status das transaes, caso escolha esse tipo de integrao para o Retorno automtico dos dados. Saiba mais URL que indica uma pgina em sua loja virtual que receber as atualizaes de status das transaes, caso escolha esse tipo de integrao para o Retorno automtico dos dados. Saiba mais Este campo ativa uma contagem regressiva de 30 segundos que redirecionar automaticamente o comprador para a URL informada no campo url_retorno. Basta informar o valor true no campo redirect que a contagem regressiva ser iniciada automaticamente. Utilizado para definir os segundos que a contagem regressiva ter at que o comprador seja redirecionado para a URL de Retorno (url_retorno). redirect_time Numrico 2 Valores permitidos: 0 a 60 (segundos). Para o redirecionamento imediato, use 0. Se este parmetro vier vazio ou invlido, o Bcash ir considerar o tempo padro de 30 segundos. Permite criar uma instruo criptografada das informaes enviadas ao Bcash atravs do cdigo html, garantindo a integridade dos dados. Saiba mais Valor total do desconto atribudo pela loja. Usar . para separar os decimais (Enviar o valor que ser descontado e no a porcentagem). Valor total do acrscimo feito pela loja. Usar . para separar os decimais (Enviar o valor que ser acrescido e no a porcentagem). Limitar o nmero mximo de parcelas que a loja aceitar. Pr-seleo dos meios de pagamento. meio_pagamento Numrico 2 Ao informar nesse campo o cdigo do meio de pagamento escolhido pelo comprador, o Bcash j trar selecionado o meio de pagamento escolhido. Saiba mais Identificao da Plataforma desenvolvedora da Loja Virtual. Campo de Livre Digitao. Quantidade de meses da garantia do fabricante. E-mail do comissionado. Saiba mais Valor que o comissionado ir receber. Usar "." para separar os decimais (Enviar o valor da comisso e no a porcentagem). Saiba mais

Descrio

url_retorno

Alfa-Numrico

255

url_aviso

Alfa-Numrico

255

redirect

Alfa-Numrico

10

hash

Alfa-Numrico

255

desconto

Numrico

11

acrescimo parcela_maxima

Numrico Numrico

11 2

id_plataforma* free meses_garantia email_dependente_x valor_dependente_x

Numrico Alfa-Numrico Numrico Alfa-Numrico Numrico

5 255 3 80 50

* O envio do campo id_plataforma torna-se obrigatrio para a identificao das plataformas parceiras.

2.5.1. Pr-seleo dos meios de pagamento


A Bcash possibilita que a loja virtual informe qual o meio de pagamento que ser utilizado pelo comprador, geralmente esse recurso utilizado para oferecer descontos ou acrscimos para determinados meios de pagamento. Para a integrao desse recurso, a loja virtual dever disponibilizar em seu checkout todos os meios de pagamento oferecidos pela Bcash, assim, o comprador ir selecionar, ainda na loja virtual, qual ser o meio de pagamento utilizado para finalizar a compra. Cada meio de pagamento possui um cdigo identificador na Bcash, sendo assim, basta inform-lo no input meio_pagamento junto aos dados do pedido enviados via POST. Segue abaixo o cdigo identificador dos meios de pagamento:
Cdigo identificador dos meios de pagamento
Visa Mastercard American Express Aura Diners Hipercard Elo Boleto Transferncia OnLine Banco do Brasil Transferncia OnLine Bank Bradesco Transferncia OnLine Bank Ita Transferncia OnLine Bank Banrisul Transferncia OnLine Bank HSBC 1 2 37 45 55 56 63 10 58 59 60 61 62

Importante: Esse recurso ir apenas pr-selecionar o meio de pagamento escolhido pelo comprador, com isso, ao ser direcionado para o checkout da Bcash o comprador poder finalizar sua compra com os demais meios de pagamento oferecidos. Para bloquear os demais meios de pagamento e fazer com que o comprador finalize sua compra com o meio de pagamento selecionado na loja, entre em contato com nossa Central de Atendimentos e solicite o bloqueio dos meios de pagamento.

2.5.2. Transao dependente


Nosso sistema tambm oferece a possibilidade de gerar comisses automaticamente para terceiros, ou seja, ao criar uma transao a loja poder informar o valor que ser enviado automaticamente ao comissionado aps a transao ser concluda. Para utilizar a Transao Dependente a loja virtual dever adicionar junto s informaes do pedido os campos email_dependente_1, onde informar o e-mail para qual o valor da comisso ser enviado e o campo valor_dependente_1, onde dever informar o valor da comisso que ser repassado, esse deve ser o valor exato da comisso e no a porcentagem da mesma. Seguem os campos abaixo:
Nome
email_dependente_1 valor_dependente_1

Formato
Alfa-Numrico Numrico

N mx de caractres
80 50

Descrio
E-mail do comissionado. Valor que o comissionado ir receber. Usar "." para separar os decimais (Enviar o valor da comisso e no a porcentagem).

Ateno: o nmero 1 nos campos acima caracteriza as informaes do primeiro dependente, caso houver mais dependentes para uma mesma transao, os dois campos devero ser informados novamente, porm, o nmero 1 dever ser substitudo por 2, 3 e assim sucessivamente. Observao: Uma transao pode ter no mximo 6 dependentes.

Para mais informaes sobre Transao Dependente, clique aqui.

2.5.3. Validao dos Dados da Transao


A Validao dos Dados da Transao um recurso que oferece mais segurana durante a troca de informaes entre a loja virtual e o Bcash; Utilizando este recurso, podemos validar se as informaes recebidas via POST foram realmente enviadas pela loja virtual, garantindo que uma requisio alterada no seja processada. Segue abaixo os procedimentos para integrar a Validao dos Dados da Transao:
1 2 3 4 5 Realizar UrlEconde nos valores dos parmetros que sero enviados ao Bcash; Ordenar os parmetros alfabeticamente separados pelo caracter "&"; Concatenar a chave de acesso (token) ao final da string ordenada e realizar um MD5; Obter como resultado um hash de 32 caracteres; Enviar o valor obtido junto aos dados do pedido, no parmetro denominado hash.

Realizar UrlEconde nos valores dos parmetros que sero enviados ao Bcash;

Parmetro
produto_codigo_x produto_descricao_x email_loja

Valor com UrlEncode


Produto+teste Descritivo+do+meu+produto emaildaloja%40minhaloja.com.br

Ordenar os parmetros alfabeticamente separados pelo caracter "&";

campanha=&cliente_cnpj=&cliente_razao_social=&cod_loja=&cpf=15273417805&c_data_nascimento=&c_rg=&c_rg _emissao=&c_rg_orgao_emissor=&c_rg_estado_emissor=&email=sergio%40bcash.com.br&email_loja=lojamodelo %40bcash.com.br&id_pedido=&numero_gerado=&ponto=&sexo=&tipo=cpf&tipo_conta=1

Concatenar a chave de acesso (token) ao final da string ordenada e realizar um MD5;

MD5("campanha=&cliente_cnpj=&cliente_razao_social=&cod_loja=&cpf=15273417805&c_data_nascimento=&c_rg= &c_rg_emissao=&c_rg_orgao_emissor=&c_rg_estado_emissor=&email=sergio%40bcash.com.br&email_loja=lojamo delo%40bcash.com.br&id_pedido=&numero_gerado=&ponto=&sexo=&tipo=cpf&tipo_conta=1TOKEN")

Obter como resultado um hash de 32 caracteres;


de8d0cbfb96f03cac6b8e94488790116

Enviar o valor obtido junto aos dados do pedido, no parmetro denominado hash.
<input type="hidden" name="hash" value="de8d0cbfb96f03cac6b8e94488790116" />

3. Retorno automtico dos dados


O Retorno automtico dos dados um recurso oferecido pela Bcash para notificar a loja virtual sobre os status das transaes. Essas notificaes so enviadas sempre que uma nova transao criada ou quando h uma alterao de status da mesma. Com esse recurso integrado, o lojista poder acompanhar as transaes diretamente na rea administrativa de sua loja virtual, no sendo necessrio acessar sua conta do Bcash para verificar os status das transaes.

10

Atualmente h duas opes para o recebimento do retorno automtico dos dados, a URL de Retorno e a URL de Aviso, segue abaixo informaes sobre cada uma delas.

3.1. URL de Retorno


Utilizando essa opo, a loja virtual receber um POST com todas as informaes sobre a transao sempre que houver uma alterao de status. A URL de Retorno tambm pode ser configurada como uma pgina de finalizao da prpria loja virtual, para onde o comprador poder ser direcionado aps concluir o pagamento na Bcash, ou seja, em uma mesma URL possvel receber as informaes das transaes e disponibilizar uma pgina de finalizao da prpria loja virtual. Poder informar a URL de Retorno atravs do parmetro url_retorno, que deve ser enviado no POST junto aos dados do pedido ou poder inseri-la no menu Ferramentas da conta do lojista. Para mais informaes e exemplos clique aqui.

3.2. URL de Aviso


Diferente da URL de Retorno, a funo da URL de Aviso apenas receber os status das transaes que so enviados via POST. Nessa opo somente trs dados so retornados, transacao_id, pedido e status. Caso a loja virtual necessite de mais informaes, ser necessrio integrar a ferramenta Consultar Dados da Transao, que atravs de uma consulta retorna, em um XML ou JSON, todos os dados da transao. Conforme informado acima, a URL de Aviso utilizada apenas para receber e atualizar os status da transao, sendo assim, caso queira disponibilizar uma pgina de finalizao da prpria loja virtual para onde o comprador dever ser direcionado aps o pagamento, dever criar tambm uma URL de Retorno. Quanto uma URL de Retorno e uma URL de Aviso so informadas em uma mesma transao, cada uma assume uma funo, que so: URL de Retorno: ser apenas a pgina de finalizao para onde o comprador ser direcionado aps finalizar o pagamento; URL de Aviso: URL para onde as atualizaes dos pedidos sero enviadas;

11

Seguem os dados retornados atravs da URL de Aviso:


Campo
transacao_id pedido

Descrio
ID da transao que foi gerada no Bcash. Nmero do pedido que foi atribudo pela loja virtual. Status retornados: Em andamento Aprovada Concluda Disputa Devolvida Cancelada Chargeback

status

A URL de Aviso pode ser informada atravs do parmetro url_aviso que deve ser enviado no POST junto aos dados do pedido ou pode ser inserida no menu Ferramentas da conta do lojista.

3.3. Diferena entre URL de Retorno e URL de Aviso


Segue abaixo tabela com as diferenas entre as duas opes de Retorno Automtico:
Caracterstica
Quantidade de status enviados no retorno

URL de Retorno
3

URL de Aviso
7 Em andamento Aprovada

Transao em Andamento Status enviados no retorno Transao Concluda Transao Cancelada

Concluda Disputa Devolvida Cancelada Chargeback

Redirecionamento aps finalizao da transao Quantidade de informaes enviadas Necessrio utilizar a ferramenta de Consultar dados de Transao

Sim 38 No

No 3 Sim

12

3.4. Consultar Dados de Transao


A URL de Retorno e a URL de Aviso enviam os dados das transaes automaticamente para o sistema da loja virtual, entretanto, essa comunicao feita somente quando h uma alterao de status os quando uma nova transao criada. J com a ferramenta de Consultar Dados da Transao possvel consultar o status e todos os dados de uma determinada transao a qualquer momento. Geralmente essa ferramenta utilizada como complemento da URL de Aviso. Segue abaixo os passos para a consulta de dados: 1 Loja / Plataforma envia uma requisio via POST para o Bcash informando os dados necessrios para a consulta (E-mail da Loja, Token e ID da Transao ou ID do Pedido); 2 3 4 O Bcash recebe a solicitao e efetua a autenticao do usurio baseando-se nas informaes enviadas no header da requisio; Posteriormente o Bcash realiza a consulta pelo ID da transao ou do pedido; Aps a consulta, retornada ao cliente uma mensagem de sucesso ou erro, formatadas em XML ou JSON; Para mais informaes, detalhes e exemplos de integrao com a ferramenta, clique aqui.

13