--- title: "Referência de API" url: "https://devcenter.stone.com.br/tap-to-pay-reference" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~UmVmZXLDqm5jaWEgZGUgQVBJ,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii90YXAtdG8tcGF5LXJlZmVyZW5jZSI,s_t_Ai3v4iY_oLi9O1.png" --- # Referência de API Modelos de dados, eventos, status e erros do SDK Tap to Pay. 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étodos do TapStoneCo](#métodos-do-tapstoneco) | 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() | ### [SetupData — entrada do setup()](#setupdata-entrada-do-setup) | 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 | ### [Credential](#credential) | Campo | Tipo | Descrição | | :----------- | :----- | :------------------------------------------ | | clientId | String | client_id das Credenciais Transacionais | | clientSecret | String | client_secret das Credenciais Transacionais | ### [TapActivationResult — resultado do setup()](#tapactivationresult-resultado-do-setup) | 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 | ### [TransactionData — entrada do pay()](#transactiondata-entrada-do-pay) | 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. Importante 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. ### [TransactionEvent — resultado do pay()](#transactionevent-resultado-do-pay) 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. ### [OnResult — resultado final](#onresult-resultado-final) | 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 | ### [TapFeeScreens — avisos opcionais da venda](#tapfeescreens-avisos-opcionais-da-venda) | 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 | ### [TransactionResult](#transactionresult) | 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](#stonestatus) `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. #### [Faixas de código](#faixas-de-código) | 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ódigos mais comuns](#códigos-mais-comuns) | 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 | ### [Tratamento de erros — Setup](#tratamento-de-erros-setup) | 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 | ### [Sessão ausente](#sessão-ausente) 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. ### [Referência rápida](#referência-rápida) | 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 | ## [Veja também](#veja-também) [**Android**Onde TransactionData e TransactionEvent são usados.](https://devcenter.stone.com.br/tap-to-pay-android)[**iOS**A mesma referência aplicada em Swift.](https://devcenter.stone.com.br/tap-to-pay-ios)[**Setup do SDK**TapActivationResult é o retorno do setup().](https://devcenter.stone.com.br/tap-to-pay-sdk-setup) --- **Integração: [Tap to Pay para Terceiros](https://devcenter.stone.com.br/tap-to-pay)** Etapa 6 de 7 [**Etapa anterior**iOS](https://devcenter.stone.com.br/tap-to-pay-ios)[**Próxima etapa**Version Codes (Android)](https://devcenter.stone.com.br/tap-to-pay-version-codes) 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.