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
required
Valor base em centavos — inteiro positivo, mínimo 500 (R$ 5,00). Valor entre 1 e 499 retorna 400 com code: "amount_too_small". Quando o comprador paga juros de parcelamento, o amount retornado passa a ser o total cobrado e o valor original fica em amount_details.principal_amount.
​
string
default:"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
default:"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
default:"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
default:"brl"
Moeda em minúsculas. Padrão: brl.
​
string
Customer associado (cus_*). Obrigatório quando payment_method é enviado.
​
boolean
default:"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
default:"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.
​
boolean
true quando o comprador paga o acréscimo do parcelamento; false quando o lojista absorve o acréscimo (venda sem juros ao comprador). A taxa é definida no plano de parcelamento da organização. Quando omitido, usa a configuração da organização.
​
array
default:"[\"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 e do parcelamento escolhido — POST /v1/payment-previews usa o mesmo cálculo.
  • Parcelamento: payment_method_options omitido → 1 parcela; has_interest 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 é pending: o pagamento só está concluído quando o intent chegar a succeeded.

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.