Dê a cada usuário um endereço de depósito cripto exclusivo

Por que um endereço compartilhado não funciona

Toda plataforma que aceita cripto bate no mesmo muro, na mesma ordem, geralmente depois do primeiro chamado sobre um pagamento que ninguém acha.

• Um único endereço informa um valor e um remetente, nunca a qual dos seus usuários ele pertence. Conciliar por valor quebra na primeira vez que duas pessoas enviam a mesma quantia.
• A gambiarra habitual é juntar tudo e repassar depois — o que transforma um recurso de pagamento em guardar dinheiro dos outros, a coisa mais pesada que uma plataforma pode assumir.
• Pedir que o usuário cole um memo ou uma referência funciona até alguém esquecer, e aí é uma pessoa conciliando uma blockchain na mão.

Uma chamada por usuário, uma única vez

Você envia o seu próprio identificador do usuário. Recebe endereços que nunca mudam, então a chamada acontece no cadastro e nunca mais.

1. 01

   Crie o cliente com o seu id

   Passe o id que você já usa para o usuário em `external_ref`. A Unheld não cria um identificador que você depois precise guardar e mapear — o registro é indexado pelo id que o seu banco de dados já usa.

2. 02

   Guarde os endereços que voltarem

   A resposta traz os endereços de depósito daquele usuário, derivados da sua própria carteira. São permanentes: você pode exibi-los, colocá-los num QR code, ou deixar o usuário salvá-los e enviar de onde quiser.

3. 03

   Credite a conta quando o webhook chegar

   Um pagamento nesse endereço é atribuído ao cliente a quem ele pertence, e a notificação devolve o seu próprio `externalRef`. Sua aplicação credita um id de usuário que já conhece, sem conciliar valores nem ler uma blockchain.

A chamada de verdade

Requisição

curl -X POST https://api.unheld.io/api/v1/customers \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user_8412",
    "label": "Ada Lovelace",
    "supported_assets": ["ETH", "USDC"],
    "evm": true
  }'

Resposta

{
  "id": "c7f1…",
  "external_ref": "user_8412",
  "label": "Ada Lovelace",
  "evm_address": "0x…",
  "supported_assets": ["ETH", "USDC"],
  "receive_method": "auto"
}

Exige uma API key com o escopo `customers:write`; para lê-los de volta é preciso `customers:read`. Os endereços de cada rede em que um usuário pode pagar estão em `GET /api/v1/customers/:id/addresses`.

Como um pagamento encontra seu usuário

Faturas também podem ser vinculadas a um cliente com `customerId`, de modo que uma cobrança avulsa e um endereço de depósito fixo sejam atribuídos ao mesmo usuário, tanto no painel quanto nos webhooks.

Onde o dinheiro realmente fica

O que isso não diz é se a sua plataforma está guardando fundos dos seus usuários. Provavelmente está, se os pagamentos chegam a endereços que você controla e você deve esse valor a eles. Essa é uma questão do seu próprio arranjo e da sua jurisdição, e não é uma que possamos responder por você — busque orientação. Só podemos afirmar o nosso lado: o dinheiro nunca passa pela Unheld.

Construir sobre isto

Cada um destes pontos é mais fácil de prever agora do que descobrir em produção.

• Todo endereço de usuário deriva de uma única carteira: a sua. Isso deixa uma só frase de recuperação para proteger, não uma por usuário, e significa que os fundos não ficam segregados por usuário via chaves.
• Um endereço permanente é reutilizado por design, e é isso que faz a atribuição funcionar. Também significa que o histórico de pagamentos de um usuário para você é rastreável on-chain por quem descobrir o endereço dele.
• O endereço de um usuário é fixo por família de redes: o mesmo endereço EVM recebe em todas as redes EVM que você habilitar. Habilitar uma nova rede não exige reemitir endereços.
• Excluir um cliente para de observar o endereço dele; não move — nem pode mover — o que já foi enviado para lá. O dinheiro que chegar depois da exclusão continua sendo seu, mas nada vai te avisar dele.

Perguntas