Cobrar com Payment Intents

Este guia mostra como criar cobranças diretamente pela API, sem depender de uma Checkout Session. Ao final, seu sistema será capaz de:

criar uma cobrança vinculada ao objeto do seu sistema;
exibir o QR Code e o copia-e-cola de um PIX;
concluir a operação de negócio somente quando o pagamento for confirmado;
tratar corretamente tentativas que falham ou são canceladas;
lidar com retries, eventos duplicados e eventos fora de ordem;
receber eventos de organizações conectadas quando a integração for de plataforma.

A integração server-to-server usa a API REST. Você não precisa de um SDK da Chargefy: os exemplos abaixo usam HTTP diretamente. Mantenha a API key apenas no seu backend.

O desenho da integração

O payment_intent representa uma cobrança: uma compra, uma invoice ou um ciclo que precisa ser pago. Cada tentativa concreta dentro dela é registrada como uma charge. O objeto de negócio continua pertencendo ao seu sistema; guarde nele o ID do Payment Intent que representa aquela cobrança.

Etapa	Responsável	Ação	Resultado
1	Comprador	Inicia a compra ou operação	Seu backend recebe a solicitação.
2	Seu backend	Cria um registro `awaiting_payment`	A operação fica ligada à cobrança.
3	Seu backend	Envia `POST /v1/payment-intents`	Recebe o `payment_intent` e a `next_action`.
4	Seu backend	Apresenta a próxima ação	O comprador vê o QR Code PIX ou o resultado do cartão.
5	Chargefy	Envia `payment.intent.succeeded`, `payment.intent.updated` (recusa) ou `payment.intent.canceled`	Seu webhook recebe o desfecho ou a recusa retentável.
6	Seu backend	Atualiza o registro de forma idempotente	A operação é concluída ou a tentativa é encerrada.

Separe os estados do seu objeto de negócio dos estados do pagamento:

Estado local	O que significa	Estado comum do Payment Intent
`awaiting_payment`	A operação foi criada e ainda falta concluir o pagamento.	`requires_confirmation`, `pending` ou `processing`
`completed`	O pagamento foi confirmado e a operação foi concluída.	`succeeded`
`payment_failed`	A última tentativa foi recusada; o mesmo intent aceita nova confirmação enquanto a operação continuar pagável.	`requires_payment_method` com `last_payment_error` preenchido
`canceled`	A operação ou a tentativa foi cancelada pelo comprador ou pelo seu sistema.	`canceled`
`expired`	O código PIX ou o prazo comercial terminou.	`requires_payment_method` quando o código venceu (aceita novo código no mesmo intent); `canceled` se você encerrou pelo seu prazo comercial

Não use redirect, callback do frontend, ausência de next_action ou checkout.session.completed como prova de pagamento. Para concluir a operação, processe payment.intent.succeeded.

Antes de começar

Você precisa de:

uma API key do ambiente correto;
um registro no seu banco para relacionar a cobrança ao seu objeto de negócio;
uma URL HTTPS para receber webhooks assinados;
uma restrição de unicidade para os IDs evt_* já processados.

No seu banco, guarde pelo menos:

Campo local	Para que serve
`reference_id`	ID do objeto de negócio relacionado no seu sistema.
`payment_intent_id`	ID `pi_*` que representa a cobrança atual. Troque apenas ao iniciar outro fluxo depois de um estado terminal.
`payment_status`	Cópia do status financeiro mais recente.
`business_status`	Estado da operação no seu sistema, separado do pagamento.
`pix_code_expires_at`	Cópia de `next_action.pix_display_qr_code.expires_at`; persista antes que `next_action` seja limpo.
`payment_expires_at`	Prazo comercial definido pelo seu sistema, quando existir. Pode ser diferente da validade do PIX.
`processed_webhook_events`	Tabela ou inbox com cada `evt_*` recebido, usando o ID como chave única.

Grave a relação principal no seu banco, em payment_intent_id. Assim, cada webhook pode ser correlacionado pelo ID do Payment Intent sem depender de campos livres enviados pelo cliente.

1. Crie e confirme o PIX

Para obter o QR Code em uma única chamada, envie confirm: true e permita somente pix. Use uma chave de idempotência estável para criar a cobrança. Se sua chamada sofrer timeout, repita a mesma requisição com a mesma chave em vez de criar outro intent.

curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-order-8f4c2a" \
  -d '{
    "amount": 7500,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_e2wcu85THLyw1Q53",
    "metadata": {},
    "payment_method_types": ["pix"]
  }'

A resposta é o objeto completo. Em PIX, o estado comum após a confirmação é pending, e next_action contém os dados que o frontend deve apresentar.

{
  "id": "pi_yEiGAw9jN95nBBL8",
  "object": "payment_intent",
  "amount": 7500,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 7500,
    "installment_interest_amount": 0,
    "principal_amount": 7500,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_yEiGAw9jN95nBBL8_secret_3d43b50b7de0a1337be76ff10c4993faa101c16b5a647383",
  "confirmation_method": "automatic",
  "created_at": "2026-07-21T14:00:00Z",
  "currency": "brl",
  "customer": "cus_e2wcu85THLyw1Q53",
  "installment_interest_amount": 0,
  "installments": null,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": "ch_QCRi1go92zjYxWo1",
  "livemode": true,
  "metadata": {},
  "next_action": {
    "pix_display_qr_code": {
      "expires_at": "2026-07-21T15:00:00Z",
      "qr_code": "00020101021226860014br.gov.bcb.pix...",
      "qr_code_url": null
    },
    "type": "pix_display_qr_code"
  },
  "payment_method": null,
  "payment_method_options": {},
  "payment_method_types": [
    "pix"
  ],
  "principal_amount": 7500,
  "status": "pending",
  "surcharge_amount": 0,
  "updated_at": "2026-07-21T14:00:01Z"
}

Depois da resposta:

grave pi_yEiGAw9jN95nBBL8 em payment_intent_id;
mantenha a operação local em awaiting_payment;
grave next_action.pix_display_qr_code.expires_at em pix_code_expires_at;
envie ao frontend apenas os campos necessários de next_action;
aguarde o webhook para concluir a operação ou encerrar a tentativa.

Se você opera uma plataforma

Use a API key da plataforma e envie o header Organization com a organização conectada que receberá o pagamento:

curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_V1zwh6dK7nfgWFtV" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-order-8f4c2a" \
  -d '{
    "amount": 7500,
    "confirm": true,
    "currency": "brl",
    "metadata": {},
    "payment_method_types": ["pix"]
  }'

O Payment Intent pertence à organização indicada no header. Use a mesma organização ao consultá-lo, cancelá-lo ou regenerar o PIX.

2. Exiba o PIX

Leia next_action.type. Para PIX, o valor é pix_display_qr_code.

Campo	Como usar
`next_action.pix_display_qr_code.qr_code`	Texto EMV do PIX copia-e-cola.
`next_action.pix_display_qr_code.qr_code_url`	Imagem pronta do QR Code, quando disponível. Pode ser `null`.
`next_action.pix_display_qr_code.expires_at`	Validade daquele código PIX. Use para informar o comprador e encerrar a tela.

O frontend pode mostrar uma contagem regressiva, mas não deve alterar o estado financeiro. Quando a contagem terminar, consulte o Payment Intent no backend ou aguarde payment.intent.canceled.

expires_at pertence ao código PIX dentro de next_action; o payment_intent não tem um expires_at top-level. O prazo comercial para concluir o pagamento (payment_expires_at) também é seu e pode ser diferente da validade do código de pagamento.

Eventos da confirmação e da expiração

Quando a confirmação muda o intent de requires_confirmation para pending, a Chargefy emite payment.intent.updated. Use o objeto completo do evento para sincronizar status, latest_charge, next_action e pix_code_expires_at. Se o PIX vencer sem pagamento, a expiração encerra a tentativa — não o intent:

Campo ou evento	Resultado
`status`	`requires_payment_method`
`next_action`	`null`
Evento emitido pela expiração	`payment.intent.updated`
`payment.intent.canceled`	Não é emitido; cancelamento fica reservado a decisões.

O intent aceita um novo código via /regenerate_pix. Não espere recuperar expires_at no payload da expiração: persista-o a partir da resposta de confirmação ou do payment.intent.updated que trouxe o código. A sequência acima é lógica; as requisições de webhook ainda podem chegar fora de ordem ou ser reentregues.

3. Cobre um cartão salvo

Para cartão, informe um payment_method salvo do customer. Com confirm: true, a cobrança costuma ser resolvida na mesma chamada.

curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-order-8f4c2a-attempt-1" \
  -d '{
    "amount": 12000,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_e2wcu85THLyw1Q53",
    "metadata": {},
    "payment_method": "pm_cwdZMSKcr8R6GfVM",
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "count": 3,
          "has_interest": true
        }
      }
    },
    "payment_method_types": ["credit_card"]
  }'

Resultado	O que fazer
`status: "succeeded"`	Espere e processe também `payment.intent.succeeded`; o webhook mantém o backend consistente em caso de timeout da resposta.
`status: "requires_capture"`	A autorização foi feita com captura manual; capture antes de concluir a operação no seu sistema.
`status: "requires_payment_method"` com `last_payment_error`	A tentativa foi recusada; o intent continua confirmável. Corrija o cartão ou troque de método e confirme o mesmo intent de novo.
Erro HTTP `402`	A tentativa foi recusada. Não repita automaticamente com o mesmo método sem ação do comprador; um intent aceita até 10 tentativas.

Se ainda não existe um método salvo, use um Setup Intent e a tokenização segura do cartão antes de criar a cobrança.

4. Cadastre os webhooks necessários

Os tipos devem ser cadastrados individualmente. Não existe wildcard para payment.intent.*. Para manter uma visão completa do ciclo da cobrança, inscreva:

[
  "payment.intent.created",
  "payment.intent.updated",
  "payment.intent.succeeded",
  "payment.intent.canceled",
  "charge.failed"
]

curl -X POST "https://api.chargefy.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "payment.intent.created",
      "payment.intent.updated",
      "payment.intent.succeeded",
      "payment.intent.canceled",
      "charge.failed"
    ],
    "events_from": "organization",
    "name": "Payment Intents",
    "url": "https://meusite.com/webhooks/chargefy"
  }'

O secret whsec_... aparece somente na resposta de criação. Guarde-o em um gerenciador de secrets.

Organização ou plataforma

`events_from`	Eventos recebidos
`organization`	Eventos próprios da organização dona do endpoint.
`platform`	Eventos das organizações conectadas ativas da plataforma. O campo top-level `organization` identifica a origem.

events_from: "platform" não inclui os eventos próprios da organização da plataforma. Se você precisa dos dois fluxos, crie dois endpoints. Eles podem usar a mesma URL, mas terão secrets independentes.

5. Verifique a assinatura

A implementação oficial segue Standard Webhooks. Cada entrega inclui:

webhook-id;
webhook-timestamp;
webhook-signature;
um secret no formato whsec_....

Verifique o corpo bruto antes de parsear o JSON. O exemplo abaixo usa uma biblioteca compatível com Standard Webhooks; ela não é um SDK da Chargefy.

import { Webhook } from "svix";

const verifier = new Webhook(process.env.CHARGEFY_WEBHOOK_SECRET!);

export async function receiveChargefyWebhook(request: Request) {
  const rawBody = await request.text();

  const event = verifier.verify(rawBody, {
    "webhook-id": request.headers.get("webhook-id")!,
    "webhook-timestamp": request.headers.get("webhook-timestamp")!,
    "webhook-signature": request.headers.get("webhook-signature")!,
  }) as ChargefyEvent;

  // Persista antes de responder. A chave única transforma reentregas em no-op.
  await webhookInbox.insertIfAbsent(event.id, event);
  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

Não valide um HMAC apenas sobre o JSON já parseado. A assinatura cobre $ {webhook - id}.${webhook - timestamp}.${corpo_bruto} e usa os bytes decodificados do secret whsec_....

Veja implementações completas e o algoritmo manual em Entrega e assinatura de webhooks. Depois de persistir o evento, processe a inbox em background. Assim você responde em menos de 20 segundos e não perde o payload se sua regra de negócio estiver temporariamente indisponível.

6. Processe os eventos sem duplicar efeitos

Cada data.object contém o objeto payment_intent público completo no estado registrado pelo evento. data.previous_attributes, quando presente, contém somente os valores anteriores dos campos alterados.

Evento	Ação recomendada no seu sistema
`payment.intent.created`	Registre ou sincronize a cobrança. Não conclua a operação.
`payment.intent.updated`	Atualize o retrato local. Na confirmação do PIX, ele registra `requires_confirmation → pending` com `next_action` completo; numa recusa, traz `status: "requires_payment_method"` e `last_payment_error`.
`payment.intent.succeeded`	Marque o pagamento como concluído e avance a operação de negócio.
`charge.failed`	Registre o detalhe da tentativa recusada (código, categoria). O intent segue confirmável.
`payment.intent.canceled`	Encerre a cobrança somente se ela ainda não estiver concluída. A expiração de um código PIX não emite este evento — ela chega por `payment.intent.updated` com `status: "requires_payment_method"`.

Um handler seguro segue esta ordem:

async function processEvent(event: ChargefyEvent) {
  await database.transaction(async (tx) => {
    // A restrição UNIQUE em event.id transforma retries em no-op.
    const inserted = await tx.processedEvents.insertIfAbsent(event.id);
    if (!inserted) return;

    const intent = event.data.object as PaymentIntent;
    const operation = await tx.operations.findByPaymentIntent(intent.id);
    // Lance um erro para a sua fila tentar de novo. Isso cobre o caso raro em
    // que o webhook chega antes de payment_intent_id ser persistido.
    if (!operation) throw new RetryableError("Operation not linked yet");

    // Ignora outro ciclo de cobrança que não representa mais esta operação.
    if (operation.paymentIntentId !== intent.id) return;

    switch (event.type) {
      case "payment.intent.succeeded":
        await tx.operations.complete(operation.id, intent);
        break;

      case "payment.intent.updated":
        if (
          operation.status !== "completed" &&
          intent.status === "requires_payment_method" &&
          intent.last_payment_error
        ) {
          await tx.operations.markPaymentFailed(operation.id, intent);
        }
        break;

      case "payment.intent.canceled":
        if (operation.status !== "completed") {
          await tx.operations.markPaymentCanceled(operation.id, intent);
        }
        break;

      default:
        await tx.operations.syncPayment(operation.id, intent);
    }
  });
}

Duplicação e ordem

A entrega é at least once: o mesmo event.id pode chegar novamente.
Eventos diferentes podem chegar fora de ordem.
Não compare apenas a ordem em que as requisições chegaram.
Não deixe um evento antigo rebaixar uma operação que já está completed.
data.object é o snapshot completo do momento do evento, não uma garantia de que continua atual quando a entrega chega.
Antes de aplicar falha ou cancelamento, consulte o Payment Intent pelo ID e preserve succeeded.

7. Consulte o pagamento ao reabrir a tela

O webhook mantém o backend sincronizado. O GET é útil quando o comprador reabre a tela de pagamento, atualiza a página ou volta depois de um período offline.

curl -X GET "https://api.chargefy.io/v1/payment-intents/pi_yEiGAw9jN95nBBL8" \
  -H "Authorization: Bearer {{API_KEY}}"

Use a resposta para reconstruir a tela:

Status	Tela sugerida
`requires_payment_method`	Solicite um método de pagamento; se `last_payment_error` estiver preenchido, mostre o motivo da recusa e ofereça nova tentativa no mesmo intent.
`requires_confirmation`	Confirme a tentativa pelo backend.
`pending`	Mostre o PIX vigente em `next_action` e aguarde o webhook.
`processing`	Informe que o pagamento está em processamento.
`requires_capture`	Mostre que a autorização existe, mas ainda falta captura.
`succeeded`	Mostre o pagamento concluído e o resultado da operação.
`failed`	Estado histórico (cobrança de fatura); para nova cobrança, crie outro fluxo.
`canceled`	Mostre a tentativa encerrada e crie outra somente se a operação ainda puder ser paga.

Polling contínuo não é necessário. Se você optar por polling apenas para atualizar a tela do comprador, trate-o como conveniência de UX; o efeito de negócio continua sendo processado no backend.

8. Cancele a tentativa quando necessário

Você pode cancelar um intent que ainda não está em succeeded ou canceled:

curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_yEiGAw9jN95nBBL8/cancel" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-order-8f4c2a-cancel" \
  -d '{
    "cancellation_reason": "requested_by_customer"
  }'

Valores aceitos:

Valor	Use quando
`duplicate`	Outra tentativa representa a mesma cobrança.
`fraudulent`	Seu sistema decidiu encerrar a tentativa por suspeita de fraude.
`requested_by_customer`	O comprador pediu o cancelamento.
`abandoned`	O comprador saiu do fluxo. Nós nunca escrevemos esse valor — ele só aparece se você enviar.

A Chargefy também escreve motivos por conta própria — automatic, expired, failed_invoice e void_invoice. Você recebe esses valores na resposta e nos webhooks, mas não pode enviá-los: a requisição responde 400.

Se a tentativa nasceu de uma sessão de checkout, o cancelamento não vai por aqui. A sessão é a dona do ciclo de vida do intent, então use POST /v1/checkout-sessions/{id}/expire — o intent é cancelado junto, com expired. O cancelamento direto responde 409, exceto em requires_capture.

Você não precisa cruzar dados para saber o que aconteceu: expired já diz que um prazo acabou. E abandoned nunca chega da Chargefy — se você recebeu esse motivo, foi porque você mesmo o enviou.

O endpoint retorna o Payment Intent completo já cancelado e também gera payment.intent.canceled. Faça a atualização local de maneira idempotente para que a resposta e o webhook não produzam o mesmo efeito duas vezes.

9. Permita outra tentativa com segurança

Use uma destas estratégias:

Situação	Próximo passo
O PIX expirou, a operação ainda pode ser paga e você quer manter o mesmo intent	Use `POST /v1/payment-intents/{id}/regenerate_pix`. O ID `pi_*` é preservado e `next_action` recebe um novo código.
O intent falhou ou foi cancelado explicitamente	O intent está terminal. Se a operação continuar pagável, inicie outro fluxo com um novo Payment Intent, uma nova chave de idempotência e atualize `payment_intent_id`.
O cartão foi recusado	Peça outro método ou uma ação do comprador; não faça loop automático de cobranças.
Outra cobrança já foi paga	Mantenha a operação concluída e ignore eventos terminais de intents antigos.

Cada novo fluxo terminal deve ter um identificador próprio no seu sistema. Um padrão simples é payment-order-8f4c2a, payment-order-8f4c2a-retry-2 e assim por diante. Dentro do mesmo intent, latest_charge e os eventos charge.* identificam as tentativas concretas, como um PIX regenerado.

10. Entenda Payment Intent, Charge e Transaction

Os três objetos respondem perguntas diferentes:

Objeto	Pergunta que responde
`payment_intent`	Qual é o estado da cobrança?
`charge`	O que aconteceu na tentativa concreta de cobrar o método?
`transaction`	Quanto entrou no extrato, quais taxas foram descontadas e quando o valor liquida?

Para avançar ou encerrar a operação no seu sistema, use o Payment Intent. Para investigar uma recusa, consulte latest_charge. Para conciliação financeira e liquidação, consulte Transactions.

Checklist de testes

Antes de produção, valide pelo menos:

Referência rápida

Objeto Payment Intent

Campos, enums, status, next_action, valores e timestamps.

Criar Payment Intent

Parâmetros e respostas de criação.

Consultar Payment Intent

Estado atual e expansões de payment_method e latest_charge.

Confirmar Payment Intent

Confirmação de cartão e PIX.

Cancelar Payment Intent

Estados canceláveis e motivos de cancelamento.

Eventos de Payment Intent

Catálogo e páginas individuais de cada payload.

Entrega e assinatura

Standard Webhooks, retry, timeout, duplicação e ordem.

Lifecycle financeiro

Relação entre Payment Intent, Charge, Transaction e Invoice.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Cobrar com Payment Intents

O desenho da integração

Antes de começar

1. Crie e confirme o PIX

Se você opera uma plataforma

2. Exiba o PIX

Eventos da confirmação e da expiração

3. Cobre um cartão salvo

4. Cadastre os webhooks necessários

Organização ou plataforma

5. Verifique a assinatura

6. Processe os eventos sem duplicar efeitos

Duplicação e ordem

7. Consulte o pagamento ao reabrir a tela

8. Cancele a tentativa quando necessário

9. Permita outra tentativa com segurança

10. Entenda Payment Intent, Charge e Transaction

Checklist de testes

Referência rápida

Objeto Payment Intent

Criar Payment Intent

Consultar Payment Intent

Confirmar Payment Intent

Cancelar Payment Intent

Eventos de Payment Intent

Entrega e assinatura

Lifecycle financeiro

​O desenho da integração

​Antes de começar

​1. Crie e confirme o PIX

​Se você opera uma plataforma

​2. Exiba o PIX

​Eventos da confirmação e da expiração

​3. Cobre um cartão salvo

​4. Cadastre os webhooks necessários

​Organização ou plataforma

​5. Verifique a assinatura

​6. Processe os eventos sem duplicar efeitos

​Duplicação e ordem

​7. Consulte o pagamento ao reabrir a tela

​8. Cancele a tentativa quando necessário

​9. Permita outra tentativa com segurança

​10. Entenda Payment Intent, Charge e Transaction

​Checklist de testes

​Referência rápida

Objeto Payment Intent

Criar Payment Intent

Consultar Payment Intent

Confirmar Payment Intent

Cancelar Payment Intent

Eventos de Payment Intent

Entrega e assinatura

Lifecycle financeiro

O desenho da integração

Antes de começar

1. Crie e confirme o PIX

Se você opera uma plataforma

2. Exiba o PIX

Eventos da confirmação e da expiração

3. Cobre um cartão salvo

4. Cadastre os webhooks necessários

Organização ou plataforma

5. Verifique a assinatura

6. Processe os eventos sem duplicar efeitos

Duplicação e ordem

7. Consulte o pagamento ao reabrir a tela

8. Cancele a tentativa quando necessário

9. Permita outra tentativa com segurança

10. Entenda Payment Intent, Charge e Transaction

Checklist de testes

Referência rápida