Pular para o conteúdo principal
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 = a moeda padrão da organização, 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.
array
Comissões de afiliados do pagamento avulso. Cada item contém affiliation (vínculo ativo) e affiliate_fee_rate (inteiro de 1 a 10000 pontos-base; 3000 significa 30%). Todos os percentuais incidem em paralelo sobre o que sua organização recebe antes das comissões de afiliados, depois da taxa de processamento e dos juros pagos pela organização. A soma vai até 10000. São até 8 afiliados em venda direta e 7 quando há taxa de plataforma, com no máximo 10 recebedores no pagamento. Vínculos, contas e recebedores repetidos são conferidos antes de aceitar a operação. Veja Comissões de afiliados.
integer
obrigatório
Valor base na menor unidade da moeda (centavos em brl) — inteiro positivo. O cadastro aceita valores positivos até o máximo indicado abaixo; 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.O teto depende da moeda. Em brl, o máximo é 999999999 na menor unidade. Acima do teto, a API retorna 400 amount_too_large com param e maximum_amount. Quando o valor já está associado a uma moeda, a resposta inclui currency.
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
Moeda do pagamento. Sem o campo, vale a moeda padrão da organização.Aceita hoje: brl. Maiúsculas valem como minúsculas (BRL é lido como brl); outra moeda retorna 400 com code: "unsupported_currency". Veja Moedas.
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

Um pagamento por pedido

Crie um Payment Intent por pedido, com a Idempotency-Key tirada do número do pedido, como payment-order-8f4c2a acima. Para tentar de novo, repita a requisição com a mesma chave: ela devolve o mesmo pagamento, inclusive quando a primeira requisição ainda está em andamento ou nunca respondeu (veja Idempotência). Uma chave nova cria outro pagamento para o mesmo pedido. Se a resposta vier em processing, sem next_action, o resultado com o banco ainda não é conhecido. Sem webhook cadastrado, acompanhe consultando o mesmo pagamento em GET /v1/payment-intents/:id até ele sair de processing. Se ele voltar a requires_payment_method com last_payment_error.code igual a connection_error, confirme de novo o mesmo pagamento.

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.

Erros de comissões de afiliados