--- title: "Consentimento e Ativação" url: "https://devcenter.stone.com.br/tap-to-pay-consent-activation" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~Q29uc2VudGltZW50byBlIEF0aXZhw6fDo28,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii90YXAtdG8tcGF5LWNvbnNlbnQtYWN0aXZhdGlvbiI,s_Wi15wxjzhYSkqOBI.png" --- # Consentimento e Ativação Token Gerencial, Consentimento e CMA API — o fluxo completo do backend do parceiro. ## [Fluxo de integração](#fluxo-de-integração) A integração acontece em três fases. As duas primeiras rodam no backend do parceiro, com as **Credenciais Gerenciais**; a terceira roda no app, com as **Credenciais Transacionais** (detalhada em [Setup do SDK](https://devcenter.stone.com.br/tap-to-pay-sdk-setup)). **FASE 1 · CONSENTIMENTO** Backend do parceiro · Credenciais Gerenciais Token Gerencial `POST /auth/realms/payments/oauth2/token` → Consentimento `POST /v1/auth/consents` `status: pending` → Aceite do lojista `notificação na webhookUrl` `(SDX: status accepted)` ↓ consentimento aceito **FASE 2 · ATIVAÇÃO TAP** Backend do parceiro · Credenciais Gerenciais Gera código `POST /v1/cma/partners/codes` `Bearer: Token Gerencial` → activationCode `TTL curto` `não armazenar` → Entrega ao app `via backend do parceiro` `(BFF recomendado)` ↓ activationCode **FASE 3 · SDK NO DISPOSITIVO** App · Credenciais Transacionais Criar o SDK `TapStoneCo.Builder` `uma vez, na startup` → setup() `SetupData: document,` `activationCode, stoneCode,` `credential (Transacionais)` → pay() `TransactionData` `telas do SDK → OnResult` Detalhes da Fase 3 em [Setup do SDK](https://devcenter.stone.com.br/tap-to-pay-sdk-setup). | Passo | Origem | Destino | Ação | | :---- | :------------------ | :------------------------ | :------------------------------------------------------------------------------- | | 1 | BFF do parceiro | Consent API (Stone) | Com o Token Gerencial, cria o consentimento informando afiliação e documento do lojista | | 2 | Consent API (Stone) | BFF do parceiro | Notifica na webhookUrl que o lojista aceitou o consentimento | | 3 | App | BFF do parceiro | Solicita o activationCode | | 4 | BFF do parceiro | CMA API (Stone) | Gera o activationCode (POST /v1/cma/partners/codes) e o entrega ao app | | 5 | App | TapStoneCo (SDK) | Cria o SDK e executa o setup() com activationCode + Credenciais Transacionais | | 6 | TapStoneCo (SDK) | Endpoints Stone | Setup e transacional (interno ao SDK) | | 7 | CI/CD do parceiro | Version Codes API (Stone) | Registra os version codes do app Android (POST /v1/partners/versions) | No iOS, o parceiro também precisa do entitlement de Tap to Pay on iPhone na conta Apple dele. A aprovação da Apple é a etapa mais demorada da integração; comece por ela (veja [iOS](https://devcenter.stone.com.br/tap-to-pay-ios)). ## [Considerações](#considerações) - Realize testes extensivos em Sandbox antes de publicar. - Implemente logs adequados para monitoramento de consentimentos e transações. Nunca registre credenciais nem o activationCode. - Mantenha o SDK sempre na versão mais recente indicada pela Stone. - O activationCode tem TTL curto — solicite-o apenas no momento do setup e não o armazene. ## [Token Gerencial](#token-gerencial) Autenticação OAuth2 com as Credenciais Gerenciais. O token é usado como Bearer nas chamadas de Consentimento, CMA API e Version Codes. ```text POST {base_url}/auth/realms/payments/oauth2/token Content-Type: application/x-www-form-urlencoded ``` | Parâmetro | Valor | | :------------ | :------------------------ | | grant_type | client_credentials | | client_id | {client_id_gerencial} | | client_secret | {client_secret_gerencial} | ```bash curl --request POST \ --url https://sdx.api.stone.com.br/auth/realms/payments/oauth2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data client_id={client_id_gerencial} \ --data client_secret={client_secret_gerencial} ``` Response: ```json { "access_token": "eyJraWQiOiJhcm9naml0SGQ3YUpndDVoc2hU...", "expires_in": 86400, "token_type": "Bearer" } ``` Guarde o token em cache até perto do `expires_in`. Se uma chamada responder `401`, gere outro token e repita a chamada uma vez. ## [Consentimento](#consentimento) Solicita ao lojista permissão para que o parceiro transacione em sua afiliação. O consentimento é criado com status `pending` e a Stone notifica a `webhookUrl` quando o lojista aceitar. ```text POST {base_url}/v1/auth/consents Authorization: Bearer {token_gerencial} Content-Type: application/json ``` ```json { "document": "{documento_lojista}", "webhookUrl": "{webhook_url}", "affiliationId": "{affiliation_id_lojista}", "type": "partner_tap_trx", "clientId": "{client_id_transacional}", "resources": ["TRANSACTIONAL"] } ``` | Campo | Tipo | Descrição | | :------------ | :----- | :------------------------------------------------------------------------------- | | document | string | CNPJ ou CPF do lojista | | webhookUrl | string | Obrigatório. URL do parceiro que recebe a notificação de aceite | | affiliationId | string | Obrigatório. Código de afiliação do lojista na Stone | | type | string | Valor fixo em sandbox: partner_tap_trx. Em produção, o valor é informado pela Stone | | clientId | string | client_id das Credenciais Transacionais | | resources | string | Valor fixo em sandbox: "TRANSACTIONAL". Em produção, o valor é informado pela Stone | ### [Opções de `resources`](#opções-de-resources) | Scope | Name | | :---------------------------------- | :----------------- | | consent.s2s/all:rw | TOTAL | | consent.s2s/financial:r | FINANCIAL_READ | | consent.s2s/financial:rw | FINANCIAL | | consent.s2s/marketplace:r | MARKETPLACE_READ | | consent.s2s/marketplace:rw | MARKETPLACE | | consent.s2s/payments.conciliation:r | CONCILIATION | | consent.s2s/transactional:r | TRANSACTIONAL_READ | | consent.s2s/transactional:rw | TRANSACTIONAL | Response: ```json { "id": "cons_6ab30476e2e4e507c615372d", "clientId": "{client_id_transacional}", "affiliationId": "{affiliation_id_lojista}", "type": "partner_tap_trx", "status": "pending", "authenticationType": "jwt", "webhookUrl": "{webhook_url}", "webhookSettingsId": "hookset_4b1nkM7i2yiJZlmp", "document": "{documento_lojista}", "partnerName": "{nome_do_parceiro}", "resources": ["TRANSACTIONAL"], "createdAt": "2026-09-22T22:43:02Z", "updatedAt": "2026-09-22T22:43:02Z" } ``` Importante Somente em SDX (Sandbox): o status do consentimento precisa ser passado explicitamente como "accepted" no body da requisição, conforme o exemplo abaixo. Em produção, não envie o campo status. ```json { "document": "{documento_lojista}", "webhookUrl": "{webhook_url}", "affiliationId": "{affiliation_id_lojista}", "status": "accepted", "type": "partner_tap_trx", "clientId": "{client_id_transacional}", "resources": ["TRANSACTIONAL"] } ``` Guarde o estado do consentimento na sua base e só ofereça o Tap ao lojista depois do aceite. ## [Ativação do produto Tap (CMA API)](#ativação-do-produto-tap-cma-api) Com o consentimento aceito, o backend gera o `activationCode` que será usado no setup do SDK e o entrega ao app. ```text POST {base_url}/v1/cma/partners/codes Authorization: Bearer {token_gerencial} Content-Type: application/json ``` ```json { "type": "tap", "institution": "stone", "document": "{documento_lojista}", "stoneCode": "{affiliation_id_lojista}", "clientId": "{client_id_transacional}" } ``` | Campo | Tipo | Descrição | | :---------- | :----- | :------------------------------------------------------------------------------- | | type | string | Valor fixo: "tap" | | institution | string | Valor fixo: "stone" | | document | string | CNPJ ou CPF do lojista | | stoneCode | string | Código de afiliação do lojista (o mesmo informado como affiliationId no consentimento) | | clientId | string | client_id das Credenciais Transacionais | Response (200): ```json { "code": "KXGORLSVJNOZBTJE2SYIDZPUOI", "institution": "stone", "region": "br", "expiresAt": "2026-09-22T17:53:09.348183105Z" } ``` O backend retorna o `activationCode` (`code`) para o app. Importante O activationCode possui TTL muito curto. Utilize-o no setup() imediatamente após a geração. Não armazene — solicite um novo sempre que necessário. ## [Entrega do código ao app](#entrega-do-código-ao-app) O contrato entre o app e o backend é do parceiro. Uma forma segura: ```text POST /tap/activation-code Authorization: Bearer 200 OK { "activationCode": "KXGORLSVJNOZBTJE2SYIDZPUOI", "expiresAt": "2026-09-22T17:53:09Z" } ``` O app não envia `stoneCode` nem `document`. O backend valida a sessão do usuário, busca o lojista ligado a ele, confere se o consentimento está aceito e só então chama a CMA API. O app recebe o `stoneCode` e o `document` do lojista por um endpoint do parceiro, também resolvido pela sessão. ## [Veja também](#veja-também) [**Tap to Pay para Terceiros**Visão geral, requisitos e credenciais.](https://devcenter.stone.com.br/tap-to-pay)[**Setup do SDK**Criação do SDK e setup no dispositivo com o activationCode.](https://devcenter.stone.com.br/tap-to-pay-sdk-setup)[**Referência de API**Erros de setup e de transação.](https://devcenter.stone.com.br/tap-to-pay-reference) --- **Integração: [Tap to Pay para Terceiros](https://devcenter.stone.com.br/tap-to-pay)** Etapa 2 de 7 [**Etapa anterior**Visão geral](https://devcenter.stone.com.br/tap-to-pay)[**Próxima etapa**Setup do SDK](https://devcenter.stone.com.br/tap-to-pay-sdk-setup) 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.