Identificadores e prefixos | Documentação da Raims

Saiba a que recurso cada identificador pertence e diferencie IDs de credenciais.

O prefixo é a parte inicial de um identificador, antes do restante do código. Ele ajuda a reconhecer o recurso. O identificador completo é necessário para consultar aquele registro; o prefixo sozinho não identifica uma transação.

Identificadores financeiros

Código ou valor	Significado	Como interpretar
`ch_`	Cobrança	Identifica uma cobrança nas respostas da API, nos links e no Dashboard. Use o valor completo ao consultar a cobrança; ele permanece distinto dos IDs de cliente, pagamento por link e estorno.
`rf_`	Estorno Pix	Identifica uma solicitação de devolução de um pagamento Pix. Pode aparecer no histórico de estornos e no campo refund_id do extrato; consulte o estado do estorno para saber se a devolução foi concluída.
`pl_`	Link de pagamento	Identifica o cadastro do link de pagamento. A URL de checkout pode usar outro token sem prefixo; copie a URL retornada em vez de montá-la a partir deste ID.
`cus_`	Cliente	Identifica o cliente cadastrado pela empresa e vinculado a uma cobrança. É o valor usado em customer_id; não é o CPF, o CNPJ nem a referência do cliente no seu sistema.
`st_`	Lançamento do extrato	Identifica um lançamento individual do extrato. Uma mesma cobrança pode gerar vários lançamentos, cada um com seu próprio ID, como recebimento, tarifa e devolução.
`dp_`	Contestação	Identifica uma contestação de pagamento e pode aparecer no campo dispute_id ou como referência do extrato. Preserve o ID recebido; os casos MED usam outro formato.
`wd_`	Saque	Identifica um saque no Dashboard e nas respostas da API. Pode aparecer em reference_id no extrato; use o valor completo para consultar o saque e acompanhar seu resultado.
`wdst_`	Destino de saque	Identifica um destino Pix próprio verificado, retornado pela consulta de destinos em Produção. Use o valor completo para recuperar seus dados mascarados; ele não identifica um saque nem altera o destino padrão.
`adj_`	Ajuste financeiro	Identifica o ajuste relacionado a um lançamento do extrato. Confira o tipo e o valor do lançamento para distinguir crédito de débito; o ID não informa a direção do ajuste nem define um endpoint público próprio.
`med_`	Caso MED	Identifica um caso do Mecanismo Especial de Devolução do Pix, com sufixo numérico decimal. Pode aparecer como ID de contestação e no campo dispute_id do extrato; o encerramento do caso não comprova, sozinho, uma devolução financeira.

O ID de caso MED usa um número decimal após o prefixo. Preserve o formato recebido ao consultar uma contestação.

Os demais IDs deste grupo usam uma combinação de letras e números que distingue maiúsculas de minúsculas. Copie o valor completo como foi recebido, sem remover zeros, alterar letras ou converter o código em número.

Identificadores da conta e do Dashboard

Estes identificadores aparecem nas configurações da conta, de chaves e de webhooks, nos arquivos de uma contestação e nos envios de imagens do checkout. Copie o valor completo quando precisar identificar o recurso. Eles não substituem as credenciais de autenticação.

Código ou valor	Significado	Como interpretar
`mk_`	Cadastro da chave de API	Identifica a chave gerenciada no Dashboard, inclusive nas ações de configuração e rotação. Não é o segredo usado no header Authorization e não autentica uma requisição.
`cau_`	Envio de imagem do checkout	Identifica um envio autorizado de logo ou ícone. Depois de enviar o arquivo, use o ID no campo correspondente da personalização do checkout. O ID não é a URL da imagem e não comprova que ela já foi aplicada.
`co_`	Empresa	Identifica a conta empresarial em informações do Dashboard e registros de atividade. Conhecer este ID não concede acesso aos dados da empresa; a sessão ou a chave de API continua definindo o acesso permitido.
`whk_`	Cadastro de webhook	Identifica o destino configurado na área de Webhooks do Dashboard. É diferente do segredo usado para verificar a origem das notificações.
`emp_`	Membro da equipe	Identifica uma pessoa com acesso à conta por meio da equipe. Pode aparecer no cadastro, nos convites e nas atividades; suas permissões continuam sendo definidas pelo acesso concedido à pessoa.
`df_`	Arquivo de contestação	Identifica um arquivo vinculado a uma contestação, como um documento de evidência. O acesso ao conteúdo depende das permissões da conta; o ID não é o endereço de download.

Credenciais e segredos

Estes prefixos identificam dados de autenticação, não o cadastro de um recurso:

Código ou valor	Significado	Como interpretar
`sk_test_`	Chave de API do Sandbox	Prefixo do segredo usado para autenticar requisições com dados de teste. Envie a chave completa no header Authorization com o esquema Bearer e mantenha o segredo protegido no backend da sua aplicação.
`sk_live_`	Chave de API de Produção	Prefixo do segredo usado para autenticar requisições no ambiente de operações reais. O prefixo não comprova que a chave está válida: acesso, ambiente e restrições são conferidos a cada requisição.

Código ou valor	Significado	Como interpretar
`whsec_`	Segredo de webhook	Prefixo do segredo de assinatura mostrado ao gerenciar um webhook. Proteja o valor completo e siga a orientação de validação do webhook; ele não é o ID do cadastro nem uma chave Bearer da API.

O ID mk_ de uma chave não autentica requisições. O ID whk_ de um webhook não permite conferir a assinatura de uma mensagem. Para essas finalidades, use a credencial ou o segredo apropriado, conforme os guias de Autenticação e Webhooks.

Não publique credenciais, não as inclua em URLs e não as envie ao suporte. Os exemplos da documentação abreviam os segredos; eles não são credenciais válidas para uso.

Referências sem prefixo

No extrato, uma referência manual pode aparecer sem prefixo. Nesse caso, reference_type informa a categoria. A ausência de prefixo não autoriza tratar esse valor como ID de cobrança, estorno ou contestação.

O token presente na URL de pagamento também é diferente do ID pl_ do link. Preserve a URL fornecida pela Raims; não construa uma URL de checkout trocando ou acrescentando prefixos.

Como usar um identificador

O prefixo não informa a empresa, o ambiente, o valor ou o estado do recurso. IDs de Sandbox e Produção seguem os mesmos prefixos de recurso. O acesso depende da credencial e do vínculo com a empresa e o ambiente corretos.

Um st_ identifica um lançamento. Seus campos reference_id, refund_id e dispute_id, quando preenchidos, identificam outros recursos relacionados. Use o campo certo para cada consulta; a cobrança e seus lançamentos não têm o mesmo identificador.