Consentimento e Ativação

Token Gerencial, Consentimento e CMA API — o fluxo completo do backend do parceiro.

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

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.

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

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

Autenticação OAuth2 com as Credenciais Gerenciais. O token é usado como Bearer nas chamadas de Consentimento, CMA API e Version Codes.

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}

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:

{
    "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

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.

POST {base_url}/v1/auth/consents
Authorization: Bearer {token_gerencial}
Content-Type: application/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`

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:

{
    "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.

{
    "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)

Com o consentimento aceito, o backend gera o activationCode que será usado no setup do SDK e o entrega ao app.

POST {base_url}/v1/cma/partners/codes
Authorization: Bearer {token_gerencial}
Content-Type: application/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):

{
    "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

O contrato entre o app e o backend é do parceiro. Uma forma segura:

POST /tap/activation-code
Authorization: Bearer <token de sessão do usuário do parceiro>

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

Tap to Pay para TerceirosVisão geral, requisitos e credenciais.Setup do SDKCriação do SDK e setup no dispositivo com o activationCode.Referência de APIErros de setup e de transação.

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

Etapa anteriorVisão geral Próxima etapaSetup do SDK