---
title: "Setup do SDK"
url: "https://devcenter.stone.com.br/tap-to-pay-sdk-setup"
image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_Setup+do+SDK,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii90YXAtdG8tcGF5LXNkay1zZXR1cCI,s_gQWM5CG2EBxHI41m.png"
---

# Setup do SDK

Criação do SDK, setup com SetupData, sessão ativa e telas da venda.

O setup ativa a sessão do SDK no dispositivo para o lojista. A partir da v3.0, a ativação usa um único modelo, o `SetupData`, para qualquer integração:

| Campo            | Origem                                                              |
| :--------------- | :------------------------------------------------------------------ |
| document         | CNPJ ou CPF do lojista                                              |
| activationCode   | Gerado pelo backend na ativação (ver Consentimento e Ativação)      |
| stoneCode        | Código de afiliação do lojista                                      |
| paymentProfileId | Perfil de pagamento do lojista                                      |
| accountId        | Conta do lojista na Stone                                           |
| credential       | Credential(clientId, clientSecret) com as Credenciais Transacionais |

## [3.1 — Criação do SDK (uma única vez, na startup)](#_31-criação-do-sdk-uma-única-vez-na-startup)

Crie uma instância do `TapStoneCo` na inicialização do app e reutilize em todo o app.

Android — classe Application

```kotlin
class MainApplication : Application() {

    lateinit var tapStoneCo: TapStoneCo
        private set

    override fun onCreate() {
        super.onCreate()
        // A tela de PIN roda num processo separado: nele, não inicialize nada.
        if (TapSdk.shouldIgnoreApplicationOnCreate()) return

        tapStoneCo = TapStoneCo.Builder(this).build {
            environment = Environment.SDX        // Environment.PRODUCTION em produção
        }
    }
}
```

iOS

```swift
import TapCore

final class TapService {
    static let shared = TapService()
    let sdk: TapStoneCo

    private init() {
        sdk = TapStoneCoBuilder(application: IosContext()).build(block: { builder in
            builder.environment = TapCore.Environment.sdx   // .production em produção
        })
    }
}
```

| Opção do Builder | Padrão                     | Descrição                        |
| :--------------- | :------------------------- | :------------------------------- |
| environment      | conforme a variante do SDK | SDX (sandbox) ou PRODUCTION      |
| timeouts         | padrão do SDK              | Tempo máximo de leitura e de PIN |
| pinpad           | padrão Stone               | Estilo da tela de PIN            |

## [3.2 — Setup (ativação do dispositivo)](#_32-setup-ativação-do-dispositivo)

Peça o `activationCode` ao backend e chame o `setup()` logo em seguida, com um `SetupData`. O SDK identifica o tipo de integração sozinho; o app não informa instituição nem tipo de dono da sessão.

Android

```kotlin
val activationCode = backend.fetchActivationCode()   // nunca chame a CMA API do app

val result = tapStoneCo.setup(
    SetupData(
        document = document,
        activationCode = activationCode,
        paymentProfileId = paymentProfileId,
        accountId = accountId,
        stoneCode = stoneCode,
        credential = Credential(
            clientId = transactionalClientId,        // Credenciais Transacionais
            clientSecret = transactionalClientSecret,
        ),
    )
)

if (result.stoneStatus == StoneStatus.SUCCESS) {
    // sessão ativa, pronto para transacionar
} else {
    val status = result.stoneStatus
    Log.e("TapStoneCo", "Setup failed [${status.code}] ${status.message}")
}
```

iOS

```swift
let activationCode = try await backend.fetchActivationCode()

let setupData = SetupData(
    document: document,
    activationCode: activationCode,
    paymentProfileId: paymentProfileId,
    accountId: accountId,
    stoneCode: stoneCode,
    credential: Credential(
        clientId: transactionalClientId,             // Credenciais Transacionais
        clientSecret: transactionalClientSecret
    )
)
let result = try await TapService.shared.sdk.setup(data: setupData)

if result.stoneStatus == ErrorStoneStatus.companion.SUCCESS {
    // sessão ativa, pronto para transacionar
} else {
    print("Setup failed [\(result.stoneStatus.code)] \(result.stoneStatus.message)")
}
```

O `setup()` é assíncrono (`suspend` no Android, `async` no iOS). O retorno é um `TapActivationResult`; sucesso é o código `"0000"`.

No iOS, a primeira ativação do aparelho pede ao lojista que aceite os termos do Tap to Pay on iPhone com a conta Apple dele (veja [iOS](https://devcenter.stone.com.br/tap-to-pay-ios)).

## [3.3 — Sessão ativa](#_33-sessão-ativa)

O `setup()` cria a sessão ativa do lojista. O SDK guarda os dados do lojista dessa sessão (o contexto do lojista) e os usa em todas as vendas. Por isso o `pay()` não recebe mais o dono da transação: basta chamar `pay()` depois de um `setup()` bem-sucedido. Não é preciso chamar o `setup()` antes de cada transação.

Gere um novo `activationCode` e refaça o `setup()` quando:

-   o lojista ativar o Tap pela primeira vez no dispositivo;
-   o app for reinstalado ou os dados do app forem apagados;
-   o lojista do dispositivo mudar (depois do `deactivate()`);
-   a venda terminar sem sessão ativa ou com `7410` (`DEACTIVATED`).

## [3.4 — Telas da venda](#_34-telas-da-venda)

O SDK exibe todas as telas da venda. O app não desenha nenhuma tela de pagamento e não precisa tratar eventos de leitura do cartão: ele chama `pay()` com o valor e recebe o resultado final.

Durante o `pay()`, o SDK mostra, nesta ordem:

1.  **Forma de pagamento:** o lojista escolhe crédito, débito ou voucher, as parcelas e, se houver, o repasse da taxa ao cliente.
2.  **Aproximação e PIN:** no Android, a tela de aproximação e a tela segura de PIN do SDK; no iPhone, a tela do Tap to Pay da Apple.
3.  **Processamento e erros:** em caso de erro, o lojista pode tentar de novo sem sair da venda.
4.  **Venda aprovada e comprovante:** o lojista pode enviar o comprovante ao cliente e escolher entre fazer uma nova venda ou fechar.

O `pay()` só emite o `OnResult` quando o lojista termina a venda: sucesso ao sair da venda aprovada ou do comprovante, cancelamento (`7011`) se ele desistir na forma de pagamento, ou o erro que ele fechou.

Importante

Mantenha a coleta do `pay()` ativa até o `OnResult`. Se ela for cancelada junto com a tela do app, o SDK fecha as telas e o resultado da venda se perde.

### [Avisos opcionais do SDK](#avisos-opcionais-do-sdk)

| Callback                               | Quando é chamado                                                          | Para que serve                                                                   |
| :------------------------------------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------- |
| TapFeeScreens.onPaymentMethodConfirmed | Quando o lojista confirma a forma de pagamento, antes da aproximação      | Recebe o TransactionData final. Com repasse da taxa, o amount é maior que o valor enviado no pay(); use este valor no seu registro e na conciliação |
| TapFeeScreens.onSaleFinished           | Quando o lojista sai da venda aprovada, logo antes do OnResult de sucesso | Diz por onde ele saiu: NEW_SALE ("Fazer nova venda") ou CLOSE (fechar). Use para voltar à tela de valor ou à home do app |

## [3.5 — Logout](#_35-logout)

Encerra a sessão do SDK no dispositivo. A chamada é a mesma em Android e iOS, então não há necessidade de blocos de código separados por plataforma.

Android e iOS

```kotlin
tapStoneCo.deactivate()
```

Depois do `deactivate()`, a próxima venda exige um novo `setup()` com um `activationCode` novo.

## [3.6 — Fluxo resumido](#_36-fluxo-resumido)

| Fase                        | Quando                                                           | O que fazer                                                                      |
| :-------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| 1 — Inicialização do app    | Uma vez, na startup                                              | Criar o SDK com TapStoneCo.Builder(app).build { ... }                            |
| 2 — Ativação do dispositivo | Primeiro uso, reinstalação, troca de lojista ou venda sem sessão | Obter o activationCode via backend do parceiro e chamar setup(SetupData(...)). Se result.stoneStatus for SUCCESS, a sessão está ativa; senão, trate o erro |
| 3 — A cada transação        | Em cada venda                                                    | Chamar pay(TransactionData(...)); o SDK exibe as telas da venda. Trate o OnResult ao fim da venda: em caso de sucesso, a venda está concluída. Sem sessão ou com 7410, volte à fase 2 |

## [Veja também](#veja-também)

[**Consentimento e Ativação**De onde vem o activationCode usado aqui.](https://devcenter.stone.com.br/tap-to-pay-consent-activation)[**Android**Configuração completa e exemplo de transação.](https://devcenter.stone.com.br/tap-to-pay-android)[**iOS**Configuração completa e exemplo de transação.](https://devcenter.stone.com.br/tap-to-pay-ios)

---

**Integração: [Tap to Pay para Terceiros](https://devcenter.stone.com.br/tap-to-pay)**  
Etapa 3 de 7

[**Etapa anterior**Consentimento e Ativação](https://devcenter.stone.com.br/tap-to-pay-consent-activation)[**Próxima etapa**Android](https://devcenter.stone.com.br/tap-to-pay-android)

Siga a Stone nas redes sociais

[](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ)

© Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57

Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP

Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.