@autra-io/react-native-card

SDK React Native para tokenização segura de cartões via página hospedada da Autra. Os dados do cartão nunca passam pelo seu app nem pelos seus servidores.

🌎 README.md (in English) (documentação completa) · Guias completos no portal do desenvolvedor

Por que usar

• Tokenização em página hospedada — o portador digita PAN/CVV em uma página hospedada pela Autra, dentro de uma WebView. Os dados do cartão nunca transitam pelo seu app ou backend, o que ajuda a reduzir seu escopo PCI DSS.
• WebView endurecida por padrão — HTTPS-only, allow-list de navegação, sem conteúdo misto, incognito, sem cache em disco, sem acesso a arquivos.
• Bridge de mensagens estrita — validação de origem e de schema em toda mensagem; onSuccess dispara no máximo uma vez.
• Tipado de ponta a ponta e zero dependências de runtime.

Instalação

npm install @autra-io/react-native-card react-native-webview
# iOS (React Native bare): cd ios && pod install
# Expo: npx expo install react-native-webview

Requisitos: React >= 18, React Native >= 0.72, react-native-webview >= 13 (peer dependency obrigatória). Expo: requer development build / expo prebuild (Expo Go não é suportado).

Início rápido

Passo 1 — Backend: criar uma sessão de cartão hospedada

As sessões são criadas no servidor, com suas credenciais de serviço Autra. Nunca chame esta API do app e nunca embuta credenciais no app.

// Seu backend (exemplo Node). Sandbox: https://api.sandbox.autra.io
// Produção: consulte o portal do desenvolvedor. <!-- PLACEHOLDER: URL produção -->
app.post('/card-sessions', async (_req, res) => {
  const response = await fetch('https://api.sandbox.autra.io/v1/acquiring/card-sessions', {
    method: 'POST',
    headers: {/* credenciais de serviço Autra — somente no servidor */},
  });
  const { hostedCardUrl } = await response.json();
  // hostedCardUrl é de curta duração e uso único — gere uma por tentativa.
  res.json({ hostedCardUrl });
});

Passo 2 — App: renderizar o formulário

import { useState } from 'react';
import { Button, View } from 'react-native';
import {
  AutraCardForm,
  type AutraCardTokenizedResult,
  type AutraCardError,
} from '@autra-io/react-native-card';

export function AdicionarCartaoScreen() {
  const [hostedCardUrl, setHostedCardUrl] = useState<string | null>(null);

  async function iniciarEntradaDeCartao() {
    // Peça ao SEU backend uma sessão nova (Passo 1). URLs são de uso único:
    // solicite uma nova a cada tentativa — nunca fixe ou reutilize.
    const response = await fetch('https://seu-backend.example.com/card-sessions', {
      method: 'POST',
    });
    const body = (await response.json()) as { hostedCardUrl: string };
    setHostedCardUrl(body.hostedCardUrl);
  }

  if (!hostedCardUrl) {
    return <Button title="Adicionar cartão" onPress={iniciarEntradaDeCartao} />;
  }

  return (
    <View style={{ flex: 1 }}>
      <AutraCardForm
        hostedCardUrl={hostedCardUrl}
        onReady={() => {
          // Página hospedada pronta — esconda seu indicador de carregamento.
        }}
        onSuccess={(result: AutraCardTokenizedResult) => {
          // Envie result.slugStoredCard ao seu backend e armazene lá.
          // O backend usa essa referência para cobranças futuras.
        }}
        onError={(error: AutraCardError) => {
          if (error.code === 'token_expired' || error.retryable) {
            // Sessões expiram rápido: crie uma NOVA sessão e tente de novo.
            setHostedCardUrl(null);
            return;
          }
          // Não recuperável: mostre uma mensagem amigável e reporte error.code.
        }}
        style={{ flex: 1 }}
      />
    </View>
  );
}

Códigos de erro (AutraCardError)

| Código | Significado | O que fazer | | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ | | configuration_error | hostedCardUrl inválida/não-HTTPS ou allowedOrigins vazio. | Corrigir a integração — não é erro do usuário. | | token_expired | Sessão expirada ou não autorizada. | Criar nova sessão e recarregar o formulário. | | tenant_mismatch | A sessão não pertence ao expectedTenantId informado (SDK ≥ 0.4.0). | Não prosseguir; garantir que a sessão foi criada para este tenant. | | message_origin_rejected | Mensagem/navegação de origem fora da allow-list. | Investigar; não enfraquecer allowedOrigins. | | message_invalid | Mensagem malformada da página hospedada. | Tentar com nova sessão; reportar requestId. | | validation_error | Dados do cartão rejeitados. | A própria página orienta o usuário. | | tokenization_failed | Falha de carregamento ou de tokenização. | Se retryable, tentar com nova sessão. |

Documentação completa

Referência completa da API, segurança & PCI, testes e troubleshooting: o README.md (em inglês) que acompanha este pacote.

Licença

Apache-2.0 — veja o arquivo LICENSE que acompanha este pacote.