Pular para o conteúdo principal
POST
Charge an Unpaid Subscription
Disponível só para contas liberadas para a política retry_then_unpaid, e só para assinaturas de cartão em unpaid. A cobrança usa o cartão salvo na assinatura e passa pelas mesmas verificações da renovação automática. Escolher os ciclos. cycles é obrigatório. Uma assinatura pode ter vários ciclos em aberto quando ficou unpaid por mais de um período.
  • current cobra um ciclo, o que cobre o dia de hoje, e perdoa os ciclos em aberto mais antigos.
  • all cobra todos os ciclos em aberto numa transação só, no valor do ciclo vezes o número de ciclos em aberto. A taxa repassada ao comprador incide sobre esse total.
Nos dois casos, a cobrança aprovada avança a assinatura no calendário original: uma assinatura que vence no dia 31 continua vencendo no último dia de cada mês. Ela volta para active quando o ciclo pago ainda cobre o momento em que a cobrança é aplicada; confira subscription.status na resposta. Com um ciclo em aberto, as duas opções cobram o mesmo. GET /v2/subscriptions/{id} devolve os ciclos em aberto em nextManualCharge: openCycles, o ciclo que cobre o dia de hoje (currentPeriodStart, currentPeriodEnd), o valor base de um ciclo (cycleAmount) e o de cobrar todos (allCyclesAmount), em centavos. A troca de plano agendada é aplicada antes da cobrança, então os dois valores já saem pelo preço do plano novo. A resposta e o subscription.renewed trazem cyclesCharged e cyclesForgiven (cycles_charged e cycles_forgiven no webhook). Cobrança recusada. A assinatura continua unpaid e sai o subscription.payment_failed. Depois de uma recusa, a próxima cobrança da mesma assinatura só é aceita após 24 horas. Quando o cartão é recusado em definitivo, a resposta é PAYMENT_METHOD_REPLACEMENT_REQUIRED, e o cartão precisa ser trocado antes de cobrar de novo. Cobrar os ciclos que você mostrou. Envie expected_period_start com o início do ciclo em aberto mais antigo que você mostrou ou confirmou, e expected_open_cycles com quantos ciclos em aberto você mostrou, normalmente o nextManualCharge.periodStart e o nextManualCharge.openCycles de GET /v2/subscriptions/{id}. Se outra cobrança (outra tela, outra integração) já encerrou o ciclo mais antigo, ou se um ciclo novo abriu depois da leitura, a resposta é 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED e nada é cobrado; leia a assinatura de novo para ver os ciclos em aberto agora. Sem os campos, são cobrados os ciclos em aberto no momento do pedido. Repetições. Envie idempotency_key para repetir com segurança: a mesma chave devolve o resultado do primeiro pedido em vez de cobrar de novo. A resposta SUBSCRIPTION_CHARGE_INDETERMINATE significa que a cobrança ainda não teve resultado: a assinatura continua unpaid e novas cobranças são recusadas enquanto ela estiver em aberto. Se ela se resolver como paga, esse pagamento não é aplicado à assinatura sozinho: novas cobranças respondem MANUAL_CHARGE_PENDING_RESOLUTION, para o mesmo ciclo nunca ser cobrado duas vezes, até o suporte resolver esse pagamento.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

id
string<uuid>
obrigatório

Public subscription id (UUID).

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Corpo

application/json
cycles
enum<string>
obrigatório

Which open cycles to charge. current charges the cycle that covers today and forgives the older open cycles; all charges every open cycle in one transaction. With one open cycle both charge the same.

Opções disponíveis:
current,
all
idempotency_key
string
Required string length: 1 - 255
expected_period_start
string<date-time>

Start of the oldest open cycle you showed or confirmed (nextManualCharge.periodStart from GET by id). When another charge already settled it, the request is refused with 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED and nothing is charged.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
expected_open_cycles
integer

Number of open cycles you showed or confirmed (nextManualCharge.openCycles from GET by id). When a new cycle opened since then, the request is refused with 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED and nothing is charged.

Intervalo obrigatório: 1 <= x <= 3660

Resposta

Success

success
boolean
obrigatório
requestId
string
obrigatório
data
object
obrigatório