Emitir o primeiro boleto da fatura

curl -X POST "https://api.chargefy.io/v1/invoices/inv_2Th8gTm8USwKEyzo/issue_boleto" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: emitir-boleto-pedido-2026-001"

{
  "id": "pi_JgEJanPt14Dbs46f",
  "object": "payment_intent",
  "...": "outros campos do Payment Intent",
  "amount": 14990,
  "currency": "brl",
  "invoice": "inv_2Th8gTm8USwKEyzo",
  "latest_charge": "ch_YFvU8E5yMkDgQ74c",
  "next_action": {
    "boleto_display_details": {
      "barcode": "23791966600000149903381286008296100211202300",
      "expires_at": "2026-11-01T23:59:59-03:00",
      "hosted_voucher_url": "https://meusite.com/boleto.pdf",
      "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
      "pdf": "https://meusite.com/boleto.pdf"
    },
    "type": "boleto_display_details"
  },
  "payment_method_types": [
    "boleto"
  ],
  "status": "requires_action"
}

{
  "error": {
    "code": "buyer_field_required",
    "message": "Informe o CPF ou CNPJ.",
    "param": "customer_document",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Invoice not found",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "A payment for this invoice is already in progress or completed",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_result_unconfirmed",
    "message": "The payment result is not confirmed yet. Do not submit the payment again.",
    "type": "api_error"
  }
}

Emite o primeiro boleto de uma fatura open, avulsa ou de assinatura, sem abrir a página hospedada. A chamada usa o valor a receber da fatura e os dados do customer já cadastrado. Não é necessário enviar um corpo. A resposta é o Payment Intent completo, vinculado à mesma fatura. Leia:

Campo	Conteúdo
`next_action.boleto_display_details.pdf`	URL do PDF do boleto.
`next_action.boleto_display_details.number`	Linha digitável.
`next_action.boleto_display_details.barcode`	Código de barras.
`next_action.boleto_display_details.expires_at`	Fim do dia de vencimento no horário de Brasília.
`invoice`	ID da fatura que será quitada.

Emitir o documento não significa receber o pagamento: o status normalmente é requires_action. Aguarde invoice.paid para considerar a fatura quitada.

string

obrigatório

ID da fatura (inv_*).

curl -X POST "https://api.chargefy.io/v1/invoices/inv_2Th8gTm8USwKEyzo/issue_boleto" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: emitir-boleto-pedido-2026-001"

{
  "id": "pi_JgEJanPt14Dbs46f",
  "object": "payment_intent",
  "...": "outros campos do Payment Intent",
  "amount": 14990,
  "currency": "brl",
  "invoice": "inv_2Th8gTm8USwKEyzo",
  "latest_charge": "ch_YFvU8E5yMkDgQ74c",
  "next_action": {
    "boleto_display_details": {
      "barcode": "23791966600000149903381286008296100211202300",
      "expires_at": "2026-11-01T23:59:59-03:00",
      "hosted_voucher_url": "https://meusite.com/boleto.pdf",
      "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
      "pdf": "https://meusite.com/boleto.pdf"
    },
    "type": "boleto_display_details"
  },
  "payment_method_types": [
    "boleto"
  ],
  "status": "requires_action"
}

{
  "error": {
    "code": "buyer_field_required",
    "message": "Informe o CPF ou CNPJ.",
    "param": "customer_document",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Invoice not found",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "A payment for this invoice is already in progress or completed",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_result_unconfirmed",
    "message": "The payment result is not confirmed yet. Do not submit the payment again.",
    "type": "api_error"
  }
}

Antes de emitir

A fatura precisa estar open, com saldo a receber e boleto habilitado em payment_method_types.
O customer precisa ter nome, e-mail, CPF/CNPJ válido e endereço completo: país BR, UF, cidade, bairro, rua e CEP. Complete o cadastro pela API de customers antes da emissão. A fatura também precisa ter nome e e-mail corretos no seu snapshot de cobrança.
O valor vem da fatura, incluindo multa e juros de atraso aplicáveis. Não envie amount, dados de cartão ou outro método nesta ação.
O boleto vence no dia da fatura, respeitando o mínimo de três dias a partir da emissão, no calendário de Brasília. O vencimento da fatura não é alterado.

Repetição e pagamentos em andamento

Envie Idempotency-Key para repetir com segurança a mesma solicitação. Uma nova chamada enquanto o boleto ainda está ativo devolve o mesmo Payment Intent e documento, sem emitir outro boleto. Se houver outro pagamento em andamento, a emissão retorna 409. Esta ação não reemite boletos anteriores. Depois que o banco confirmar o encerramento de um boleto sem pagamento, use regenerate_boleto no Payment Intent. Um boleto vencido ainda aguardando compensação bloqueia uma nova emissão. Se receber 502 payment_result_unconfirmed, a solicitação pode ter sido recebida. Consulte o Payment Intent e aguarde os webhooks; não crie outra fatura nem repita a cobrança automaticamente.

Chargefy for Platforms

Esta seção se aplica somente ao Chargefy for Platforms, que opera pagamentos para suas organizações filhas.

Use a chave da plataforma e o header Organization com a organização filha dona da fatura. A chave da própria organização não envia esse header.

curl -X POST "https://api.chargefy.io/v1/invoices/inv_2Th8gTm8USwKEyzo/issue_boleto" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_7Dk9mQ2vX5rT8pWN" \
  -H "Idempotency-Key: emitir-boleto-pedido-2026-001"

curl -X POST "https://api.chargefy.io/v1/invoices/inv_2Th8gTm8USwKEyzo/issue_boleto" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: emitir-boleto-pedido-2026-001"

{
  "id": "pi_JgEJanPt14Dbs46f",
  "object": "payment_intent",
  "...": "outros campos do Payment Intent",
  "amount": 14990,
  "currency": "brl",
  "invoice": "inv_2Th8gTm8USwKEyzo",
  "latest_charge": "ch_YFvU8E5yMkDgQ74c",
  "next_action": {
    "boleto_display_details": {
      "barcode": "23791966600000149903381286008296100211202300",
      "expires_at": "2026-11-01T23:59:59-03:00",
      "hosted_voucher_url": "https://meusite.com/boleto.pdf",
      "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
      "pdf": "https://meusite.com/boleto.pdf"
    },
    "type": "boleto_display_details"
  },
  "payment_method_types": [
    "boleto"
  ],
  "status": "requires_action"
}

{
  "error": {
    "code": "buyer_field_required",
    "message": "Informe o CPF ou CNPJ.",
    "param": "customer_document",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Invoice not found",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "A payment for this invoice is already in progress or completed",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_result_unconfirmed",
    "message": "The payment result is not confirmed yet. Do not submit the payment again.",
    "type": "api_error"
  }
}

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Emitir o primeiro boleto da fatura

Antes de emitir

Repetição e pagamentos em andamento

Chargefy for Platforms

​Antes de emitir

​Repetição e pagamentos em andamento

​Chargefy for Platforms

Antes de emitir

Repetição e pagamentos em andamento

Chargefy for Platforms