Identificadores
Todo id que a SwitchPay devolve é um texto com um prefixo que diz o tipo da coisa. Assim dá pra bater o olho num id solto (num log, num e-mail de suporte) e saber do que se trata.
| Prefixo | O que identifica | Exemplo |
|---|---|---|
pi_ | Intenção de pagamento | pi_7b2f9c1e-4d3a-4c6b-9e1f-2a3b4c5d6e7f |
trx_ | Transação (a venda) | trx_6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b |
whk_ | Cadastro de webhook | whk_3a9d1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b |
evt_ | Evento enviado por webhook | evt_5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e |
cmp_ | Conta de empresa (o vendedor) | cmp_8f2a1c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d |
pl_ | Link de pagamento | pl_9c1e2d3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f |
Como tratar um id
- Guarde como texto, com o prefixo. Reserve espaço pra até 64 caracteres.
- Use o id inteiro nas chamadas, do jeito que veio:
GET /v2/transactions/trx_6f1a2b3c-…. - Não interprete o que vem depois do prefixo. O formato pode mudar; a única garantia é o prefixo e o tamanho máximo.
O seu próprio identificador
Além do id da SwitchPay, você pode mandar o seu identificador no campo referenceId (o
número do pedido no seu sistema, por exemplo). Ele volta na transação e serve de filtro em
GET /v2/transactions?referenceId=…. É o jeito mais simples de ligar uma venda da SwitchPay a um
pedido seu.
Textos com prefixo que não são ids
Alguns valores também têm prefixo, mas são segredos ou códigos de uso único, não identificadores. Nunca registre em log nem mostre ao usuário:
| Prefixo | O que é |
|---|---|
swp_test_ / swp_live_ | Chave de API (sandbox / produção) |
whsec_ | Segredo pra conferir a assinatura dos webhooks |
vtk_ | Token de cartão devolvido pelo cofre, de uso único |