COMECE AGORA

Documentação e API da rostopay

A rostopay é uma infraestrutura de pagamento biométrico não custodial. Seu comprador autoriza com o rosto ao vivo no próprio aparelho; o dinheiro se move de banco a banco via Pix e cai na conta do lojista como um pagamento instantâneo em dinheiro. Você nunca lida com número de cartão, escopo PCI ou chargeback.

Início rápido →Aceite seu primeiro pagamento facial em 4 linhas. Links de pagamento →Nenhum código — envie uma URL e receba. Referência de API →Cobranças, reembolsos, erros — REST + JSON.

Início rápido — 4 linhas

Adicione o SDK ao seu checkout. O botão rosto-pay aparece junto aos seus outros meios de pagamento e cuida de todo o fluxo facial.

<!-- 1. carregar o SDK -->
<script src="https://js.rostopay.com/v3"></script>

<!-- 2. adicione o botão junto dos seus meios de pagamento -->
<rosto-pay key="pk_live_oak_ember_112" amount="23.40" currency="brl"></rosto-pay>

É só isso. Em caso de sucesso, o comprador vê o comprovante, você recebe um webhook charge.settled, e o dinheiro já está na sua conta — em dinheiro, definitivo, sem bandeiras de cartão no meio do caminho.

Modo de teste e rostos de teste

Chaves com o prefixo pk_test_ executam todo o fluxo em sandbox — sem bancos reais, sem rostos reais. Use as personas de teste integradas para testar cada resultado:

PERSONA DE TESTERESULTADO

face_okAutoriza e liquida instantaneamente

face_no_livenessFalha na prova de vida — liveness_failed

face_deepfakeRejeitado pelo antideepfake — synthetic_media

face_insufficientBanco recusa — insufficient_funds

face_slow_bankLiquida após 30 s — testa sua interface de pendência

Cobranças de teste aparecem no painel com o selo TEST e são ancoradas na testnet Polygon Amoy.

ACEITE PAGAMENTOS

SDK de checkout

O web component aceita atributos de valor, metadados e callbacks. Eventos são disparados a cada etapa para que sua interface possa reagir.

<rosto-pay key="pk_live_…" amount="23.40" order-id="ord_5512"
  delivery-address="sync" <!-- o endereço salvo do comprador é usado no pedido -->
  discount="2%">        <!-- repasse ao comprador a economia da taxa de cartão -->
</rosto-pay>

document.querySelector('rosto-pay')
  .addEventListener('settled', (e) => {
    // e.detail = { charge_id, proof_hash, amount, receipt_url }
  });

authorized settled failed cancelled

Links de pagamento — sem código

Um link de pagamento é uma URL que é um checkout. Crie um no painel (ou via API), envie por SMS, e-mail, WhatsApp ou um QR — o comprador abre, olha e você recebe. Perfeito para faturas, serviços, venda social e quem não tem site.

POST /v1/payment_links
{ "amount": "185.00", "description": "Kitchen sink repair — final" }

// → 201 Created
{ "url": "https://pay.rostopay.com/l/hartley-448/k7Q2", "status": "active" }

Os links podem ser de uso único ou reutilizáveis, ter uma validade, e liquidam exatamente como as cobranças do SDK — dinheiro instantâneo, webhook, comprovante verificável.

QR e presencial

Todo link de pagamento vira um QR no painel — imprima no balcão, no ticket do manobrista ou no display da mesa. Para pontos de venda fixos, o terminal do lojista mostra um QR rotativo vinculado ao seu caixa. O comprador escaneia com a câmera do celular; o fluxo facial roda no aparelho dele, então você não precisa de nenhum hardware.

Já usa Shopify, WooCommerce, Square, Toast ou outra plataforma? A rostopay se integra sem código — veja todas as Integrações →

REFERÊNCIA DE API

Autenticação

A API é REST sobre HTTPS em api.rostopay.com. Autentique com sua chave secreta como bearer token. Chaves secretas (sk_live_…) ficam apenas no seu servidor — a chave pública do SDK não consegue movimentar dinheiro.

curl https://api.rostopay.com/v1/charges \
  -H "Authorization: Bearer sk_live_…"

Cobranças

Uma cobrança (charge) é criada pelo SDK ou por um link de pagamento quando o rosto do comprador autoriza. Você as lê; não as cria pelo servidor — apenas um rosto ao vivo pode.

GET /v1/charges/ch_8C31FB09

{
  "id": "ch_8C31FB09",
  "status": "settled",          // authorized | settled | failed | refunded
  "amount": "23.40",
  "net": "23.15",               // taxa fixa, sem percentual
  "rail": "pix",
  "proof_hash": "0x8C31…FB09",  // verify.rostopay.com
  "order_id": "ord_5512",
  "created": "2026-07-21T09:41:22Z"
}

Liste com GET /v1/charges?from=…&to=… — com paginação por cursor, filtrável por status, local e caixa.

Reembolsos

Total ou parcial. O reembolso é uma nova transferência banco a banco de volta ao comprador, encadeada ao proof hash original — então também é publicamente verificável.

POST /v1/refunds
{ "charge": "ch_8C31FB09", "amount": "23.40", "reason": "requested_by_customer" }

Erros

Códigos HTTP padrão mais um corpo legível por máquina. Os que você realmente vai ver:

CÓDIGOSIGNIFICADO

liveness_failedComprador não passou na prova de vida — nunca cobrado

synthetic_mediaO antideepfake rejeitou a captura

insufficient_fundsBanco do comprador recusou — nada foi movimentado

bank_unavailableInstabilidade no trilho de pagamento — tente novamente com a mesma chave de idempotência

rate_limited429 — aguarde conforme o Retry-After

WEBHOOKS

Eventos

Cadastre um endpoint no painel e a rostopay envia POST com JSON assinado a cada mudança de estado:

charge.authorized charge.settled charge.failed refund.settled invoice.paid payout.reconciled

{
  "type": "charge.settled",
  "data": { "id": "ch_8C31FB09", "amount": "23.40", "proof_hash": "0x8C31…FB09" }
}

Assinaturas e novas tentativas

Todo envio traz um cabeçalho Rosto-Signature (HMAC-SHA256 do corpo com o segredo do seu endpoint). Verifique-o antes de confiar no payload. Envios com falha tentam novamente com backoff exponencial por 72 horas; os eventos são idempotentes por event_id.

const ok = rostopay.webhooks.verify(req.body, req.headers['rosto-signature'], endpointSecret);

RECURSOS

Bibliotecas e SDKs

Node.js

npm i rostopay

Python

pip install rostopay

Ruby

gem install rostopay

PHP

composer require rostopay

go get rostopay.com/go

iOS / Android

kits nativos de checkout

Está tudo funcionando?

Status em tempo real da API, SDK, trilhos de pagamento, webhooks e verify.

Status do sistema →

Changelog e versões

A API tem versões por data — fixe a sua com o cabeçalho Rosto-Version. Mudanças que quebram compatibilidade só saem em novas versões; o SDK se atualiza automaticamente dentro de uma major.

SDK v3.4

15 jul 2026

NOVODetecção de padrão de coerção ativada por padrão; novo evento cancelled; botão renderiza 40% mais rápido em Android de entrada.

API 2026-06-01

01 jun 2026

NOVOFaturas e orçamentos imutáveis (/v1/invoices, /v1/estimates) com status público; webhook invoice.paid.

SDK v3.3

22 abr 2026

ALTERADOdelivery-address="sync" agora retorna um objeto de endereço estruturado; o formato de texto legado ainda é aceito na v3.

API 2026-03-01

01 mar 2026

NOVOAPI de links de pagamento; endpoints de QR por caixa; paginação por cursor em todas as chamadas de listagem. DESCONTINUADO paginação page= (removida em 01/01/2027).

SDK v3.0

09 jan 2026

MUDANÇA CRÍTICAWeb component substitui o embed via iframe da v2; instalação em uma linha; v2 com suporte até janeiro de 2027.