Pular para o conteúdo
Pagamentos

Criar cobrança

v1.0.0
POSThttps://api.staging.growthaisystem.com/api/v1/charges
  • ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escopospayments.write

Emite uma cobrança real ao comprador, com link de checkout (Pix e/ou cartão). Exige o header Idempotency-Key: repetir a mesma chave com o mesmo corpo devolve a mesma cobrança; com outro corpo, 409. Sem payer, o checkout pede os dados.

Corpo da requisição

application/jsonobrigatório
  • amountintegerobrigatório
    • faixa 1–100000000
  • descriptionstringobrigatório
    • tamanho 1–500
  • methodsstring[]opcional
    • itens 1–2
  • maxInstallmentsintegeropcional
    • faixa 1–12
  • expiresInHoursintegeropcional
    • faixa 1–720

  • Sem pagador, o checkout pede os dados.

    • namestringobrigatório
      • tamanho 2–120
    • emailstring (email)obrigatório
      • tamanho máx. 200
      • regex "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\…
    • taxIdstringobrigatório
      • regex "^(\\d{11}|[0-9A-Z]{12}\\d{2})$"
    • phonestringopcional
      • regex "^\\d{10,13}$"
  • externalReferencestringopcional
    • tamanho 1–120
    • chave string
    • valor string | number | boolean | null

    Uma destas formas

    • string
      • tamanho máx. 500
    • number
    • boolean

Respostas

10 respostas documentadas — o código, o que ele significa nesta rota e a forma do corpo.

200Deu certoapplication/json

A Idempotency-Key repetiu uma criação anterior com o mesmo corpo: devolve a MESMA cobrança, com idempotency_replay: true. Nada novo foi emitido.

V1ChargeEscrita

  • idstring
  • statusstring
    • um de"open""processing""pending""paid""failed""expired""canceled""refunded""partially_refunded""chargeback""reconciliation_required"
  • amountinteger

    Principal em centavos (BRL).

  • amountPaidinteger | null

    Bruto pago em centavos, com juros do comprador quando houver.

  • currency"BRL"
    • sempre "BRL"
  • descriptionstring
  • methodstring | null

    Pix, cartão de crédito (1–12x), débito à vista ou BolePix (boleto com Pix).

    • um de"pix""card""debit""bolepix"
  • installmentsinteger | null
  • sourcestring
    • um de"link""api""crm_deal""manual""subscription"
  • paymentLinkIdstring | null
  • externalReferencestring | null
    • chave string
    • valor string | number | boolean | null

    Uma destas formas

    • string
    • number
    • boolean
    • namestring | null
    • emailstring | null
    • taxIdLast4string | null
    • phonestring | null

      Telefone do pagador, só dígitos, como foi informado.

  • contactIdstring | null

    Contato do CRM que pagou; null quando a cobrança não está ligada a um contato.

  • opportunityIdstring | null

    Negócio do CRM de origem; null fora do CRM.

  • payerIdstring | null

    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_…) derivado do documento ou do e-mail, que não revela nenhum dos dois. null sem nenhum dado do pagador.

  • checkoutUrlstring (uri)
  • checkoutExpiresAtstring
  • platformFeeinteger | null

    Taxa da plataforma esperada em centavos (null antes do pagamento).

  • netAmountinteger | null

    Líquido previsto ao recebedor em centavos.

  • reconciliationstring
    • um de"pending""matched""divergent""not_applicable"
  • createdAtstring
  • paidAtstring | null
  • refundedAtstring | null
  • subscriptionIdstring | null

    Assinatura de que esta cobrança é a fatura do ciclo; null fora de assinatura.

  • dueDatestring | null

    Vencimento (YYYY-MM-DD): o do BolePix, o da parcela de proposta ou o da fatura de assinatura; null sem prazo.

  • overdueboolean

    Passou o dueDate (horário de Brasília) sem pagamento. Cartão parcelado nunca fica vencido: o comprador já pagou.

  • amountRefundedinteger

    Total estornado e confirmado pelo processador, em centavos.

  • O crédito na conta, pela agenda do processador. null antes do pagamento ou enquanto a agenda não chegou.

    • statusstring

      pending_credit: pago, nada creditado ainda; partially_credited: parte das parcelas já caiu; credited: tudo creditado.

      • um de"pending_credit""partially_credited""credited"
    • installmentsinteger

      Parcelas de crédito na agenda do processador (1 no Pix e no cartão à vista).

    • grossAmountinteger

      Bruto das parcelas na agenda, em centavos.

    • platformFeeinteger | null

      Taxas REAIS da agenda do processador, em centavos (positivo). null enquanto o processador não informou.

    • netAmountinteger

      Líquido real: grossAmount − platformFee.

    • creditedAmountinteger

      Já creditado na conta, em centavos.

    • pendingAmountinteger

      Ainda a creditar, em centavos.

    • nextCreditDatestring | null

      Próxima data prevista de crédito (YYYY-MM-DD); null quando tudo já caiu.

    • lastCreditAtstring | null

      Último crédito (ISO); null antes do primeiro.

  • idempotency_replaytruepode faltar
    • sempre true