Pular para o conteúdo
Pagamentos

Estornar cobrança

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

Devolve ao comprador o valor que resta de uma cobrança paga com cartão ou Pix; depois de processado, é irreversível. Com amountCents menor que o restante, o estorno é parcial: depende do contrato e responde 409 partial_refund_disabled quando indisponível; vários parciais podem somar até o total, um em andamento por vez. Sem amountCents, o comportamento é o de sempre (estorna o restante). O estorno parcial não gera o evento charge.refunded, que continua significando estorno total. Se o processador recusar (por exemplo, prazo de estorno encerrado), responde 409 refund_window_closed. Exige o header Idempotency-Key.

Parâmetros de caminho

Entram no próprio endereço, no lugar das chaves.

  • idstringobrigatório
    • tamanho mín. 1

Corpo da requisição

application/jsonobrigatório
  • reasonstringobrigatório
    • tamanho 3–500
  • amountCentsintegeropcional

    Valor a estornar em centavos. Omitido: estorna o valor restante. Menor que o restante: estorno parcial, disponível conforme o contrato (senão 409 partial_refund_disabled). Maior que o restante: 422 refund_exceeds_remaining.

    • mín. 1

Respostas

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

200Deu certoapplication/json

A cobrança depois do pedido de estorno. O status é o que o provedor confirmou (refunded quando o restante foi estornado; partially_refunded depois de um estorno parcial; paid enquanto o estorno está em andamento). Replay da Idempotency-Key traz idempotency_replay: true.

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