Docs

Buscar na documentação

Guias, endpoints e eventos

Ir ao painel

Ações de cobrança

Todas escopo write.

Estornar um pagamento

Total ou parcial. amount_cents e reason obrigatórios.

curl -X POST "https://api.ribbo.app/v1/payments/pay_01J…/refund" \
  -H "Authorization: Bearer bk_..." -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1990, "reason": "cliente desistiu", "revoke": "none" }'
  • revoke: subscription (cancela a assinatura) | grant (revoga a concessão do pedido) | none (só devolve o dinheiro). Se omitido, revoga o acesso apropriado: fatura de assinatura cancela a assinatura; pedido avulso revoga a concessão. Mande "revoke": "none" para não revogar.
  • Se o estorno desfaz uma extensão/renovação, o tempo concedido é revertido automaticamente.
  • Se o estorno atinge uma fatura que financiou runway pré-pago, a resposta é 422 com {"requires_confirmation":"runway"}. Reenvie com "confirm_runway": true para confirmar.
  • Anti-duplo-estorno embutido. Emite payment.refunded.

Cancelar assinatura

curl -X POST "https://api.ribbo.app/v1/subscriptions/sub_01J…/cancel" \
  -H "Authorization: Bearer bk_..." -H "Content-Type: application/json" \
  -d '{ "reason": "a pedido", "at_period_end": true }'
  • Imediato (padrão, sem at_period_end): terminal e idempotente. 422 se houver um QR Pix ainda pagável. Emite subscription.canceled.
  • No fim do período ("at_period_end": true): o acesso continua até o fim do período pago e a assinatura não renova (cancel_at_period_end: true). É reversível:
curl -X POST "https://api.ribbo.app/v1/subscriptions/sub_01J…/cancel/undo" -H "Authorization: Bearer bk_..."

422 se não há cancelamento agendado. Emite subscription.updated.

Cobrar agora

Enfileira a cobrança do ciclo no cartão salvo. Resposta 202 { "ok": true, "message": "..." }. A tarefa respeita a data da cobrança: só cobra quando a próxima cobrança já venceu (ex.: uma renovação que ficou para trás). Se a data ainda não chegou, nada é cobrado; para receber antes do vencimento, use o link de renovação antecipada.

curl -X POST "https://api.ribbo.app/v1/subscriptions/sub_01J…/charge-now" -H "Authorization: Bearer bk_..."

409 se a assinatura não está em active, trialing ou past_due (o corpo traz o status) ou se as renovações da conta estão pausadas. Chamar duas vezes não cobra duas vezes.

A API cobra direto no cartão salvo. O painel da ribbo, ao contrário, nunca cobra o cartão: lá a cobrança manual e a troca de plano com cobrança geram um link de pagamento para o cliente.

Reagendar a próxima cobrança

Não cobra, só move a data. next_billing_at deve ser futuro (ISO-8601).

curl -X POST "https://api.ribbo.app/v1/subscriptions/sub_01J…/reschedule" \
  -H "Authorization: Bearer bk_..." -H "Content-Type: application/json" \
  -d '{ "next_billing_at": "2026-10-01T12:00:00Z" }'

Emite subscription.updated. Erros trazem code: 400 data_invalida/data_passada, 422 status (status não permite), 409 fatura_em_voo (cobrança ou QR Pix em aberto).

Remover cupom

Tira o cupom dos ciclos futuros. Resposta { "removed": <int> }.

curl -X POST "https://api.ribbo.app/v1/subscriptions/sub_01J…/remove-coupon" -H "Authorization: Bearer bk_..."