> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Abra o checkout hospedado do Dodo Payments a partir de um app React Native em uma aba do navegador do sistema e obtenha um resultado tipado em uma única chamada.

<Info>
  Este é o SDK oficial de checkout do Dodo Payments para React Native, `@dodopayments/react-native-checkout`. Ele abre o checkout hospedado do Dodo em uma visualização de navegador nativa e retorna um resultado tipado. Observação: existe um pacote mais antigo e não relacionado chamado `dodopayments-react-native-sdk` (sem escopo), com uma API completamente diferente. Esta página documenta apenas o pacote oficial com escopo atual.
</Info>

<CardGroup cols={2}>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Crie o checkout\_url que este SDK abre a partir do seu backend.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Veja como isso se encaixa no fluxo completo de pagamento móvel.
  </Card>
</CardGroup>

O SDK do React Native é um wrapper fino de Turbo Module sobre os mesmos núcleos nativos em Swift e Kotlin. Ele abre `SFSafariViewController` no iOS e uma Chrome Custom Tab no Android, não armazena nenhuma chave de API e nunca chama a API do Dodo diretamente. Toda a lógica do checkout é executada no navegador; o SDK simplesmente gerencia o ciclo de vida da visualização e captura a URL de retorno.

<Warning>
  Este SDK requer **apenas a New Architecture**, React Native 0.76+, iOS 16+ e Android `minSdk` 24.
</Warning>

## Instalação

<Steps>
  <Step title="Install the Package">
    <Tabs>
      <Tab title="Android">
        O pacote é vinculado automaticamente e obtém `com.dodopayments.api:checkout-android` do Maven.

        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        ```

        Não é necessária nenhuma configuração adicional; a dependência nativa é resolvida automaticamente.
      </Tab>

      <Tab title="iOS">
        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        cd ios && pod install
        ```

        O núcleo Swift é incluído no pacote e instalado por meio do CocoaPods.
      </Tab>

      <Tab title="Expo">
        Apenas builds de desenvolvimento (não o Expo Go).

        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        npx expo install expo-build-properties
        ```

        Em seguida, configure o seu `app.json` (consulte Registrar um esquema de URL de callback abaixo).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Register a Callback URL Scheme">
    Seu app deve registrar um esquema de URL para receber a URL de retorno do checkout.

    <Tabs>
      <Tab title="Android (Gradle)">
        Em `android/app/build.gradle`:

        ```kotlin android/app/build.gradle theme={null}
        android {
            defaultConfig {
                manifestPlaceholders["dodoCallbackScheme"] = "myapp"
            }
        }
        ```

        Substitua `"myapp"` pelo esquema do seu app.
      </Tab>

      <Tab title="iOS (Info.plist)">
        Em `ios/YourApp/Info.plist`:

        ```xml Info.plist theme={null}
        <key>CFBundleURLTypes</key>
        <array>
          <dict>
            <key>CFBundleURLName</key>
            <string>myapp</string>
            <key>CFBundleURLSchemes</key>
            <array>
              <string>myapp</string>
            </array>
          </dict>
        </array>
        ```

        Você também pode adicionar isso pela interface **Info → URL Types** do Xcode.
      </Tab>

      <Tab title="Expo (both platforms)">
        Em `app.json`:

        ```json app.json theme={null}
        {
          "expo": {
            "plugins": [
              [
                "expo-build-properties",
                {
                  "android": {
                    "manifestPlaceholders": {
                      "dodoCallbackScheme": "myapp"
                    }
                  }
                }
              ]
            ],
            "ios": {
              "infoPlist": {
                "CFBundleURLTypes": [
                  {
                    "CFBundleURLSchemes": ["myapp"]
                  }
                ]
              }
            }
          }
        }
        ```

        <Warning>
          O pacote também inclui um plugin de configuração do Expo `@dodopayments/react-native-checkout`,
          mas atualmente ele não grava nenhum esquema de URL nem nenhum placeholder de manifesto.
          Adicioná-lo sozinho **não** registrará o esquema de callback — use a configuração
          `expo-build-properties` e `infoPlist` acima.
        </Warning>

        <Note>
          Reconstrua o projeto nativo depois de editar `app.json`:

          ```sh theme={null}
          npx expo prebuild --clean
          ```

          Isso funciona apenas com builds de desenvolvimento, não com o Expo Go.
        </Note>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Uso

```typescript theme={null}
import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}
```

## Encaminhamento da URL de retorno

O listener `Linking` é necessário para o tratamento da URL de retorno no iOS. No Android, `handleOpenURL` é uma operação no-op que resolve `false` porque o núcleo do Android gerencia o redirecionamento nativamente. É seguro registrar o listener incondicionalmente em ambas as plataformas.

```typescript theme={null}
import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});
```

## O significado do resultado

<Warning>
  `result.status` é uma indicação da UI, não uma prova de pagamento. Confirme cada pagamento a partir do seu backend, por meio do webhook `payment.succeeded` / `subscription.active`.
</Warning>

<ParamField body="status" type="CheckoutStatus" required>
  Um de `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
</ParamField>

<ParamField body="paymentId" type="string">
  Definido quando a URL de retorno incluía um. Exiba-o na UI, mas não o use para conceder acesso. Consulte Verificar o pagamento abaixo.
</ParamField>

<ParamField body="subscriptionId" type="string">
  Definido para checkouts de assinatura.
</ParamField>

<ParamField body="licenseKeys" type="string[]">
  Definido quando o checkout inclui produtos com chave de licença.
</ParamField>

<ParamField body="customerEmail" type="string">
  Definido quando o checkout captura um e-mail.
</ParamField>

<ParamField body="raw" type="Record<string, string>">
  Todos os parâmetros de consulta da URL de retorno, literalmente.
</ParamField>

## Verificar o pagamento

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    O Dodo Payments chama o seu backend quando um pagamento é bem-sucedido ou uma assinatura é ativada.
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Consulte `paymentId` usando a sua chave secreta para verificar o status diretamente.
  </Card>
</CardGroup>

Conceda acesso depois que um desses confirmar o pagamento, nunca com base apenas em `result.status`.

## Erros

`start` rejeita com um `CheckoutError` apenas em caso de uso incorreto ou falha da plataforma. Um pagamento cancelado ou recusado sempre é um resultado, nunca uma exceção.

* `INVALID_CHECKOUT_URL`: não é uma URL de sessão `checkout.dodopayments.com`.
* `INVALID_RETURN_URL`: não é uma URL absoluta válida.
* `ALREADY_IN_PROGRESS`: já existe um checkout em execução.
* `PLATFORM_ERROR`: falha inesperada da plataforma.

## Sessões abandonadas

Se o app ou o bundle JS for encerrado durante o checkout, a promise será perdida, mas a camada nativa manterá a sessão. Recupere-a na próxima montagem e faça a reconciliação com o seu backend.

```typescript theme={null}
import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}
```

## Relacionado

<CardGroup cols={2}>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    O mesmo contrato para Android, iOS e Flutter.
  </Card>

  <Card title="Expo Boilerplate" icon="layer-group" href="/developer-resources/expo-boilerplate">
    Um exemplo completo do Expo com integração de checkout.
  </Card>
</CardGroup>