Envie um cartão de pagamento dentro do WhatsApp, com Pix copia-e-cola ou link de pagamento, dê baixa quando o cliente pagar e use em conversas, templates e automações.
Uma cobrança é um cartão de pagamento nativo do WhatsApp que chega dentro da conversa: número da cobrança, itens, total e um botão — Copiar código Pix ou Pagar, conforme o meio que você usar.
O WhatsApp não processa o pagamento, e a Arara também não. O Pix copia-e-cola ou o link vêm do seu banco ou PSP, e o dinheiro cai direto na sua conta. A Arara entrega o cartão e, quando você avisa que foi pago, põe o selo de pago nele.
À esquerda, a cobrança recém-enviada. À direita, a mesma cobrança depois que você deu baixa.O ciclo tem dois passos e os dois são seus: enviar a cobrança e dar baixa.
Valores sempre em centavos.No dashboard, o mesmo envio sai do link Cobrar na caixa de Conversas: você cola o Pix e a tela lê valor, nome de quem recebe e chave do próprio código.
Conversas: o painel Cobrar com o Pix colado, o valor lido do código e o total no botão de enviar.
2
Dê baixa quando o pagamento cair
Quando o seu banco ou PSP confirmar, avise a Arara. O cartão ganha o selo de pago.
status aceita PAID, FAILED (o pagamento não passou; a cobrança segue em aberto) e CANCELED. description é opcional, até 120 caracteres.Com a conversa fechada, a baixa sai pelo painel (PUT /v1/charges/{id}/status por trás): ela é registrada de qualquer jeito, e o cartão no WhatsApp só é atualizado quando a janela de 24h deixa.No dashboard, as cobranças em aberto da conversa aparecem com Marcar como paga e Cancelar.
Conversas: as cobranças em aberto do contato, com os botões Marcar como paga e Cancelar.
3
Fora da janela, cobre por template
Pra cobrar quem não falou com você nas últimas 24h, crie um template com o botão de cobrança. Ele precisa ser o único botão do template.
curl -X POST https://api.ararahq.com/v1/templates \ -H "Authorization: Bearer ara_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "fatura_pix", "category": "UTILITY", "language": "pt_BR", "body": "Oi {{nome}}, sua fatura de {{mes}} chegou.", "buttons": [{ "type": "CHARGE", "text": "Pagar com Pix" }] }'
Depois de aprovado, envie o template com o mesmo objeto charge do envio na conversa:
Esse é o ponto que mais gera dúvida, então sem rodeio: a Arara não sabe que o cliente pagou. O Pix cai no seu banco, não aqui. Enquanto ninguém avisar, a cobrança fica PENDING pra sempre, e o cartão no WhatsApp continua “aguardando pagamento” mesmo com o dinheiro já na sua conta.Existem dois jeitos de avisar, e você precisa de um deles:
Alguém marca como paga no painel — ou o seu código manda o charge_status por POST /v1/messages.
O seu sistema posta no gancho da automação: um POST no link da automação com { "referenceId": "...", "status": "paid" }. É o caminho pra automatizar — o seu backend, ao receber a confirmação do PSP, repassa pro gancho. status aceita paid, failed, canceled e expired.
A única mudança automática é o vencimento: se você mandou expiresAt e o prazo passa sem baixa, a Arara marca EXPIRED sozinha. No WhatsApp ela aparece como cancelada, porque o cartão não tem estado de vencido. Sem expiresAt, nem isso acontece.
Ou pix, ou paymentLink. Mandar os dois é recusado (“por enquanto é um meio de pagamento por cobrança”), e não mandar nenhum também. Não existe cartão com as duas opções.
Erro de cobrança aparece no celular do seu cliente, então a API recusa cedo, com 422 e a frase do problema:
Código que não é Pix copia-e-cola, ou cortado: todo BR Code termina em 6304 + um dígito verificador (CRC16). A Arara recalcula.
Caractere trocado: o CRC não fecha e o envio é recusado com “copie de novo do banco”.
Total diferente do valor dentro do Pix: se o código fixa valor e ele não bate com o total dos itens, o envio é recusado. Sem isso, o cartão mostraria um número e o banco cobraria outro. Pix sem valor fixo (dinâmico) passa.
referenceId repetido, total zerado ou negativo, item sem nome, valor ou quantidade não positivos, vencimento a menos de 5 minutos, link sem https.
Na conversa, a cobrança só é registrada depois que o provedor aceita o envio: envio que falha não queima o referenceId. Com template é diferente: o template vai pra fila, então a cobrança é registrada já no enfileiramento. Se o envio falhar depois, aquele referenceId ficou usado — reenvie com outro.
Cobrança PAID, CANCELED ou EXPIRED não aceita outro status. Reenviar o mesmo status é permitido (é o caso do cartão que precisa alcançar uma baixa que entrou pelo gancho), qualquer outro é recusado. FAILED não encerra: a cobrança segue em aberto.A baixa por mensagem (charge_status) é mensagem de sessão, então depende da janela de 24h. Como pagamento costuma ser confirmado em minutos, na prática ela está aberta — e quando não está, o caminho é o PUT.
Campanhas ainda não enviam cobrança por contato. Um template de cobrança escolhido numa campanha é recusado na criação. Use a API ou uma automação.
Num passo de mensagem com template de cobrança, você diz de onde vem cada dado. Cada campo aceita texto fixo ou {{variavel}} do evento que dispara a automação:
Pra link de pagamento, use "paymentLink": "{{payment_url}}" no lugar dos campos de Pix. O seu sistema gera o Pix ou o link e manda no evento (payment.failed, cart.abandoned ou webhook próprio); a automação monta e envia a cobrança. As mesmas conferências do envio pela API valem aqui.
O caminho recomendado é o link da automação: o seu sistema manda a cobrança pronta num POST, a automação envia e para no passo wait_payment, e um segundo POST no mesmo link avisa paid. A execução segue por paid ou unpaid, sem mapear {{variaveis}}.Os gatilhos charge.paid e charge.expired iniciam uma automação quando qualquer cobrança da conta chega nesse status.
Enviar cobrança e dar baixa por mensagem passam por POST /v1/messages, que aceita API key. Já os caminhos /v1/charges/** — lista, detalhe, resumo e baixa direta — respondem hoje só à sessão do painel: com ara_live_... a resposta é 403. Pra acompanhar status no seu backend, use os eventos charge.* do webhook.
method é PIX ou PAYMENT_LINK. contact pode vir null; automationId, automationName e runId só vêm preenchidos quando a cobrança saiu de uma automação. O código Pix e o link não são guardados pela Arara.
Endpoint
O que devolve
GET /v1/charges/{id}
Uma cobrança.
GET /v1/charges?contactId={id}
As cobranças de um contato.
PUT /v1/charges/{id}/status
Dá baixa direto: { "status": "PAID" | "CANCELED" | "FAILED" }. Funciona com a conversa fechada; cardUpdated na resposta diz se o cartão no WhatsApp foi atualizado.
