Tokenização na Bandeira

A tokenização na bandeira substitui o número real do cartão (PAN) por um Network Token emitido diretamente pela bandeira.

Bandeiras suportadas

Visa
Mastercard

Na prática, você guarda apenas um token interno de 64 caracteres retornado pela Bempaggo. O token da bandeira e o criptograma de cada transação ficam sob responsabilidade da Bempaggo; você não precisa armazenar, transmitir ou gerenciar nenhuma informação sensível do cartão após a tokenização.

📘
Adquirente disponível
Hoje o fluxo de tokenização na bandeira está disponível via Rede (e.Rede). O modelo é assíncrono: após a solicitação, a Rede processa a emissão do token em background e notifica a Bempaggo, que por sua vez notifica você.

Como funciona

sequenceDiagram
    autonumber
    participant I as Integrador
    participant B as Bempaggo
    participant R as Rede

    I->>B: POST /cards/tokens/network<br/>(dados do cartão + notificationUrl)
    B-->>I: 202 Accepted<br/>token interno (PENDING)

    Note over B,R: Processamento assíncrono

    R-->>B: Evento de tokenização concluído
    B->>R: Consulta status do token
    R-->>B: Token ACTIVE ou FAILED

    B->>I: POST notificationUrl<br/>(ACTIVE ou FAILED)

    Note over I,B: Token pronto para uso

    I->>B: POST /orders/credit-card/authorize<br/>(networkToken.token)
    B->>R: Obtém criptograma + autoriza
    R-->>B: Autorização aprovada
    B-->>I: 201 Created

Passo a passo

Passo 1 — Solicitar a tokenização

Envie os dados do cartão do seu cliente junto com a URL onde você quer receber o resultado.

A Bempaggo responde imediatamente com 202 Accepted e um token interno em status PENDING. O processamento com a Rede acontece em segundo plano.

📘
Salve o token interno
O campo token retornado no 202 é a sua referência permanente — use-o para consultar o status, identificar o webhook e cobrar. Ele tem 64 caracteres e não é o PAN nem o token da bandeira.

Passo 2 — Aguardar o webhook

Quando a Rede confirmar (ou recusar) o token, a Bempaggo faz um POST na sua notificationUrl com o resultado.

Token aprovado:

{
  "token": "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "status": "ACTIVE",
  "bin": "544828",
  "lastFour": "0007",
  "brand": "Mastercard",
  "expiration": {
    "year": "2035",
    "month": "01"
  }
}

Token recusado:

{
  "token": "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "status": "FAILED",
  "bin": "544828",
  "lastFour": "0007",
  "brand": "Mastercard",
  "expiration": {
    "year": "2035",
    "month": "01"
  },
  "reason": "Tokenização recusada pela Rede"
}

Campo	Descrição
`token`	O mesmo token de 64 caracteres retornado no Passo 1.
`status`	`ACTIVE` — pronto para cobrar. `FAILED` — não foi possível tokenizar.
`bin`	Primeiros 6 dígitos do cartão.
`lastFour`	Últimos 4 dígitos do cartão.
`brand`	Bandeira detectada (`Mastercard`, `Visa`).
`expiration`	Validade do cartão informado na solicitação — não é a validade do token da bandeira.
`reason`	Motivo da recusa. Presente apenas quando `status = FAILED`.

🚧
Responda com HTTP 200
Seu endpoint deve responder 200 OK assim que receber o payload. Se não conseguir processar na hora, acuse o recebimento e processe de forma assíncrona. Caso sua URL esteja offline, você ainda pode consultar o status via GET a qualquer momento.

Passo 3 — Consultar o status (opcional)

Se precisar verificar o estado atual sem aguardar o webhook, consulte o token pelo endpoint de consulta passando o token interno recebido no Passo 1.

A resposta inclui os mesmos campos do webhook, acrescido do campo holder.name.

Passo 4 — Cobrar com o Network Token

Com o token em status ACTIVE, use-o diretamente na autorização do pedido. A Bempaggo busca o token da bandeira, gera o criptograma junto à Rede e autoriza a transação — você não precisa enviar PAN, CVV nem qualquer dado sensível do cartão.

{
  "orderReference": "ORDER-NT-20260601-001",
  "amount": 10000,
  "customer": {
    "name": "Carlos Melo",
    "document": "06219385993",
    "email": "[email protected]"
  },
  "payments": [
    {
      "paymentMethod": "CREDIT_CARD",
      "amount": 10000,
      "installments": 1,
      "networkToken": {
        "token": "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
      }
    }
  ]
}

🚧
Token deve estar ACTIVE
Tentativas de cobrança com token PENDING ou FAILED retornam 422 Unprocessable Entity.

Status do token

Status	O que significa	O que fazer
`PENDING`	Solicitação recebida. Processamento em andamento na Rede.	Aguarde o webhook. Não tente cobrar.
`ACTIVE`	Token emitido e pronto para uso.	Use em `payments[].networkToken.token` na cobrança.
`FAILED`	O adquirente recusou a emissão do token.	Verifique o campo `reason` no webhook.
`INACTIVE`	Token desativado administrativamente.	Solicite uma nova tokenização.

Testando no Sandbox

O seller precisa ter um estabelecimento com a Rede (e.Rede) habilitado para tokenização na bandeira. Sem isso, o endpoint retorna 422 indicando que não há estabelecimento compatível.

Use os cartões abaixo no ambiente sandbox da Rede:

Bandeira	Número do cartão	Validade	CVV
Mastercard	`5448280000000007`	`01/2035`	`123`
Visa	`4895370010000005`	`01/2035`	`123`

Perguntas frequentes

Preciso guardar o número do cartão do meu cliente?

Não. Guarde apenas o token interno (64 caracteres) retornado no Passo 1. A Bempaggo cuida do token da bandeira e do criptograma em cada transação.

Qual a diferença entre cardToken e networkToken na cobrança?

cardToken é a tokenização interna da Bempaggo (vault da plataforma). networkToken é a tokenização na bandeira via Rede. No mesmo pagamento, informe exatamente um dos dois — nunca os dois ao mesmo tempo.

Quanto tempo leva para o token ficar ACTIVE?

Com a Rede o processo é assíncrono. No sandbox pode levar até ~4 minutos. Em produção o tempo é menor, mas sempre dependa do webhook ou do GET para confirmar antes de cobrar.

Por que o campo expiration do webhook não muda quando o token fica ACTIVE?

Por design. A API expõe ao integrador a validade do cartão informada na tokenização. A validade do token da bandeira é usada apenas internamente pela Bempaggo ao gerar o criptograma.

Posso usar o mesmo token em múltiplas cobranças?

Sim. Um token ACTIVE pode ser reutilizado em quantas cobranças forem necessárias enquanto estiver ativo. A Bempaggo obtém o criptograma para cada transação de forma automática.

O que fazer se o status for FAILED?

Verifique o campo reason no webhook para entender o motivo. Você pode tentar novamente com outro cartão ou repetir a tokenização após um intervalo.

Minha notificationUrl precisa ser HTTPS?

Sim. A API exige que a notificationUrl comece com https://. Para testes, use webhook.site ou Pipedream.

O que acontece se minha notificationUrl estiver offline?

A Bempaggo tenta entregar a notificação. Se o seu servidor não responder, você pode consultar o status a qualquer momento via GET .../cards/tokens/network/{token}.