Guia de tokenização¶

OpenAPI: não publicado nesta versão do BCP.

Visão geral¶

Este guia é para implementadores que criam gerenciadores de pagamentos de tokenização. Isso define a API compartilhada, os requisitos de segurança e os critérios de conformidade que todos Seguem os manipuladores de tokenização.

Observação: Embora os exemplos neste guia usem credenciais de cartão, a tokenização padrões se aplicam a qualquer tipo de credencial sensível — contas bancárias, contas digitais carteiras, contas de fidelidade, etc. Requisitos de conformidade (por exemplo, PCI DSS para cartões) variam de acordo com o tipo de credencial.

Oferecemos uma série de exemplos para utilizar formas de tokenização no BCP:

Exemplo	Caso de uso
Tokenizer de processador (não incluído nesta versão BCP)	Business ou PSP executa tokenização e processamento
Platform Tokenizer (não incluído nesta versão BCP)	Plataforma tokeniza credenciais para empresas/PSPs
Manipulador de credenciais criptografadas (não incluído nesta versão do BCP)	Plataforma criptografa credenciais em vez de tokenizar

Conceitos Básicos¶

Fluxo de credenciais¶

Os manipuladores de tokenização transformam credenciais entre os formulários de origem e de checkout:text +-------------------------------------------------------------------------+ | Tokenization Payment Flow | +-------------------------------------------------------------------------+ | | | Platform has: Tokenizer Business receives: | | Source Credential --> /tokenize --> TokenCredential | | | | +-----------------+ +-------------------------+ | | | source_ | | checkout_ | | | | credentials | What goes IN | credentials | | | | |<--------------- | | | | | * card/fpan | | What comes OUT | | | | * card/dpan | ----->| * token | | | | | | | | | +-----------------+ +-------------------------+ | | | +-------------------------------------------------------------------------+Os manipuladores de tokenização aceitam credenciais de origem (por exemplo, cartão com FPAN) e produzir credenciais de checkout (por exemplo, tokens).

Ciclo de vida do token¶

Encadernação¶

Todas as solicitações de tokenização requerem um objeto binding que vincula o token a um contexto específico:

Campo	Obrigatório	Descrição
`checkout_id`	Sim	A sessão de checkout para a qual este token é válido
`identity`	Condicional	A identidade do participante à qual se vincular; obrigatório quando o chamador age em nome de outro participante

O tokenizer DEVE verificar as correspondências de ligação em /detokenize. Consulte Esquema de ligação.

OpenAPI¶

Os manipuladores de tokenização implementam dois pontos de extremidade. Seu gerenciador PODE implementar um ou ambos, dependendo da sua arquitetura. Ou nenhum, como nosso criptografado exemplo de carga útil, que define seu próprio mecanismo para criptografar.

POST /tokenizar¶

Converte uma credencial bruta em um token vinculado a um checkout e uma identidade.

Quando implementar: Sempre, a menos que você seja um agente gerando tokens internamente.```json POST /tokenize Content-Type: application/json

{ "credential": { "type": "card", "card_number_type": "fpan", "number": "4111111111111111", "expiry_month": 12, "expiry_year": 2026, "cvc": "123" }, "binding": { "checkout_id": "abc123", "identity": { "access_token": "merchant_001" } } } **Resposta:**json { "token": "tok_abc123xyz789" } ```### POST /destokenizar

Retorna a credencial original de um token válido. A vinculação deve corresponder.

Quando implementar: Sempre, a menos que você combine a destokenização com processamento (ver exemplo PSP).```json POST /detokenize Content-Type: application/json Authorization: Bearer {caller_access_token}

{ "token": "tok_abc123xyz789", "binding": { "checkout_id": "abc123" } } **Resposta:**json { "type": "card", "card_number_type": "fpan", "number": "4111111111111111", "expiry_month": 12, "expiry_year": 2026, "cvc": "123" } ``**Observação:**binding.identity` é omitido quando o chamador autenticado é o alvo vinculativo. Inclua-o ao agir em nome de outro participante (por exemplo, Destokenização de PSP para empresas).

A especificação OpenAPI para manipuladores de tokenização não está publicada neste BCP lançamento.

Requisitos de segurança¶

Requisito	Descrição
Encadernação necessária	As credenciais DEVEM ser vinculadas a `checkout_id` e ao participante `identity` para evitar reutilização
Vinculação verificada	O tokenizer DEVE verificar as correspondências de ligação antes de retornar as credenciais
Criptograficamente aleatório	Use geradores aleatórios seguros; os tokens devem ser indecifráveis
Comprimento suficiente	Mínimo de 128 bits de entropia
Não reversível	Não é possível derivar a credencial do token
Escopo	O token só deve funcionar com o seu tokenizer
Tempo limitado	Aplicar TTL apropriado ao caso de uso (normalmente de 5 a 30 minutos)
Preferencialmente de uso único	Invalidar após a primeira destokenização quando possível

Requisitos de especificação do manipulador¶

Ao publicar seu manipulador, seu documento de especificação DEVE incluir:

Requisito	Exemplo
Nome exclusivo do manipulador	`com.example.tokenization_payment` (formato DNS reverso)
URLs de endpoint	URLs base de produção e sandbox
Requisitos de autenticação	OAuth 2.0, chaves de API, etc.
Processo de integração	Como os participantes se cadastram e recebem identidades
Credenciais aceitas	Quais tipos de credenciais são aceitos para tokenização
Política de ciclo de vida de token	Uso único, TTL ou escopo de sessão
Reconhecimentos de segurança	Os participantes que recebem credenciais brutas devem aceitar a responsabilidade

Exemplo de esboço de especificação```markdown¶

Handler Name: com.acme.tokenization_payment OpenAPI: not published in this BCP release.

Environment	Base URL
Production	`https://api.acme.com/ucp`
Sandbox	`https://sandbox.api.acme.com/ucp`

Supported Instruments:

Instrument	Source Credentials	Checkout Credentials
`card`	`card` (fpan, network_token)	`token`

Token Lifecycle: Single-use (invalidated after detokenization)

Authentication: OAuth 2.0 client credentials

Onboarding: Register at portal.acme.com. Businesses receive access_token for handler identity. ```---

Lista de verificação de conformidade¶

Um manipulador de tokenizador estará em conformidade com esse padrão se:

[] Publica uma especificação de manipulador em uma URL estável com um DNS reverso exclusivo handler_name
Implementa /tokenize e/ou /detokenize pela OpenAPI
[] Define requisitos de autenticação e integração
[] Documenta a transformação de credenciais entre os formulários de origem e de checkout
Produz tokens compatíveis com o esquema TokenCredential
[] Especifica a política de ciclo de vida do token (TTL, uso único, etc.)
[] Requer binding com checkout_id em solicitações de tokenização
Utiliza PaymentIdentity para identificação do participante
[] Verifica correspondências de binding em solicitações de destokenização
[] Requer confirmações de segurança dos participantes que recebem credenciais brutas

Referências¶

Recurso	URL
OpenAPI de tokenização	Não publicado neste comunicado do BCP.
Esquema de Identidade	esquemas/shopping/types/payment_identity.json
Esquema de ligação	esquemas/shopping/types/binding.json
Esquema de credenciais de token	esquemas/shopping/types/token_credential.json
Esquema de instrumento de cartão	schemas/shopping/types/card_payment_instrument.json

Veja também¶

Manipulador de credenciais criptografadas (não incluído nesta versão do BCP) — Padrão alternativo usando criptografia em vez de tokenizar/destokenizar viagens de ida e volta
AP2 Mandates Extension — Adicionar prova criptográfica do contrato de checkout para verificação PSP