Como funciona a Wyra Rails

O que é a Wyra Rails

A Wyra Rails é a forma de mostrar o catálogo da Wyra — recargas pré-pagas, eSIM de viagem e gift cards digitais, já com preços reais — diretamente no seu próprio site, app ou ferramenta, com pagamento incluído. Você cola um widget (ou chama nossa API, se tiver seu próprio backend), seu cliente compra sem sair da sua página, e a Wyra cuida de tudo o mais: o pagamento (a Wyra é a comerciante registrada de cada venda, sempre — nunca você), a conformidade (incluindo as restrições de países sancionados), a entrega do produto, e a sua comissão.

Hoje a Wyra Rails é um nível de widget incorporável + API: o checkout e os e-mails que seu cliente recebe levam a marca da Wyra. É, deliberadamente, o primeiro passo rumo a uma API completamente white-label — onde esses mesmos e-mails, e potencialmente o checkout, levem a sua própria marca. Essa versão ainda não está construída. Não é uma promessa vazia: é uma base real, em produção, sobre a qual a próxima é construída — e a seção 10 conta exatamente o que falta e como se chega lá.

Como funciona, passo a passo

Da sua primeira visita ao seu primeiro pagamento, é assim que se vê o caminho completo:

1. Você cria sua conta, grátis.
   No portal de parceiros, com Google, Apple, ou seu e-mail com um código — sem senha. Uma conta Wyra Rails é, por dentro, a mesma identidade de um afiliado da Wyra: se você já tem conta (de afiliado, de recargas, de eSIM), faz login e ativa a Rails em uma etapa.
2. Você recebe suas chaves na hora.
   Uma chave pública (segura para colar no navegador) e uma chave secreta (só para o seu próprio backend, nunca em JavaScript). Você pode ter várias de cada tipo — em modo teste ou ao vivo — e rotacioná-las quando quiser, direto do seu painel.
3. A Wyra configura sua margem.
   Por padrão, 10% sobre nosso preço normal — configurável pela Wyra até um teto de 30%, para que o preço final continue competitivo para seu cliente. Hoje o número é definido pela Wyra na sua conta (não é um campo que você edita sozinho pelo painel); se quiser pedir um ajuste, escreva para nós.
4. Você cola o widget — ou chama a API.
   Para a maioria dos sites (WordPress, Wix, Squarespace, ou código próprio) uma <div> mais um <script> bastam. Se você tem seu próprio backend, pode pular o widget e chamar os mesmos endpoints REST diretamente com sua chave secreta — veja a especificação técnica.
5. A Wyra revisa sua conta antes que dinheiro real se mova.
   Uma chave nova pode ler o catálogo (preços reais, ao vivo) imediatamente — isso é só leitura, sem risco. Mas criar uma sessão de pagamento real exige que a Wyra ative sua conta para o modo ao vivo, uma revisão manual, normalmente 1-2 dias úteis.
6. Seu cliente compra sem sair do seu site.
   Ele vê o preço final, sem surpresas, preenche seus dados, e é redirecionado — dentro da mesma aba — para uma página de pagamento segura operada pela Stripe, em nome da Wyra. Ao terminar, ele volta automaticamente para o seu site.
7. A Wyra entrega o produto.
   Usando exatamente o mesmo sistema que já entrega cada recarga, eSIM e gift card da Wyra hoje — nada novo, nada diferente, para uma venda que chegou pelo seu widget.
8. Sua comissão se acumula, visível em tempo real.
   100% da margem que você adicionou fica registrado a seu favor assim que o pagamento é confirmado, com um período de espera (a janela de reembolso) antes de ficar disponível para saque — veja a seção de ganhos.
9. Você recebe.
   Via Stripe Connect — o mesmo sistema de pagamento que os afiliados da Wyra já usam. A Wyra nunca vê seus dados bancários.

Como se vê no seu negócio

O widget, incorporado no seu site: uma caixa compacta que adota a cor de destaque da sua marca (você define com um único atributo). Mostra abas por produto (Recargas / eSIM / Gift cards, ou só a que você habilitar), uma busca por país, e uma lista de preços onde o número grande — o que seu cliente realmente paga, já com sua margem incluída — é o destaque. Ao tocar em um item, abre-se o formulário de compra, com esse mesmo preço final. Abaixo, um pequeno crédito "Powered by Wyra" — não removível neste nível, o mesmo padrão que o Stripe Checkout e outras plataformas de pagamento usam no plano grátis/de baixo custo.

A compra, do lado do seu cliente: ele preenche o e-mail (e o dado do produto — o número a recarregar, por exemplo), toca em "Comprar", e uma verificação anti-bot invisível resolve em segundo plano sem pedir nada a ele. Em seguida é redirecionado — na mesma aba, sem abrir uma janela nova — para uma página de pagamento real, operada pela Stripe, com o nome da Wyra Technologies no extrato do cartão. Ali ele preenche o cartão (ou Apple Pay / Google Pay, se o navegador oferecer) na interface padrão da Stripe — essa tela nunca leva sua marca, deliberadamente: é a prova de que é a Wyra, não você, quem está cobrando. Ao confirmar, a Stripe o redireciona de volta para o seu próprio site, para a página de sucesso que você definir.

Para quais negócios foi pensada

A Wyra Rails não é "para todos" — foi pensada para negócios que já têm uma audiência própria e querem vender algo a mais para ela, sem construir infraestrutura de pagamentos nem negociar com fornecedores atacadistas:

E, sendo igualmente honestos sobre para quem não é a melhor opção hoje: se você precisa que o checkout e os e-mails do seu cliente levem sua marca de ponta a ponta, essa versão (white-label completo) ainda não está construída — veja a seção 10. E se o seu negócio ainda não tem nenhuma audiência própria, o programa de afiliados (compartilhar um link, sem site próprio) costuma ser um ponto de partida melhor do que a Wyra Rails.

Especificações regulatórias

Nenhuma. Você não precisa de licença de transmissor de dinheiro, registro como MSB (Money Services Business), nem de nenhum tipo de conta de pagamentos ou entidade regulada própria para vender através da Wyra Rails.

Isso é possível porque a Wyra — não você — é sempre a comerciante registrada de cada venda. A Wyra opera sob a isenção da FinCEN para pré-pago de circuito fechado (31 CFR 1010.100): o saldo entregue (minutos, dados, o código de uma gift card) não é dinheiro transferível nem resgatável em espécie, então a atividade não se qualifica como transmissão de dinheiro sob essa estrutura. Seu cliente paga diretamente à Wyra através da Stripe; você nunca processa o pagamento, nunca tem acesso aos fundos, e nunca faz parte da cadeia de custódia do dinheiro.

Ganhos e pagamentos

A matemática, com um exemplo real

Sua margem se soma sobre o preço da Wyra — o mesmo que ela já cobra em seu próprio site. É puramente adicional, e 100% dela é sua.

Sua comissão não tira nada da economia própria da Wyra nessa venda: ela existe só porque seu tráfego existe.

O que nunca muda, aconteça o que acontecer

• $0 adiantado. Não há custo para criar sua conta, não há mensalidade, não há mínimo de vendas. É puro pagamento por resultado: você ganha quando seu cliente compra, e nada antes disso.
• Reembolso automático da sua comissão se a venda for revertida. Se uma venda é reembolsada ou contestada (chargeback), sua comissão é revertida automaticamente — o mesmo mecanismo que o programa de afiliados da Wyra já usa, acionado pelo mesmo webhook que processa cada reembolso da Wyra, não importa se a venda veio do seu widget ou diretamente do wyraapp.com. Você nunca recebe por uma venda que não se confirma.
• Margem configurada pela Wyra, não self-service. A porcentagem que você adiciona (10% por padrão, até 30%) é definida pela Wyra na sua conta — não é um controle deslizante que você mesmo edita hoje pelo painel.

Quando e como você recebe

Cada venda atribuída à sua conta fica registrada como comissão "pendente" assim que o pagamento é confirmado. Antes de ficar disponível para saque, ela passa por dois filtros reais, não cosméticos:

1. Janela de reembolso (~30 dias).
   Sua comissão passa de "pendente" para "disponível" só quando a janela de reembolso dessa venda se fecha — o mesmo período de espera que já protege o programa de afiliados da Wyra. Não é uma demora arbitrária: é o prazo padrão em que um reembolso ou um chargeback ainda poderia chegar.
2. Saque mínimo: $25.
   Você pode sacar seu saldo disponível assim que ele chega a $25 — o mesmo limite que os afiliados da Wyra já usam hoje, via Stripe Connect. A Wyra nunca vê seus dados bancários; isso a Stripe cuida diretamente com você.
3. Aprovação manual antes que o dinheiro se mova.
   Cada lote de pagamento passa por uma revisão humana na Wyra antes que a transferência seja executada — hoje isso é igual para qualquer valor. A intenção da Wyra é que saques notavelmente grandes recebam um olhar mais atento antes de serem liberados (isso dá tempo para o próprio período de liquidação da Stripe terminar de se assentar, reduzindo o risco de pagar sua comissão pouco antes de um reembolso tardio chegar) — mas hoje isso é critério manual dentro dessa mesma revisão, não uma fórmula automática de "valor maior = espera mais longa" ainda codificada no sistema.

Instalação e especificação técnica

Esta seção é a referência completa — autenticação, endpoints, formatos exatos de request/response, e códigos de erro. Se você está integrando (ou se é um assistente de código lendo isto por um humano), isto é tudo o que você precisa.

O mínimo para começar

<!-- Tudo o que é preciso colar no seu site -->
<div id="wyra-rails" data-wyra-pubkey="wr_pub_live_SUA_CHAVE"></div>
<script src="https://wyraapp.com/rails/widget.js" async></script>

Atributos do widget (data-wyra-*)

Um success_url / cancel_url que não aponte para um domínio registrado na sua conta é ignorado silenciosamente e cai para uma página genérica da Wyra — é uma proteção real: uma chave pública vazada não pode ser usada para redirecionar um cliente que acabou de pagar para um site arbitrário.

Autenticação

Dois tipos de chave, com regras de exposição bem diferentes:

Envie sua chave como o header x-rails-key (recomendado — funciona em qualquer ambiente, incluindo builders low-code onde o header Authorization é incômodo de configurar), ou como Authorization: Bearer <sua-chave>.

Se você chama a partir do seu próprio backend (sem o widget), não precisa de mais nada:

Authorization: Bearer wr_sec_live_SUA_CHAVE_SECRETA

Se você chama a partir do navegador com o widget, viajam duas camadas de auth — o widget já cuida delas por você, você não precisa montá-las na mão: o par público do Supabase (da Wyra, não o seu) mais sua própria chave:

apikey: <chave anônima pública da Wyra — o widget.js já traz>
Authorization: Bearer <a mesma chave anônima>
x-rails-key: wr_pub_live_SUA_CHAVE_PUBLICA

Catálogo — GET /rails?action=catalog

Base: https://owvktacuqmlymszkrwxv.supabase.co/functions/v1/rails. Leitura pura, sem efeitos colaterais — qualquer chave ativa (pública ou secreta, ao vivo ou de teste) pode chamá-la. Os preços que ela retorna já incluem sua margem (partner_price_usd); nunca expõe o custo de atacado da Wyra.

GET /rails?action=catalog&product=recargas&country=MX

{
  "product": "recargas", "country": "MX",
  "operators": [{
    "wyra_operator_id": 100234,
    "operator_name": "Telcel Mexico",
    "is_bundle": false,
    "logo_url": "https://.../telcel.png",
    "brackets": [{
      "bracket_id": 3,
      "wyra_retail_usd": 20.65,
      "partner_price_usd": 22.72,
      "markup_usd": 2.07,
      "local_amount": 350, "currency_delivered": "MXN",
      "denomination_type": "fixed",
      "product_label": "Recarga de $350 MXN",
      "validity": null, "benefits": null
    }]
  }]
}

Exemplo ilustrativo com o formato real dos campos — um país traz vários operadores, cada um com várias denominações (brackets).

GET /rails?action=catalog&product=esim&country_code=ES

{
  "product": "esim", "country_code": "ES",
  "packages": [{
    "package_id": "6b6f6e5b-…", "name": "Espanha 20GB 30 dias",
    "country_code": "ES", "data_quantity": 20, "data_unit": "GB",
    "validity": 30, "validity_unit": "days", "unlimited": false,
    "wyra_retail_usd": 23.99, "partner_price_usd": 26.39, "markup_usd": 2.40
  }],
  "truncated": false
}

GET /rails?action=catalog&product=giftcard&country_iso=US&brand=amazon

{
  "product": "giftcard", "country_iso": "US",
  "cards": [{
    "catalog_id": "b21e4b0e-…", "brand": "Amazon", "category": "retail",
    "country_iso": "US", "face_value": 25, "face_currency": "USD",
    "logo_url": "https://.../amazon.png",
    "wyra_retail_usd": 25.00, "partner_price_usd": 27.50, "markup_usd": 2.50
  }],
  "truncated": false
}

O catálogo de gift cards só inclui marcas cujo canal de origem já está validado do lado da Wyra — o mesmo filtro de segurança que a própria loja da Wyra usa, não um diferente para a Rails.

Checkout — POST /rails?action=checkout-session

Cria a sessão de pagamento real (uma Stripe Checkout Session, na conta da Wyra) e a ordem pendente associada. Requer uma chave live e uma conta já aprovada para o modo ao vivo.

POST /rails?action=checkout-session
{
  "product": "recargas",
  "customer_email": "cliente@email.com",
  "wyra_operator_id": 100234, "bracket_id": 3, "country_iso": "MX",
  "recipient_phone": "5215512345678", "operator_name": "Telcel Mexico",
  "turnstile_token": "…",          // só obrigatório com chave pública (navegador)
  "success_url": "https://seunegocio.com/obrigado",
  "cancel_url": "https://seunegocio.com/recargas"
}

Comuns aos três: product, customer_email, e opcionalmente turnstile_token (obrigatório só se você chama com uma chave pública a partir do navegador — o widget já resolve isso sozinho), success_url, cancel_url.

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_…",
  "transaction_id": "b0e21c4a-…",   // esim retorna "order_id" em vez disso
  "wyra_retail_usd": 20.65, "markup_usd": 2.07, "partner_price_usd": 22.72
}

Um 200 é o sinal de sucesso — redirecione para checkout_url (mesma aba). Só as respostas de erro levam success:false.

{
  "ok": false, "success": false,
  "error_code": "destination_not_supported",
  "error": "Destination country not supported",
  "message": "Destination country not supported"
}

Códigos de erro mais comuns

Limites de uso

A camada por IP usa o mesmo mecanismo que protege recargas, eSIM e gift cards no wyraapp.com, mas com uma cota própria da Rails — um checkout feito no seu site não consome a cota de outro produto Wyra a partir desse mesmo IP, nem o contrário.

Um soluço de infraestrutura do lado da Wyra nunca bloqueia sua integração por engano: esses limites falham "abertos" — se algo interno não responde, sua solicitação segue em frente em vez de ser rejeitada.

Quem é a Wyra

A Wyra Technologies LLC já opera três linhas de produto reais, ao vivo, vendidas diretamente à diáspora latina nos Estados Unidos em wyraapp.com: recargas pré-pagas para mais de 140 países, eSIM de viagem, e gift cards digitais. A Wyra Rails não é um experimento à parte — é a mesma infraestrutura que já cobra, já entrega, e já cumpre, estendida para que você também possa usá-la. Quando seu widget mostra um preço, é o mesmo motor de preços que roda na própria loja da Wyra; quando seu cliente compra, é o mesmo webhook da Stripe e os mesmos sistemas de entrega que já processam cada venda da Wyra hoje.

Essa mesma estrutura legal — a isenção da FinCEN para pré-pago de circuito fechado — é o que torna possível que a Wyra Rails não exija nenhuma licença de você (veja a seção 5).

Velocidade

Não há uma rota separada, mais lenta, para uma venda que chega pela Rails. O catálogo é lido das mesmas tabelas de preços curados que o próprio wyraapp.com consulta — não existe um "feed de preços para parceiros" separado e potencialmente desatualizado. O checkout é uma sessão de Stripe Checkout real, o mesmo fluxo de um único redirecionamento que a Wyra já usa hoje para cada recarga, eSIM e gift card que vende diretamente. E a entrega — o SMS de confirmação, o QR da eSIM, o código da gift card — roda pelos mesmos webhooks que já atendem os clientes da Wyra ao vivo, sem modificação, sem colocar uma venda da Rails em uma fila separada nem tratá-la como de segunda classe.

Não publicamos um número em milissegundos aqui de propósito: preferimos descrever a arquitetura real (a mesma que já está em produção, servindo tráfego real) a inventar uma cifra que não possamos sustentar em toda condição de rede.

O caminho até o white-label completo

Sendo honestos sobre onde isso está hoje: os e-mails que o cliente de um parceiro recebe (o recibo da compra, o QR da eSIM, o código da gift card) saem com a marca da Wyra — não a sua. Essa é a fase atual, não a versão final. A versão completamente white-label (e-mails com a sua própria marca, e potencialmente um checkout com a sua própria identidade visual) está no roadmap, mas ainda não foi construída.

Há dois caminhos reais para desbloqueá-la — e ambos são política atual da Wyra, não uma garantia fixa para sempre:

Nenhum dos dois é uma promessa contratual gravada em pedra — são a intenção atual da Wyra, e os valores exatos podem ser ajustados. Se qualquer um dos dois caminhos te interessa, escreva para support@wyraapp.com e conversamos sobre o seu caso concreto.

Uma página hospedada, para um local físico sem site próprio

Isso é diferente do widget incorporável descrito nas seções anteriores, e diferente também do roadmap white-label da seção 10 — é uma terceira opção, menor, pensada para um caso bem específico: um negócio que não tem nenhum site próprio onde colar um widget — um quiosque, um balcão de remessas, um tablet parado no balcão esperando que um cliente toque a tela.

Para esse caso, em vez de pedir que você construa um site primeiro, a Wyra pode hospedar uma página só sua — mesmo catálogo, mesmo checkout, sem escrever uma linha de código — e você aponta o navegador do seu tablet ou balcão para essa URL. Solicite pelo seu painel assim que sua conta Rails estiver ativa, e hoje isso não tem custo.