Seus clientes não têm conta na OriPay: todo o dinheiro passa pela sua conta. Para saber de quem é cada movimento, você marca os recursos com dois campos seus.
Não coloque CPF, nome, e-mail ou telefone em metadata nem em external_id. Use o ID interno do seu cliente.

​
Onde eles voltam

Os dois campos voltam sem mudança em:
  • a resposta do POST e de todo GET do recurso;
  • todo webhook do recurso (data.external_id, data.metadata);
  • a linha do extrato gerada por ele;
  • as devoluções, que trazem o próprio external_id e o received_id do PIX original (devoluções não têm metadata).

​
Padrão recomendado

  1. Crie o recurso com external_id = seu ID e metadata.customer_id = seu cliente.
  2. No webhook, procure pelo external_id (ou metadata.customer_id) e dê baixa.
  3. Perdeu um webhook? GET /v1/pix/charges?external_id=pedido-8812.

​
Quem pagou

Além dos seus campos, todo PIX recebido e toda cobrança paga trazem o payer, preenchido pelo banco: Use o metadata para saber de quem era a cobrança e o payer para saber quem de fato pagou.

​
PIX recebido fora de cobrança

Se alguém paga direto na chave PIX da sua conta (sem QR seu), não existe external_id. O evento pix.received traz o payer (nome e documento) para você identificar o cliente pelo documento. Para atribuição exata, prefira sempre cobranças.