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:

1. Possuir uma conta de vendedor na IOPAY (saiba como obter).

2. Habilitar a sua conta para recebimento por botões de pagamento (entre em contato com [e-mail]). Você receberá informações extras como o io_seller_id.

3. 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

Ambiente de testes (Sandbox)

<!-- 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="[e-mail]"/>
  
    <!-- 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="[e-mail]"/>
    <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>

Ambiente de Produção

<!-- Botão de Pagamento IOPay -->
<form id="_iopay_checkout" name="_iopay_checkout" action="https://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="[e-mail]"/>
  
    <!-- 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="[e-mail]"/>
    <input type="hidden" name="invoice" value="Anotação que deve ser inserida na fatura do cliente"/>

    <!-- Configure -->
    <input type="hidden" name="return" value="x"/>
    <input type="hidden" name="notify" value="y"/>
    <input type="hidden" name="cancel_return" value="z"/>
 
    <!-- 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://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://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://checkout.iopay.com.br/assets/js/checkout_behaviour_security.js';
        var s = document.getElementsByTagName('body')[0];
        s.parentNode.insertBefore(iopay, s);
    })();
</script>

Repare que a única mudança para diferenciar o ambiente de produção e testes (sandbox) é o prefixo da URI utilizada: sandbox.checkout.iopay.dev [testes]

checkout.iopay.dev [produção]

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: [e-mail]	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"/>
...etc

PARÂ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"/>
...etc

PARÂ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"/>
...etc

PARÂ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"/>
...etc

PARÂ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"/>
...etc

PARÂ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 [e-mail]	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).

Ambiente de testes (Sandbox)

<!-- 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>

Ambiente de Produção

<!-- 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://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 [e-mail]

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