Skip to main content
Cria um payment_intent, o objeto que representa o ciclo de vida de uma cobrança. Para cobrar um cartão salvo, informe customer, payment_method e confirme o intent. Para Pix, crie o intent com payment_method_types: ["pix"] e confirme para receber o QR code em next_action. Use payment_intent como objeto canônico da cobrança. Ele pode ser criado diretamente pela API, por uma invoice ou por uma checkout session. Não use uma checkout session como chave de idempotência de pagamento nem como ledger financeiro. Só amount é obrigatório. Todo o resto tem padrão: currency = brl, payment_method_types = ["credit_card"], capture_method = automatic, confirm = false e parcelamento em 1x.
Para um exemplo de ponta a ponta com Pix, cartão salvo, assinatura e webhooks, veja Cobrar com Payment Intents.
​
integer
obrigatório
Valor base em centavos — inteiro positivo. O cadastro aceita qualquer valor positivo; a confirmação valida o mínimo da cobrança pelo plano efetivo e pelo método. Quando o comprador paga os juros do parcelamento (interest_payer: "buyer"), o amount retornado passa a ser o total cobrado e o valor original fica em amount_details.principal_amount. Quando a organização paga (interest_payer: "organization"), o amount continua igual ao valor base e o juro aparece só em installment_interest_amount.
​
string
padrão:"automatic"
automatic ou manual. Padrão: automatic. Use manual para autorizar cartão agora e capturar depois com POST /v1/payment-intents/:id/capture. manual só é suportado com payment_method_types: ["credit_card"].
​
boolean
padrão:"false"
Se true, cria e confirma a cobrança na mesma chamada. Padrão: false — o intent nasce sem confirmar; confirme depois com POST /v1/payment-intents/:id/confirm.
​
string
padrão:"automatic"
automatic ou manual. O valor é registrado no objeto como a estratégia de confirmação. Ele não substitui confirm: quando confirm é false, inicie a cobrança depois pelo endpoint /confirm.
​
string
padrão:"brl"
Moeda em minúsculas. Padrão: brl.
​
string
Customer associado (cus_*). Obrigatório quando payment_method é enviado.
​
boolean
padrão:"false"
Quando true, o comprador cobre a taxa da organização: o total é acrescido do repasse (amount_details.surcharge_amount) para que a organização receba líquido o amount informado. Exige exatamente um payment_method_types. Use POST /v1/payment-previews para exibir os totais antes de criar o intent. Padrão: false.
​
object
Pares string → string para correlacionar o intent com seu sistema. É opcional e a Chargefy não usa suas chaves para tomar decisões de negócio. Aceita até 50 chaves; cada chave tem até 40 caracteres e cada valor, até 500. Chaves aceitam letras, números, _, - e .. Objetos aninhados não são aceitos. Padrão: {}.
​
string
Payment method salvo (pm_*). Exige customer (enviar sem customer retorna 400) e credit_card em payment_method_types; o cartão deve pertencer ao customer informado. Quando informado, o intent nasce em requires_confirmation.
​
object
Opções por método de pagamento. Atualmente só credit_card. Quando omitido, o cartão fica em 1 parcela.
​
integer
padrão:"1"
Número de parcelas de cartão, de 1 a 12. O máximo também respeita o valor mínimo por parcela. Quando omitido, usa 1.
​
string
Quem paga o juro do parcelamento: buyer soma o juro ao total cobrado do comprador; organization mantém o total do comprador igual ao valor à vista e desconta o juro do líquido da organização. O valor do juro é definido pelo plano de parcelamento da organização e aparece em installment_interest_amount nos dois casos. Quando omitido, usa a configuração da organização. has_interest foi removido: enviá-lo retorna 400 com param apontando o campo e a mensagem has_interest was removed; use interest_payer ("buyer" | "organization").
​
array
padrão:"[\"credit_card\"]"
Métodos permitidos no create direto. Aceita credit_card e pix. Padrão: ["credit_card"]. Boleto é criado por checkout hospedado ou invoice.

​
O que a Chargefy resolve sozinha

  • Status inicial: requires_confirmation quando você envia payment_method ou quando o intent é só Pix (payment_method_types: ["pix"]); caso contrário, requires_payment_method.
  • client_secret é gerado na criação.
  • amount_details (principal_amount, surcharge_amount, installment_interest_amount e amount) é computado no servidor a partir de amount, has_surcharge, do parcelamento escolhido e de quem paga o juro — POST /v1/payment-previews usa o mesmo cálculo. amount_details.amount = principal_amount + surcharge_amount + installment_interest_amount com interest_payer: "buyer"; principal_amount + surcharge_amount com interest_payer: "organization".
  • Parcelamento: payment_method_options omitido → 1 parcela; interest_payer omitido usa a configuração da organização.

​
Criar e confirmar um Pix na mesma chamada

Use confirm: true para receber next_action sem fazer uma segunda chamada. O status comum é requires_action: o pagamento só está concluído quando o intent chegar a succeeded.
Pix com confirmação imediata
200
400
401

Objeto Payment Intent

Todos os campos da resposta, estados, enums e timestamps.

Confirmar depois

Cartão e Pix quando confirm foi omitido ou enviado como false.