Como funciona PCI Proxy
Envie-nos os dados de cartão. Nós tokenizamo-los, guardamo-los no vault PCI DSS e devolvemos um token. Os seus sistemas nunca ficam com o número de cartão.
Envia
Nós custodiamos
PCI DSS · UE Encriptado aqui Recebe
O fluxo em 5 passos
Desde o momento em que o cliente introduz o cartão até ao token que guarda no seu sistema: é o que acontece passo a passo.
Dados de cartão recebidos
Checkout no site, chamada API ou formulário do call center
PCI Proxy intercepta
Recebemos os dados de cartão do payload HTTP antes de chegarem aos seus servidores
Tokenização
Encriptamos o número de cartão e geramos um token único
Vault seguro
O número de cartão permanece encriptado no vault PCI DSS Nível 1, apenas na UE
Token para si
Recebe o token e utiliza-o para pagamentos, subscrições ou reembolsos
O que acontece quando tokenizamos
Substituímos o número de cartão por um token. Nunca vê o cartão em texto simples nos seus sistemas. Estes são os três passos internos.
Passo
Detetamos os dados de cartão
Analisamos os pedidos recebidos e identificamos os números de cartão, em JSON, formulário ou multipart. Não precisa de alterar o seu código: basta ligar o fluxo e está pronto.
Passo
Criamos o token
Cada token começa com tok_pci_eu_ e inclui os últimos quatro dígitos, o esquema e a data de validade. Assim pode mostrar na interface "Visa terminando em 1234" sem ter o número de cartão.
Passo
Mesmo token, mesmo cartão
Se o mesmo cartão chegar novamente, devolvemos o mesmo token. Útil para subscrições e cartões já guardados. O mapeamento permanece apenas no vault, não é exposto via API.
→ POST /v1/tokenize
{
"card_number": "4111 1111 1111 1234",
"expiry": "12/26"
}
← 200 OK · 47ms
{
"token": "tok_pci_eu_a1b2c3d4e5f61234",
"last_four": "1234",
"brand": "visa",
"card_in_your_systems": false
}
Quando o número de cartão é necessário
Para autorizar um pagamento, o PSP precisa do número de cartão real. Envia o token: nós recuperamos o cartão do vault e encaminhamo-lo de forma segura. Nunca o vê.
Quando acontece
Quando precisa de cobrar um cartão guardado, envia o token para o nosso endpoint forward. Nós resolvemos o número de cartão no vault e passamo-lo ao PSP por ligação encriptada. Não aparece nos seus registos.
Quem pode fazê-lo
Apenas quem tiver uma chave API com permissão forward ou detokenize. Pode restringir por IP, ambiente e volume de pedidos.
Totalmente auditado
Cada recuperação fica registada: quem solicitou, quando e para que PSP. Os registos são conservados pelo menos 12 meses e podem ser consultados a partir do dashboard ou da API.
Níveis de proteção
Cada pedido é autenticado
Apenas a partir dos seus servidores autorizados
TLS com certificados verificados
Conservados pelo menos 12 meses
Dois endpoints, fluxo claro
Autentique-se com a sua chave API. Um endpoint cria o token, o outro usa-o para pagar. JSON de entrada, JSON de saída.
/v1/tokenize Scope: tokenize Corpo do pedido
{ "card_number": "4111111111111111", "expiry": "12/26", "cvv": "123" }
Resposta 200 OK
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "last_four": "1111", "brand": "visa", "expires_at": "2026-12-31" }
/v1/forward Scope: forward Corpo do pedido
{ "token": "tok_pci_eu_a1b2c3d4e5f6", "target_url": "https://psp.eu/charge", "amount": 9900, "currency": "EUR" }
Resposta (do PSP, proxiada)
{ "status": "authorized", "transaction_id": "txn_9f8e7d6c", "amount": 9900, "currency": "EUR" }
Webhooks e notificações
Quando acontece algo (token criado, pagamento enviado, erro), enviamos um evento em tempo real para o seu endpoint. Cada mensagem está assinada: pode verificá-la no servidor.
Se a entrega falhar, tentamos novamente até 5 vezes com intervalos crescentes. Também pode reenviar manualmente a partir do dashboard nas 72 horas seguintes.
Tipos de Eventos Suportados
token.created Novo token gerado token.used Token enviado ao PSP token.expired Token atingiu o TTL token.deleted Token eliminado a pedido forward.success PSP devolveu 2xx forward.failure PSP devolveu erro Exemplo de Payload Webhook
o-seu-servidor.com/webhooks/pci LIVE
{
"event": "token.created",
"timestamp": "2026-04-03T10:15:30Z",
"data": {
"token": "tok_pci_eu_a1b2c3d4e5f6",
"last_four": "1111",
"brand": "visa",
"merchant_id": "mrc_xyz789"
},
"signature": "sha256=4a8b9c..." // HMAC-SHA256
}Verificação de assinatura
Cada webhook inclui o cabeçalho X-PCI-Signature. Calcule o HMAC-SHA256 do body com o seu secret e compare com a assinatura. Se não coincidir, rejeite o pedido.
SDKs e formas de integrar
SDKs para Node, Python e PHP, ou campos hosted em iFrame. Escolha o que se adapta à sua stack.
SDK JavaScript
npmimport PCIProxy from '@pci-proxy-eu/js';
const pci = new PCIProxy({
merchantId: 'mrc_xyz789'
});
const { token } = await pci.tokenize({
cardNumber: '4111...'
});SDK Python
PyPIfrom pci_proxy_eu import Client
client = Client(
merchant_id="mrc_xyz789",
api_key="sk_live_..."
)
result = client.tokenize(
card_number="4111..."
)SDK PHP
Composeruse PCIProxyEU\Client;
$client = new Client(
merchantId: 'mrc_xyz789',
apiKey: 'sk_live_...'
);
$result = $client->tokenize([
'card_number' => '4111...'
]);iFrames seguros para o checkout
Para se manter em SAQ A: os campos de cartão são renderizados nos nossos iFrames. Os dados de cartão nunca passam pelo seu DOM.
<div id="card-number"></div>
<div id="card-expiry"></div>
<div id="card-cvv"></div>
<script>
PCIProxy.hostedFields({
merchantId: 'mrc_xyz789',
fields: {
cardNumber: '#card-number',
expiry: '#card-expiry',
cvv: '#card-cvv'
},
onTokenize: (result) => {
// apenas token, nunca o número de cartão
console.log(result.token);
}
});
</script>Dados de Pagamento
Dados de cartão nunca no seu servidor
SAQ A
Menos obrigações PCI
CSS
Estilo personalizável
Mobile
Responsive
Pronto para integrar?
Saiba o que é um PCI Proxy, aprofunde-se na tokenização ou veja como os programadores utilizam a plataforma.