Modelos, eventos e códigos de status do SDK Tap to Pay. Os nomes são os mesmos nas duas plataformas. No iOS, objetos Kotlin são acessados por .shared (por exemplo, TapFeeScreens.shared).
| Método | Descrição |
|---|
setup(data: SetupData) | Ativa o aparelho e cria a sessão ativa do lojista. Devolve um TapActivationResult. suspend no Android, async no iOS |
pay(input: TransactionData) | Inicia uma venda para o lojista da sessão ativa e devolve o fluxo de eventos (TapFlow de TransactionEvent) |
deactivate() | Desativa o aparelho. A próxima venda exige novo setup() |
cancelTransaction() | Obsoleto. Para cancelar, cancele a coleta do pay() |
| Campo | Tipo | Descrição |
|---|
document | String | CNPJ ou CPF do lojista |
activationCode | String | Código gerado pelo backend do parceiro na API CMA |
paymentProfileId | String | Perfil de pagamento do lojista |
accountId | String | Conta do lojista na Stone |
stoneCode | String | Código de afiliação do lojista |
credential | Credential | Credenciais Transacionais |
| Campo | Tipo | Descrição |
|---|
clientId | String | client_id das Credenciais Transacionais |
clientSecret | String | client_secret das Credenciais Transacionais |
| Campo | Tipo | Descrição |
|---|
stoneStatus | StoneStatus | "0000" (StoneStatus.SUCCESS) quando a ativação deu certo; outro código em caso de falha |
stoneCode | String? | Stone Code da ativação |
| Campo | Tipo | Obrig. | Descrição |
|---|
amount | Int | Sim | Valor em centavos (1000 = R$ 10,00) |
paymentMethod | PaymentMethod | Sim | CREDIT, DEBIT ou VOUCHER (Android) · .credit, .debit ou .voucher (iOS) |
installments | Int | Sim | Número de parcelas. 1 = à vista; maior que 1 = parcelado lojista (só crédito). Débito e voucher: sempre 1 |
softDescriptor | String | Sim | Texto na fatura do cliente. Passe "" se não usar |
A forma de pagamento e as parcelas finais são escolhidas pelo lojista na tela do SDK. Toda venda é autorização com captura. O lojista da venda é o da sessão ativa; não há campo de dono da transação.
O TransactionData não tem o campo metadata nesta versão do SDK. Para conciliar, guarde o transactionId e o initiatorTransactionKey do TransactionResult junto do pedido no seu sistema.
O SDK exibe todas as telas da venda, então o app só precisa tratar o OnResult, que é sempre o último evento do pay(). O fluxo também emite eventos internos de progresso, que podem ser ignorados.
| Campo | Tipo | Descrição |
|---|
result | StoneStatus | Status final. Sucesso é "0000" |
transactionResult | TransactionResult? | Dados da venda. Pode ser nulo se a venda falhou antes da autorização |
vendorResult | String? | Detalhe técnico para diagnóstico. Registre em log; não mostre ao lojista |
| Propriedade | Tipo | Descrição |
|---|
onPaymentMethodConfirmed | (TransactionData) -> Unit | Chamado quando o lojista confirma a forma de pagamento, antes da aproximação. Traz o TransactionData final; com repasse da taxa, o amount é maior que o enviado no pay() |
onSaleFinished | (TapSaleExit) -> Unit | Chamado quando o lojista sai da venda aprovada, logo antes do OnResult de sucesso |
| TapSaleExit (Kotlin) | Swift | Significado |
|---|
NEW_SALE | .newSale | O lojista tocou em "Fazer nova venda" |
CLOSE | .close | O lojista fechou a venda aprovada |
| Campo | Tipo | Descrição |
|---|
transactionId | String? | Identificador da venda na Stone. Guarde para consulta e conciliação |
initiatorTransactionKey | String? | Chave da venda gerada na origem. Guarde para conciliação |
acquirerTransactionId | String? | Identificador da venda no adquirente |
localTransactionId | String | Identificador gerado no aparelho |
operationId | String? | Identificador da operação |
status | String? | Status da venda |
responseCode | String? | Código de resposta da autorização |
message | String? | Mensagem do resultado |
authorizationCode | String? | Código de autorização da bandeira (vendas aprovadas) |
cardBrand | String? | Bandeira do cartão |
cardLastDigits | String? | Últimos dígitos do cartão |
applicationIdentifier | String? | AID da aplicação do cartão |
isPinless | Boolean? | true quando a venda foi feita sem PIN |
merchantName | String? | Nome do estabelecimento |
statementDescriptor | String? | Descrição na fatura do cliente |
createdAt / updatedAt | String? | Datas da venda (ISO 8601) |
StoneStatus traz code (String), message e detail. Dois status são iguais quando têm o mesmo code.
| Constante | Código | Uso |
|---|
StoneStatus.SUCCESS (Swift: ErrorStoneStatus.companion.SUCCESS) | 0000 | Operação concluída |
StoneStatus.UNKNOWN_ERROR | UNKNOWN | Erro sem classificação; veja o vendorResult |
Use o code para decidir o que fazer e a message para exibir ao lojista.
| Faixa | Origem |
|---|
3xx | Ativação do aparelho |
1000 – 10xx | Recusa do emissor do cartão |
5xxx | Conectividade |
7xxx | Leitura do cartão, aparelho e processamento |
91xx | Autorizador |
| Código | Nome | O que fazer |
|---|
302 | FAILED_ACTIVATE_TERMINAL | Ativação falhou. Peça um código novo e repita o setup(). Se persistir, confira credenciais, consentimento e ambiente |
305 | TERMINAL_ALREADY_ACTIVATED | O aparelho já está ativado |
307 | ACCOUNT_LINKING_CANCELLED | iOS: o lojista não aceitou os termos da Apple |
309 | ACCOUNT_LINKING_REQUIRES_ICLOUD_SIGN_IN | iOS: conecte o iCloud no aparelho |
312 | DEVICE_BANNED | Aparelho bloqueado. Fale com a Stone |
314 | INVALID_READER_TOKEN | iOS: no sandbox, o iPhone não está no ambiente de teste da Apple (veja iOS) |
315 | MERCHANT_BLOCKED | Lojista bloqueado. Fale com a Stone |
316 | MODEL_NOT_SUPPORTED | Modelo de aparelho não suportado |
331 / 332 | LOCATION_PERMISSION_MISSING / LOCATION_DISABLED | Android: peça a permissão de localização ou peça para ligar a localização |
5024 | NO_NETWORK_AVAILABLE | Sem internet |
7011 | OPERATION_CANCELLED_BY_USER | Venda cancelada. Nenhuma ação |
7013 / 7419 | NFC_NOT_TURNED_ON_ERROR / NFC_DISABLED | Ligue o NFC |
7143 | CTLS_MULTI_CARD_ERROR | Mais de um cartão no campo de leitura |
7410 | DEACTIVATED | O aparelho foi desativado. Refaça o setup() |
7412 / 7413 | TOTAL_ELAPSED_TIMEOUT / CARD_READ_TIMEOUT | Tempo esgotado. Tente de novo |
7417 | INSECURE_DEVICE | O aparelho não passou na validação de segurança (por exemplo, root ou opções de depuração) |
7418 | DEVICE_WITHOUT_NFC | Aparelho sem NFC |
| Cenário | Solução |
|---|
| Credenciais inválidas | Validar client_id / client_secret transacionais com a Stone |
activationCode expirado | Solicitar novo código ao backend |
| Consentimento não aceito | Aguardar o aceite do lojista antes de gerar o activationCode |
| Ambiente trocado | Conferir se a variante do SDK e o environment são do mesmo ambiente |
| Dispositivo incompatível | Testar em dispositivo com NFC (Android) ou iPhone compatível (iOS) |
| Sem internet | Verificar conectividade e repetir |
Se o pay() for chamado sem sessão ativa, o fluxo termina com OnResult de erro. Peça um código novo ao backend, faça o setup() e repita a venda.
| Tipo | Uso |
|---|
TapStoneCo / TapStoneCo.Builder (Swift: TapStoneCoBuilder) | Instância do SDK |
SetupData e Credential | Entrada do setup() |
TapActivationResult | Resultado do setup() |
TransactionData | Entrada do pay() |
TransactionEvent.OnResult | Resultado do pay() |
TapFeeScreens e TapSaleExit | Avisos opcionais da venda |
TransactionResult | Dados da venda |
StoneStatus (Swift: ErrorStoneStatus) | Status de qualquer operação |
Integração: Tap to Pay para Terceiros
Etapa 6 de 7