metadata e externalId ligam cada venda da AbacatePay à origem dela e ao seu sistema. As UTMs dizem de qual anúncio ou canal veio a venda, metadata guarda dados seus junto com a cobrança, e externalId é o código do pedido no seu sistema.
Quando usar
Nenhum dos três muda valor, vencimento ou status da cobrança.
Como funciona
Os dados entram quando a cobrança é criada e ficam guardados no pagamento. Depois, aparecem no dashboard, nas respostas da API e nos webhooks.UTM
No checkout e no link de pagamento
Acrescente os parâmetros UTM àurl do checkout ou do link. A tela de pagamento lê utm_source, utm_medium, utm_campaign, utm_term e utm_content e guarda os valores no pagamento:
url com UTMs diferentes em cada canal para comparar as campanhas.
No checkout transparente
No Pix e no boleto do checkout transparente, envie o objetodata.utm em POST /v2/transparents/create. Todos os campos são texto e opcionais:
utm.
Onde ver as UTMs
- Dashboard: em Sua Loja → Cobranças, abra o pagamento. Os valores aparecem em Parâmetros UTM.
- Webhook: os eventos
checkout.*etransparent.*trazempayerInformation.utms, comsource,medium,campaign,termecontent. Os campos sem valor vêmnull.srcescknão vão no webhook. - UTMify: com o plugin ativo em Integração → Plugins, a AbacatePay manda as UTMs,
srcesckde cada venda para a UTMify. O plugin não funciona no Modo Teste.
Metadata
metadata é um objeto de chave e valor que você envia ao criar o recurso. A AbacatePay guarda o objeto e devolve igual nas respostas. No dashboard, ele aparece em Metadados, no detalhe do pagamento.
Use para guardar o que o seu sistema precisa para reconhecer a venda: o id do pedido, do usuário ou do plano. Não guarde senhas nem dados de cartão.
O tipo dos valores muda conforme o recurso:
Onde só texto é aceito,
{ "pedidos": 3 } é recusado. Envie { "pedidos": "3" }.
externalId
externalId é o código do pedido, da fatura ou do cadastro no seu sistema. Com ele, você busca a cobrança pelo seu código, sem guardar o id da AbacatePay, e evita criar a mesma cobrança duas vezes.
O que acontece quando você repete um externalId:
Por isso, numa nova tentativa de pagamento do mesmo pedido, reenvie o mesmo
externalId: você recebe a cobrança que já existe.
Para buscar pelo seu código, passe externalId em GET /v2/checkouts/get, GET /v2/checkouts/list ou GET /v2/transparents/list. O externalId também vem nos webhooks, em checkout.externalId e transparent.externalId.
Pelo dashboard
As UTMs e os metadados aparecem no detalhe de cada pagamento, em Sua Loja → Cobranças. Para gravar UTMs numa venda feita pelo dashboard, acrescente os parâmetros àurl do link de pagamento ou da cobrança antes de mandar ao cliente. metadata e externalId só podem ser enviados pela API.
Testar no Modo Teste
Crie uma cobrança comutm, metadata e externalId, ou abra um checkout com UTMs na url, e simule o pagamento. Os valores aparecem no dashboard e no webhook do teste. Veja Modo Teste.
Perguntas frequentes
Quais parâmetros UTM a AbacatePay aceita?
Quais parâmetros UTM a AbacatePay aceita?
utm_source, utm_medium, utm_campaign, utm_term e utm_content na url do checkout e do link. No checkout transparente, o objeto utm aceita também src e sck.As UTMs aparecem no webhook?
As UTMs aparecem no webhook?
Sim, em
payerInformation.utms, com source, medium, campaign, term e content.Posso mandar números em metadata?
Posso mandar números em metadata?
No checkout, no link, na assinatura e no Pix ou boleto do checkout transparente, sim. Em cliente, cartão e subconta, os valores precisam ser texto.
O que acontece se eu criar dois checkouts com o mesmo externalId?
O que acontece se eu criar dois checkouts com o mesmo externalId?
O segundo pedido devolve o primeiro checkout, sem criar outro e sem mudar os itens.