Setup do SDK

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:

3.1 — 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

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

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
        })
    }
}

3.2 — 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

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

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).

3.3 — 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

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.

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

3.5 — 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

tapStoneCo.deactivate()

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

3.6 — Fluxo resumido

Veja também

Integração: Tap to Pay para Terceiros
Etapa 3 de 7