Pagamentos

A API de pagamentos é um gateway de cobrança completo: você emite uma cobrança, envia o link de checkout ao comprador e recebe um evento quando ela é paga. Tudo o que a tela de Pagamentos faz com uma cobrança, a sua integração também faz.

O que é

• Cobranças por Pix, cartão de crédito em 1 a 12 parcelas ou débito à vista, com autenticação 3DS no checkout.
• Links de pagamento: uma URL que qualquer pessoa pode pagar, quantas vezes quiser, até você encerrar ou o prazo vencer.
• Assinaturas mensais sobre planos: uma fatura por mês ao comprador, com débito automático no cartão quando ele autoriza.
• Estorno de cobrança paga com cartão ou Pix: do valor restante ou, quando o contrato permite, de parte dele.
• Saldo disponível e pendente da sua conta de recebimento.
• Repasses e contestações, somente leitura: o saque e a defesa são feitos pelo painel.

Antes da primeira chamada

O workspace precisa ter o módulo de Pagamentos liberado e a conta de recebimento ativa. Sem o módulo, a emissão responde 403 module_not_enabled; com o cadastro da conta ainda em análise, responde 409 merchant_not_active. O estado da conta aparece na tela de Pagamentos do workspace. Se os pagamentos estiverem desligados no ambiente, as escritas respondem 503 disabled: tente mais tarde.

Escopos

Uma chave só de leitura serve para painéis e conciliação. Dê payments.write só à integração que de fato emite cobranças.

Criar uma cobrança

POST /api/v1/charges emite uma cobrança real. O header Idempotency-Key é obrigatório (até 200 caracteres): sem ele a resposta é 400 idempotency_key_required. Use um valor por operação de negócio, por exemplo o id do pedido no seu sistema.

curl -X POST https://api.growthaisystem.com/api/v1/charges \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: pedido-2026-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Mentoria individual, sessão de outubro",
    "methods": ["pix", "card"],
    "maxInstallments": 3,
    "expiresInHours": 72,
    "externalReference": "pedido-2026-1042",
    "payer": { "name": "Maria Souza", "email": "maria.souza@exemplo.com", "taxId": "52998224725" }
  }'

A resposta 201 traz a cobrança com o checkoutUrl. É esse endereço que você envia ao comprador: ele escolhe Pix ou cartão, paga e a cobrança muda para paid. O checkout aparece com a marca do workspace que emitiu a cobrança.

• amount: principal em centavos (obrigatório).
• description: o que o comprador vê no checkout (1 a 500 caracteres).
• methods: pix, card (crédito) ou debit (débito à vista, sempre 1 parcela). Crédito e débito não vão juntos na mesma cobrança: 400. Sem o campo, valem os padrões do workspace.
• maxInstallments: teto de parcelas no cartão (1 a 12).
• expiresInHours: validade do checkout (1 a 720 horas).
• externalReference e metadata: seus identificadores, devolvidos em toda leitura e em todo evento.

Cobrança sem pagador

O payer é opcional. Sem ele, o próprio checkout pede nome, e-mail e CPF ou CNPJ ao comprador. Use isso quando você não tem os dados de quem vai pagar.

Repetir com a mesma chave

Repetir o mesmo corpo com a mesma Idempotency-Key não emite nada novo: a resposta é 200 com a mesma cobrança e idempotency_replay: true. A mesma chave com um corpo diferente responde 409 idempotency_conflict.

Consultar e estornar

GET /api/v1/charges/{id} lê uma cobrança. A leitura não consulta o processador; o estado muda sozinho quando o pagamento é confirmado.

Listar cobranças

GET /api/v1/charges pagina por cursor, da mais nova para a mais antiga (limit de 1 a 100, padrão 25). Filtros: status, method, paymentLinkId, externalReference, o contato, o negócio e o pagador (contactId, opportunityId, payerId), a criação (createdFrom/createdTo), o pagamento (paidFrom/paidTo) e a alteração (updatedFrom, para ler só o que mudou desde a última vez), todos em ISO-8601. Com externalReference ou com um payerId opaco (pyr_…), uma página pode vir com menos itens que o limit e ainda ter nextCursor: siga o cursor até null.

Estornar

POST /api/v1/charges/{id}/refund devolve ao comprador o valor que resta de uma cobrança paga com cartão ou Pix. O corpo leva o motivo (reason) e, se quiser, o valor (amountCents). O header Idempotency-Key é obrigatório.

curl -X POST https://api.growthaisystem.com/api/v1/charges/0b8f7c2e-5d4a-4e7b-9c1a-2f3e4d5c6b7a/refund \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: estorno-pedido-2026-1042" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cliente desistiu da compra"}'

• Sem amountCents, estorna o valor restante, como sempre foi. Com um valor menor que o restante, o estorno é parcial: depende do contrato e responde 409 partial_refund_disabled quando indisponível (faça então o estorno do restante). Vários parciais podem somar até o total, um de cada vez.
• Valor maior que o restante: 422 refund_exceeds_remaining.
• Cobrança não paga, já estornada por inteiro ou de uma forma que não estorna (como BolePix): 409 refund_not_allowed.
• Um estorno já em andamento: 409 refund_in_flight.
• O processador recusou (por exemplo, a liquidação já começou): 409 refund_window_closed.
• A resposta traz o estado confirmado pelo processador: refunded quando o restante foi estornado, partially_refunded depois de um parcial, paid enquanto o estorno anda. O evento charge.refunded avisa só o estorno total; o parcial não gera evento. Depois de processado, o estorno é irreversível.

Links de pagamento

POST /api/v1/payment-links publica um link (com Idempotency-Key), e a url da resposta já pode ser divulgada. GET /api/v1/payment-links lista os links, com filtro opcional por status (active ou closed). Cada pagamento feito por um link vira uma cobrança com o paymentLinkId preenchido.

curl -X POST https://api.growthaisystem.com/api/v1/payment-links \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: workshop-nov-2026" \
  -H "Content-Type: application/json" \
  -d '{"title":"Workshop de vendas, turma de novembro","amount":29700,"methods":["pix","card"],"maxInstallments":6}'

Assinaturas

Uma assinatura cobra o mesmo valor todo mês, a partir de um plano. Toda escrita exige o header Idempotency-Key, com as mesmas regras da cobrança: repetir a chave com o mesmo corpo devolve o mesmo recurso e idempotency_replay: true; com outro corpo, 409 idempotency_conflict.

Planos

POST /api/v1/plans cria um plano mensal com name e amount em centavos. O valor de um plano é imutável: preço novo é um plano novo. Um plano arquivado (active: false) não aceita assinatura nova, e as que já existem continuam. GET /api/v1/plans lista os planos, com filtro opcional por active.

Criar uma assinatura

curl -X POST https://api.growthaisystem.com/api/v1/subscriptions \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Idempotency-Key: cliente-1042-mensal" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "paymentMethod": "card",
    "billingMode": "automatic_card",
    "startDate": "2026-10-05",
    "externalReference": "cliente-1042",
    "payer": { "name": "Maria Souza", "email": "maria.souza@exemplo.com", "taxId": "52998224725" }
  }'

• startDate é o primeiro vencimento (YYYY-MM-DD, hoje ou depois, no horário de Brasília) e fixa o dia de cobrança. Em mês mais curto, a fatura vence no último dia do mês. Uma data no passado responde 422 start_date_past.
• payer é obrigatório, com CPF ou CNPJ. paymentMethod é pix ou card.
• O valor do plano fica congelado na assinatura. Nada é cobrado antes do vencimento: com startDate igual a hoje, a fatura do primeiro mês já vem na resposta; depois, uma fatura nova nasce a cada vencimento.
• sendEmail (padrão true) avisa o comprador por e-mail com o link da fatura.

Faturas

Cada fatura é uma cobrança: source: "subscription" e o subscriptionId preenchido. Ela aparece em GET /api/v1/charges, dispara os mesmos eventos charge.* e tem o próprio checkoutUrl. GET /api/v1/subscriptions/{id} traz as 24 faturas mais recentes em invoices, com o status de pagamento de cada mês.

Pausar, reativar, cancelar e trocar de plano

• POST /subscriptions/{id}/pause (corpo {}): para de gerar faturas e de cobrar o cartão. Faturas já emitidas continuam pagáveis.
• POST /subscriptions/{id}/resume (corpo {}): volta a cobrar. Os meses parados não são cobrados; o próximo vencimento é o primeiro a partir de hoje.
• POST /subscriptions/{id}/cancel: encerra de vez. Uma assinatura cancelada não volta: 409 subscription_canceled.
• POST /subscriptions/{id}/change-plan: o plano e o valor novos valem do próximo ciclo em diante, sem pro-rata. O mesmo plano responde 409 same_plan; plano arquivado, 409 plan_inactive.

Repetir uma ação com a mesma Idempotency-Key devolve a assinatura no estado atual, sem efeito novo.

Débito automático no cartão

Com billingMode: "automatic_card" (só com paymentMethod: "card"), o comprador paga a primeira fatura no checkout e pode autorizar ali o débito mensal do cartão. A autorização é sempre dele, nunca da integração. Se o débito de um mês for recusado, ou se o comprador revogar a autorização, a assinatura é pausada sozinha (pauseReason payment_refused ou card_revoked). O campo automaticCard mostra o estado da autorização, a bandeira e o final do cartão, e nunca o cartão em si. Trocar para um plano de outro valor exige uma autorização nova.

Saldo

GET /api/v1/balance lê o saldo available e o pending da conta de recebimento, em centavos. Quando o processador não responde (ou a conta ainda não está ativa), a resposta vem com unavailable: true e os valores em null. Nunca é um zero inventado: trate null como "não sei agora" e tente de novo mais tarde.

Recebimentos

Para conciliar o que o comprador pagou com o que caiu na sua conta, a cobrança traz o pagador amarrado ao CRM, o vencimento, o estornado e o crédito real. As parcelas, a agenda e os pagadores têm rotas próprias, todas de leitura (payments.read).

Pagador e CRM

• contactId e opportunityId: o contato e o negócio do CRM ligados à cobrança (null fora do CRM).
• payerId: um id estável do pagador, o mesmo em todas as cobranças dele. crm_<contactId> quando há contato; senão um código opaco (pyr_…) que não revela o documento nem o e-mail.
• payer.phone: o telefone informado, só dígitos. O documento continua saindo só como taxIdLast4.

Crédito e parcelas

O status diz se o comprador pagou; o settlement diz se o dinheiro já caiu na conta, pela agenda do processador: pending_credit, partially_credited ou credited, com a taxa e o líquido reais, o creditado, o a creditar e a próxima data de crédito. No cartão parcelado o comprador paga tudo de uma vez e o processador credita parcela a parcela, mês a mês: por isso cartão parcelado nunca fica vencido.

dueDate é o vencimento (BolePix, parcela de proposta ou fatura de assinatura) e overdue vira true quando ele passa, no horário de Brasília, sem pagamento. amountRefunded soma os estornos confirmados.

GET /api/v1/charges/{id}/installments lista as parcelas de crédito da cobrança: valor, taxa e líquido de cada uma, a data prevista (estimatedCreditDate) e a do crédito (creditDate, null até entrar).

Agenda de recebíveis

GET /api/v1/receivables é o fluxo de caixa: cada parcela a creditar (ou já creditada) num período pela data prevista, creditFrom a creditTo (YYYY-MM-DD, até 366 dias). Filtros por status, kind e chargeId. Estornos e contestações entram com valor negativo.

curl "https://api.growthaisystem.com/api/v1/receivables?creditFrom=2026-11-01&creditTo=2026-11-30" \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI"

Pagadores

GET /api/v1/payers lista os pagadores, com o mesmo id do payerId das cobranças, e os totais em centavos: cobrado, pago, estornado e em aberto.

Repasses

Um repasse (saque) transfere o saldo da conta de recebimento para a conta de destino cadastrada. A API só lê os repasses: o pedido de saque é feito pelo painel. O status é o que o processador confirmou; unknown quer dizer que a resposta foi ambígua e o repasse está sendo conferido, nunca reenviado sozinho. Quando o banco de destino devolve o valor, o repasse fica partially_returned ou returned, com o valor em returnedCents. Uma falha traz o motivo em failureReason.

A conta de destino vem resumida (bankName e accountLast4), nunca completa.

Listar repasses

GET /api/v1/payouts pagina por cursor, do mais novo para o mais antigo (limit de 1 a 100, padrão 20), com filtro opcional por status. GET /api/v1/payouts/{id} lê um repasse. As duas leituras exigem payments.read e o módulo de Pagamentos liberado no workspace (senão, 403 module_not_enabled).

Contestações

Uma contestação é um chargeback (cartão) ou uma infração Pix aberta pelo pagador no banco dele. A decisão é do processador: o outcome diz se o valor voltou ao pagador (upheld), se a decisão foi favorável a você (dismissed) ou se ela foi encerrada sem decisão (withdrawn). A defesa é enviada pelo painel, antes do deadlineAt; a API só mostra a situação dela em responseStatus, nunca o texto.

Listar contestações

GET /api/v1/disputes traz primeiro as abertas, pelo prazo de resposta, e depois as concluídas, da mais recente para a mais antiga (limit de 1 a 100, padrão 20, filtro opcional por status). GET /api/v1/disputes/{id} acrescenta a linha do tempo (timeline) informada pelo processador; na lista ela vem vazia. As duas leituras exigem payments.read e o módulo de Pagamentos liberado (senão, 403 module_not_enabled).

Webhooks de cobrança

A assinatura é a mesma de qualquer webhook da API (POST /api/v1/webhooks, com o mesmo envelope e a mesma assinatura HMAC). Assinar os eventos charge.* exige o escopo payments.read, além de webhooks.manage.

Webhooks de assinatura

O data é a assinatura com os mesmos campos de GET /subscriptions/{id}, sem as invoices. A troca de plano não gera evento. O pagamento de cada mês chega pelos eventos charge.* da fatura. Assinar exige payments.read.

Valores

• Todo valor é inteiro em centavos, sempre em BRL: 15000 é R$ 150,00. A API não aceita casas decimais.
• amount é o principal; amountPaid é o bruto pago, que inclui os juros do parcelamento quando o comprador paga os juros.
• platformFee e netAmount são previsões calculadas no pagamento. Elas viram valor conferido quando a conciliação com o processador fecha (campo reconciliation: pending, matched, divergent ou not_applicable).

Mudanças de compatibilidade

A cobrança ganhou campos (contactId, opportunityId, payerId, payer.phone, dueDate, overdue, amountRefunded e settlement). Nos eventos charge.* só entram os quatro primeiros. Nenhum campo antigo mudou.

Alguns enums da cobrança ganharam valores. Se a sua integração valida esses campos com uma lista fechada, acrescente:

• method (e methods nos links): debit, débito à vista.
• source: subscription, a fatura de uma assinatura. A cobrança ganhou também o campo subscriptionId (null fora de assinatura).
• method (e methods nos links), só na leitura: bolepix, boleto com Pix, emitido pelo painel. Criar cobrança ou link pela API continua aceitando só pix, card e debit.
• status: partially_refunded, depois de um estorno parcial.

O estorno ganhou o campo opcional amountCents. Sem ele, o comportamento é o de antes: estorna o valor restante. Pix passou a ser estornável.