Integração por widget incorporado

Integrar o widget da 1Flow

O widget da 1Flow pode ser incorporado em qualquer página por meio de um iframe. Você pode abrir o checkout já preenchido para compra de cripto com Pix ou para venda de USDC/USDT com recebimento em reais. A 1Flow cuida da confirmação de email, verificação de conta, Pix, conversão e acompanhamento da ordem.

Fluxo recomendado

  1. Defina no seu sistema a direção do fluxo: compra cripto ou venda cripto para reais.
  2. Para compra, informe valor em reais, moeda, rede e carteira de destino do usuário.
  3. Para venda, informe moeda, rede e valor em cripto quando quiser abrir a tela já preenchida.
  4. Monte a URL do widget com os parâmetros desejados.
  5. Incorpore o iframe na página de checkout ou em uma tela dedicada.
  6. O usuário confirma email, valida a conta quando necessário e acompanha a ordem na própria tela.

Compra: reais para cripto

Use sempre valores codificados para URL. A altura recomendada é de aproximadamente 628 pixels.

<iframe
  src="https://1flow.cash/gateway/widget?asset=USDC&network=polygon&amount=50&wallet=0x37B826...FDaEb6&email=cliente%40exemplo.com"
  width="500"
  height="628"
  style="width:100%;max-width:500px;border:0;border-radius:28px;"
  allow="clipboard-write"
  title="Checkout 1Flow"
></iframe>

Venda: cripto para reais

Para abrir o fluxo de venda, use mode=sell, direction=sell ou flow=offramp. A chave Pix é sempre o CPF validado da própria conta do usuário.

<iframe
  src="https://1flow.cash/gateway/widget?mode=sell&asset=USDC&network=polygon&crypto_amount=10&email=cliente%40exemplo.com"
  width="500"
  height="628"
  style="width:100%;max-width:500px;border:0;border-radius:28px;"
  allow="clipboard-write"
  title="Venda cripto 1Flow"
></iframe>

Parâmetros aceitos

amount Valor inicial. Em compra, representa reais. Em venda, representa quantidade em cripto. Para maior clareza, prefira amount_brl na compra e crypto_amount na venda.
amount_brl Valor inicial em reais para compra. Exemplo: amount_brl=50.
crypto_amount Quantidade inicial em cripto para venda. Exemplo: crypto_amount=10.
asset Criptoativo desejado. Valores atuais: USDC ou USDT.
network Rede de envio. Valor atual: polygon para USDC e USDT.
wallet Carteira de destino no fluxo de compra. Deve ser compatível com a rede informada. Não é necessário no fluxo de venda.
email Email inicial do usuário para agilizar a confirmação. Exemplo: email=cliente%40exemplo.com.
mode Direção inicial do widget. Use mode=sell, direction=sell ou flow=offramp para venda cripto para reais. O padrão é compra.

Exemplos de URL

USDC na Polygon, R$ 50, com carteira e email preenchidos:

https://1flow.cash/gateway/widget?asset=USDC&network=polygon&amount=50&wallet=0x37B8260000000000000000000000000000FDaEb6&email=cliente%40exemplo.com

USDT na Polygon, apenas com valor inicial:

https://1flow.cash/gateway/widget?asset=USDT&network=polygon&amount=100

Venda de 10 USDC na Polygon para receber reais por Pix:

https://1flow.cash/gateway/widget?mode=sell&asset=USDC&network=polygon&crypto_amount=10&email=cliente%40exemplo.com

Venda de USDT na Polygon, abrindo com o mínimo padrão:

https://1flow.cash/gateway/widget?flow=offramp&asset=USDT&network=polygon

Eventos opcionais

O site pai pode ouvir eventos do iframe com postMessage. Isso é opcional: o checkout funciona normalmente mesmo que o parceiro não implemente nenhum listener. 

window.addEventListener('message', (event) => {
  if (event.data?.source !== '1flow-ramp') return;

  if (event.data.type === '1flow:completed') {
    console.log('Compra concluída', event.data.payload);
  }
});

Eventos atuais: 1flow:ready, 1flow:order_created, 1flow:status_changed e 1flow:completed.

Proteção do checkout

O iframe pode ser aberto publicamente, mas ações sensíveis são protegidas por sessão temporária, limites por IP, e-mail, carteira e sessão, além de idempotência para evitar múltiplas ordens em cliques repetidos. Não é necessário cadastrar previamente o domínio do site que incorpora o widget.

Observações importantes