Pagamentos
Criar um pagamento
Cria um Payment Intent para cartão ou Pix, com confirmação opcional, método salvo, parcelamento, metadata, repasse de taxa e resposta completa.
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.
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.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.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"].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.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.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.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.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: {}.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.Opções por método de pagamento. Atualmente só
credit_card. Quando omitido, o
cartão fica em 1 parcela.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.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").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_confirmationquando você enviapayment_methodou 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_amounteamount) é computado no servidor a partir deamount,has_surcharge, do parcelamento escolhido e de quem paga o juro —POST /v1/payment-previewsusa o mesmo cálculo.amount_details.amount = principal_amount + surcharge_amount + installment_interest_amountcominterest_payer: "buyer";principal_amount + surcharge_amountcominterest_payer: "organization".- Parcelamento:
payment_method_optionsomitido → 1 parcela;interest_payeromitido usa a configuração da organização.
Criar e confirmar um Pix na mesma chamada
Useconfirm: 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 aIdempotency-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.
