Botão de Pagamentos
A integração rápida, robusta e segura
Através dos botões de pagamento da IOPAY você pode integrar o seu website ou loja em minutos, através de um código HTML simples que deve ser inserido na sua página.
O botão de pagamentos da IO permite que você obtenha uma integração simples, rápida e segura. A página de pagamento customizada com o seu logo será aberta de forma segura e automática dentro do seu site, garantindo maior conversão das vendas.
Todas as nossas integrações estão em conformidade com as entidades reguladoras de meios de pagamento e seguem o mais alto grau de segurança desse mercado.
Através do botão de pagamento da IOPAY você será capaz de receber pagamentos nas seguintes modalidades:
O guia abaixo lhe orientará sobre aspectos importantes e como integrar o botão de pagamento IOPAY em seu projeto.
Setup
Para utilizar o botão de pagamento da IOPAY você deve:
Possuir uma conta de vendedor na IOPAY (saiba como obter).
Habilitar a sua conta para recebimento por botões de pagamento (entre em contato com [email protected]). Você receberá informações extras como o io_seller_id.
Inserir o
<form>abaixo em seu HTML
Código do Botão de Pagamento
Após seguir as orientações da seção 'Setup' acima, copie e cole o código abaixo na sua página.
O código abaixo é responsável por renderizar o botão de pagamentos vinculando ele à sua conta de vendedor na IOPAY
<!-- Botão de Pagamento IOPay -->
<form id="_iopay_checkout" name="_iopay_checkout" action="https://sandbox.checkout.iopay.dev/app/pay/85a6c41f63bb533c3cd157ea4df91a72" method="post" target="_iopay_frame" onSubmit="return false;">
<!-- modalidade de integração -->
<input type="hidden" name="integration" value="transparent"/>
<!-- Identificador da loja (email cadastrado na IOPAY) -->
<input type="hidden" name="business" value="[email protected]"/>
<!-- Identificador da pedido na sua loja (Exemplo: id do pedido) | Campo do tipo string podendo conter até 64 caracteres -->
<input type="hidden" name="reference_id" value="112233445566778899"/>
<!-- Produtos do carrinho de compras -->
<input type="hidden" name="product_name[]" value="Camiseta XYZ Masculina, M"/>
<input type="hidden" name="product_number[]" value="7127372"/>
<input type="hidden" name="product_amount[]" value="99.0"/>
<input type="hidden" name="product_quantity[]" value="1"/>
<input type="hidden" name="product_weight[]" value="0.5"/>
<input type="hidden" name="currency_code" value="BRL"/>
<!-- Informações do cliente comprador -->
<input type="hidden" name="first_name" value="João"/>
<input type="hidden" name="last_name" value="da Silva"/>
<input type="hidden" name="cpf" value="684.470.230-28"/>
<input type="hidden" name="phone_number" value="(11)98765-4321"/>
<input type="hidden" name="address1" value="RUA XPTO"/>
<input type="hidden" name="address2" value="200"/>
<input type="hidden" name="city" value="São Paulo"/>
<input type="hidden" name="state" value="SP"/>
<input type="hidden" name="zip" value="05466030"/>
<input type="hidden" name="country" value="Brasil"/>
<input type="hidden" name="email" value="[email protected]"/>
<input type="hidden" name="invoice" value="Anotação que deve ser inserida na fatura do cliente"/>
<!-- Configure -->
<input type="hidden" name="return" value="https://site.com/transaction_result"/>
<!-- Porcentagem de desconto para boleto pago no mesmo dia (apenas numeros) -->
<input type="hidden" name="io_config_primary_color" value="#cc0000"/>
<input type="hidden" name="io_config_secondary_color" value="#FEA40E"/>
<!-- Montante total a ser cobrado -->
<input type="hidden" name="amount" value="199.00"/>
<button onclick="iopay()" name="payWithIO" style="background-color: #6d000b; color: #fff">PAGAR</button>
</form>
<!-- Fim botão de pagamentos IOPAY -->
<!-- Folha de estilos para o Checkout Transparente IOPAY -->
<link href="https://sandbox.checkout.iopay.dev/checkout/assets/css/front.checkout.transparent.iopay.css" rel="stylesheet">
<!-- Script responsável pelas funcionalidades de frontend do chekout transparente IOPAY -->
<script src="https://sandbox.checkout.iopay.dev/checkout/assets/js/front.checkout.transparent.iopay.min.js"></script>
<!-- Script de análise de comportamento do usuário [Verifique o tópico "Antifraude"] -->
<script>
window.iopayAntifraudPublicKey = 'ABCDEXXX0000000';
window.iopaySecurityPlan = 'with_anti_fraud';
(function() {
var iopay = document.createElement('script');
iopay.id = 'iopayjs'; iopay.type = 'text/javascript';iopay.async = true;
iopay.src = 'https://sandbox.checkout.iopay.com.br/assets/js/checkout_behaviour_security.js';
var s = document.getElementsByTagName('body')[0];
s.parentNode.insertBefore(iopay, s);
})();
</script>Você pode utilizar um botão com estilos CSS personalizados, contudo lembre-se de inseri-lo dentro do form e adicionar o atributo onclick="iopay()", conforme demonstrado ac
Parâmetros
Abaixo relação de parâmetros esperados pelo formulário. Cada pagamento pode conter um ou mais itens, que representam produtos ou serviços que estão sendo vendidos.
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
integration
Esse parâmetro especifica qual o tipo de integração em uso. Valor aceito para botão de pagamentos: transparent
Sim
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
business
Identifica a conta de vendedor cadastrada na IOPAY. Este parâmetro deve ser do tipo email, exemplo: [email protected]
Sim
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
reference_id
Neste parâmetro você pode informar o identificador único do pedido da sua loja, como por exemplo o ID do pedido atual. Este campo pode conter uma cadeia de até 64 caracteres. Exemplo de reference_id: 1234
Ao informar esse parâmetro, você pode usá-lo para recuperar posteriormente o status desse pagamento (aprovado, cancelado, rejeitado etc) e atualizar na sua base de pedidos.
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
product_name[]
Este parâmetro é utilizado para informar os nomes dos itens que estão sendo vendidos.
Para adicionar mais de um item, basta inserir mais um parâmetro product_name[], conforme o exemplo abaixo:
Sim
<input type="hidden" name="product_name[]" value="Produto 1"/>
<input type="hidden" name="product_name[]" value="Produto 2"/>
...etcPARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
product_number[]
Utilize esse parâmetro para informar o identificador único desse produto ou serviço na sua loja ou site, conforme o exemplo abaixo:
Não
<!-- ID do Produto 1 (opcional) -->
<input type="hidden" name="product_number[]" value="55555"/>
<!-- ID do Produto 2 (opcional) -->
<input type="hidden" name="product_number[]" value="99999"/>
...etcPARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
product_amount[]
Parâmetro utilizado para informar o preço individual de cada produto ou serviço comercializado,
Este parâmetro aceita valores numéricos do tipo float. Dessa forma, para informar o valor de R$199,00 deve-se informar 199.00 conforme o exemplo:
Sim
<!-- Valor unitario do produto 1 -->
<input type="hidden" name="product_amount[]" value="199.00"/>
<!-- Valor unitario do produto 2 -->
<input type="hidden" name="product_amount[]" value="350.00"/>
...etcPARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
product_quantity[]
Parâmetro utilizado para informar a quantidade de cada produto comercializado. Apenas números inteiros são aceitos. O exemplo abaixo indica que o cliente está adquirindo 3 Produto 1 e 1 Produto 2.
Sim
<!-- Quantidade do produto 1 -->
<input type="hidden" name="product_quantity[]" value="3"/>
<!-- Quantidade do produto 2 -->
<input type="hidden" name="product_quantity[]" value="1"/>
...etcPARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
product_weight[]
Esse parâmetro é utilizado para informar o peso individual de determinado produto.
O valor desse parâmetro é baseado no tipo numérico float representado em Kg, ou seja, para informar 200g, use: 0.2
Não
<!-- Peso do produto 1 -->
<input type="hidden" name="product_weight[]" value="0.2"/>
<!-- Peso do produto 2 -->
<input type="hidden" name="product_weight[]" value="0.6"/>
...etcPARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
currency_code
Define a moeda utilizada nessa venda. Até o momento o único valor aceito pela IO para esse parâmetro é BRL que representa o Real Brasileiro.
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
first_name
Este campo é opcional e representa o primeiro nome do cliente que iniciou a compra. Você pode usá-lo para enviar o nome do cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
last_name
Este campo é opcional e representa o último nome/sobrenome do cliente que iniciou a compra. Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
cpf
Este campo é opcional e representa o CPF do cliente que iniciou a compra.
Ao usar esse parâmetro na sua integração você melhora a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Este parâmetro permite que você envie o CPF com pontos e traços, conforme o padrão: XXX.XXX.XXX-XX
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
phone_number
Este parâmetro é utilizado para informar o número de telefone com DDD do seu cliente.
Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Este parâmetro permite que você envie o DDD entre parêntesis, conforme o padrão: (XX)XXXXX-XXXX
O valor pode ser composto de um número de celular com DDD ou número de telefone fixo com DDD
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
address1
Utilize esse parâmetro para informar a primeira linha do endereço do cliente. Exemplo: Rua da Consolação
Ao usar esse parâmetro na sua integração você melhora a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
address2
Utilize esse parâmetro para informar o número do endereço do seu cliente. Exemplo: 750
Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
address3
Utilize esse parâmetro para informar o complemento do endereço do seu cliente. Exemplo: Fundos, Casa 2
Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
city
Utilize esse parâmetro para informar a cidade à partir do endereço do seu cliente. Exemplo: São Paulo
Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
state
Utilize esse parâmetro para informar a unidade federativa/estado a partir do endereço do seu cliente.
Ao usar esse parâmetro na sua integração você melhor a experiência de compra do seu cliente, evitando assim que o cliente precise preencher novamente ao acessar o formulário de pagamento
Esse parâmetro deve ser composto pela sigla do estado com 2 letras. Exemplo: SP
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
country
Utilize esse parâmetro para informar o país de origem do seu cliente.
Atualmente o único valor aceito para esse parâmetro pela IOPAY é Brasil
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
zip
Se informado, esse parâmetro é utilizado para fornecer o endereço completo no formulário de pagamento, evitando assim que o seu cliente precise preencher todos os campos
O formato para esse valor deve ser XXXXX-XXX
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
email
Parâmetro utilizado para informar o e-mail do cliente comprador. Ao integrar e enviar esse parâmetro (opcional), você melhora a experiência de compra do seu cliente, pois o valor desse campo virá preenchido no formulário de pagamento.
O formato de dados aceito segue o padrão e-mail, por exemplo [email protected]
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
invoice
Este parâmetro, se usado, informa a descrição da compra na fatura do cliente.
Você pode usá-lo para facilitar a identificação pelo seu cliente da compra efetuada na fatura do cartão.
Exemplo de uso: Loja de Sapatos XYZ (lojadesapatosxyz.com)
Não
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
return
Este parâmetro define a URL da sua loja, que será usada para redirecionar o seu cliente após sucesso na geração do pagamento
Exemplo de uso: https://site.com/transaction_result
A URL receberá parâmetros GET informando o ID da Transação (transaction_id) e o Status (status), o usuário será redirecionado ao Fechar a tela de pagamento. Exemplo:
https://site.com/transaction_result?transaction_id=xx&status=pending
ATENÇÃO: Não utilize essa rota para confirmar o pagamento na sua base de dados. Para confirmação utilize o serviço de WebHooks da IOPAY.
Não
Possíveis 'status' retornados na URL:
pending : pendente, comum para pagamentos por boleto
succeeded : pago com sucesso
pre_authorized : apenas pré-autorizado, ainda estão em análise antifraude
PARÂMETRO
DESCRIÇÃO
OBRIGATÓRIO
amount
Parâmetro obrigatório, utilizado para informar o montante total dessa venda através de um tipo numérico float.
Por exemplo, se a somatória de preços dos produtos + custo de frete para envio é de R$485,70, deve-se utilizar 485.70
Sim
Antifraude
Para prevenir ações suspeitas de fraude, insira o script de monitoramento do comportamento do usuário no rodapé do seu site.
Ao inserir esse trecho de código estaremos monitorando o comportamento do usuário em seu site; É altamente recomendável que este script seja carregado globalmente (em todo site).
<!-- Script de análise de comportamento do usuário -->
<script>
window.iopayAntifraudPublicKey = 'ABCDEXXX0000000';
window.iopaySecurityPlan = 'with_anti_fraud';
(function() {
var iopay = document.createElement('script');
iopay.id = 'iopayjs'; iopay.type = 'text/javascript';iopay.async = true;
iopay.src = 'https://sandbox.checkout.iopay.com.br/assets/js/checkout_behaviour_security.js';
var s = document.getElementsByTagName('body')[0];
s.parentNode.insertBefore(iopay, s);
})();
</script>Não se preocupe com o desempenho da sua página
Este será o ultimo script a ser carregado em sua página, sem afetar a performance e experiência do usuário; Para que isso ocorra, recomendamos que este script seja inserido, globalmente, antes do fechamento da tag </body> ou </footer> no corpo do site.
Não faça nenhuma alteração na estrutura deste script
Este script foi cuidadosamente desenvolvido para monitorar as ações do usuário, e lhe proteger de possíveis fraudes, sem afetar o desempenho do seu site. Não altere a estrutura do script, apenas atribua os valores necessários para configura-lo (Vide o tópico abaixo "Configure o script de monitoramento")
Configure o script de monitoramento
As informações solicitadas para configuração do script de monitoramento podem ser obtidas na sua Conta Digital em: Conta Digital > Pagamentos Online
LINHA
SCRIPT
PROPRIEDADE
TIPO
DESCRIÇÃO
3
window.iopayAntifraudPublicKey
string
Conta Digital > Pagamentos Online > Chave Pública Antifraude
Sua Chave Pública para utilização do sistema antifraude;
4
window.iopaySecurityPlan
string
Conta Digital > Pagamentos Online > Plano Antifraude
Seu plano antifraude contratado junto a IOPAY:
"with_anti_fraud": Plano antifraude padrão
"with_anti_fraud_insurance": Plano antifraude com seguro
Verifique com atenção a configuração do script
window.iopaySecurityPlan: apenas os valores exibidos na descrição são permitidos; Certifique-se de que o tipo do plano foi indicado corretamente para que o script de monitoramento funcione.
Notificações & WebHooks
Webhooks (também conhecidos como HTTP Callbacks) são uma forma de se registrar para receber informações úteis em uma URL específica de sua escolha. Quando ocorre uma alteração no estado de um recurso dentro das plataformas da IOPAY (por exemplo, uma transação é aprovada com sucesso), um evento é gerado por essa ocorrência e enviado para os webhooks cadastrados.
Para utilizar a notificação de eventos você precisa: - Implementar o seu sistema de recebimento de notificações - Cadastrar as URLs desse sistema na IOPAY, através da sua conta digital IO. - Quando ocorrer uma ação ou atualização de status nas transações enviadas para a IO, as notificações serão disparadas de acordo com os webhooks cadastrados
Beta Caso não encontre essa opção em sua conta digital IO, envie uma solicitação de ativação desse recurso para [email protected]
Customização e Cores
Com o botão de pagamentos IOPAY você pode customizar as cores e logotipo da página checkout.
Você pode definir a cor primária e secundária em hexadecimal. Essas duas cores são usadas para compor o layout do checkout que será aberto após o clique no botão de pagamentos.
Para definir as cores do seu checkout, informe o código hexadecimal (com #) nos seguintes input hiddens.
<!-- Definição das cores primária e secundária da página de checkout -->
<input type="hidden" name="io_config_primary_color" value="#cc0000"/>
<input type="hidden" name="io_config_secondary_color" value="#FEA40E"/>Se esses parâmetros não forem configurados no seu form, o checkout atribuirá automaticamente as cores padrão da página de checkout, conforme imagem abaixo
Customização de Logotipo
Com o checkout e botão de pagamento IOPAY você pode facilmente adicionar o logotipo da sua empresa.
Dessa forma você aumenta a conversão de vendas do seu site ou loja virtual, ao customizar com a mesma marca e cores da sua loja virtual.
Para inserir o logotipo, faça login na sua conta digital IOPAY e clique em 'Configurações' > 'Pagamentos Online' para especificar a URL da imagem, como ilustrado abaixo:
Padrão de imagens aceitas
Width: 171px
Max Height: 72px
Formatos: png, jpg ou svg
Last updated
Was this helpful?