spolly
Entrar no painel
Índice

(13) Referência

Referência dos eventos

Todos os eventos, com o envelope, o objeto de cada um e um exemplo, gerados dos esquemas.

O envelope

O corpo de cada webhook que o Spolly Payments envia ao comerciante. Chega assinado no cabeçalho Spolly-Signature: t=<tempo>,v1=<hmac-sha256 de '<t>.<corpo>'>. A entrega pode repetir-se (as retentativas e o reenvio manual no painel levam o mesmo id): deduplicar pelo id.

Todos os eventos têm a mesma forma por fora; o que muda é o tipo e o objeto em data.object. Como receber e verificar está em Webhooks.

idtexto · obrigatório
Identificador do evento. É por ele que se deduplica.padrão ^evt_
typetexto · obrigatório
um de: checkout.session.expired, payment.failed, payment.succeeded, payout.failed, payout.paid, refund.created, subscription.cancelled, subscription.created, subscription.past_due, subscription.renewed
created_attexto (data e hora) · obrigatório
modetexto · obrigatório
um de: test, live
merchant_idtexto · obrigatório
padrão ^mer_
api_versiontexto · obrigatório
padrão ^\d{4}-\d{2}-\d{2}$
dataobjeto · obrigatório
data.objectobjeto · obrigatório

Os tipos

checkout.session.expired

Uma sessão chegou ao fim do prazo sem ser paga.

data.object é um checkout_session:

idtexto · obrigatório
padrão ^cs_
object"checkout_session" · obrigatório
statustexto · obrigatório
um de: open, complete, expired
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
expires_attexto (data e hora) · obrigatório
metadatametadata · obrigatório
Os metadados que o comerciante pôs na sessão, devolvidos tal como vieram.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de checkout.session.expired
{
  "id": "evt_01JA9X8Y7Z",
  "type": "checkout.session.expired",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "cs_01JA9C",
      "object": "checkout_session",
      "status": "expired",
      "amount": {
        "amount": 1500000,
        "currency": "AOA"
      },
      "expires_at": "2026-12-01T10:14:00Z",
      "metadata": {
        "order_id": "1042"
      }
    }
  }
}

payment.failed

Uma tentativa de pagamento falhou (recusada, ou o tempo acabou). A sessão continua aberta para outra tentativa.

data.object é um payment:

idtexto · obrigatório
padrão ^pay_
object"payment" · obrigatório
checkout_session_idtexto · obrigatório
padrão ^cs_
statustexto · obrigatório
um de: succeeded, failed
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
feemoney · obrigatório
A taxa da Spolly.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
netmoney · obrigatório
O que fica no saldo do comerciante: amount menos fee.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
methodtexto · obrigatório
Multicaixa Express, referência, BAI Paga, cartão (Stripe).um de: mcx, reference, baipaga, card
failure_reasontexto
Só nos falhados: a razão, em português, para mostrar ao comerciante.
created_attexto (data e hora) · obrigatório
metadatametadata · obrigatório
Os metadados que o comerciante pôs na sessão, devolvidos tal como vieram.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de payment.failed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payment.failed",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "pay_01JA9P",
      "object": "payment",
      "checkout_session_id": "cs_01JA9C",
      "status": "failed",
      "amount": {
        "amount": 1500000,
        "currency": "AOA"
      },
      "fee": {
        "amount": 37500,
        "currency": "AOA"
      },
      "net": {
        "amount": 1462500,
        "currency": "AOA"
      },
      "method": "mcx",
      "created_at": "2026-11-30T10:14:58Z",
      "metadata": {
        "order_id": "1042"
      },
      "failure_reason": "O comprador recusou o pagamento na aplicação Multicaixa Express."
    }
  }
}

payment.succeeded

Um pagamento ficou confirmado pelo gateway. É o evento que marca a encomenda como paga.

data.object é um payment:

idtexto · obrigatório
padrão ^pay_
object"payment" · obrigatório
checkout_session_idtexto · obrigatório
padrão ^cs_
statustexto · obrigatório
um de: succeeded, failed
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
feemoney · obrigatório
A taxa da Spolly.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
netmoney · obrigatório
O que fica no saldo do comerciante: amount menos fee.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
methodtexto · obrigatório
Multicaixa Express, referência, BAI Paga, cartão (Stripe).um de: mcx, reference, baipaga, card
failure_reasontexto
Só nos falhados: a razão, em português, para mostrar ao comerciante.
created_attexto (data e hora) · obrigatório
metadatametadata · obrigatório
Os metadados que o comerciante pôs na sessão, devolvidos tal como vieram.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de payment.succeeded
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payment.succeeded",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "pay_01JA9P",
      "object": "payment",
      "checkout_session_id": "cs_01JA9C",
      "status": "succeeded",
      "amount": {
        "amount": 1500000,
        "currency": "AOA"
      },
      "fee": {
        "amount": 37500,
        "currency": "AOA"
      },
      "net": {
        "amount": 1462500,
        "currency": "AOA"
      },
      "method": "mcx",
      "created_at": "2026-11-30T10:14:58Z",
      "metadata": {
        "order_id": "1042"
      }
    }
  }
}

payout.failed

Um saque foi recusado, e o valor voltou ao saldo disponível.

Um saque do saldo disponível para a conta bancária verificada do comerciante (cartões 6.2 e 6.3). Só existe em produção. payout.paid sai quando a equipa marca a transferência como feita, com o comprovativo; payout.failed sai quando a equipa recusa o saque, e o valor volta ao saldo disponível.

data.object é um payout:

idtexto · obrigatório
padrão ^po_
object"payout" · obrigatório
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
statustexto · obrigatório
um de: paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
Exemplo de payout.failed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payout.failed",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "po_01JA9F",
      "object": "payout",
      "amount": {
        "amount": 5000000,
        "currency": "AOA"
      },
      "status": "failed",
      "failure_reason": "O IBAN indicado foi recusado pelo banco.",
      "created_at": "2026-12-09T08:00:00Z"
    }
  }
}

payout.paid

Um saque foi transferido para a tua conta bancária.

Um saque do saldo disponível para a conta bancária verificada do comerciante (cartões 6.2 e 6.3). Só existe em produção. payout.paid sai quando a equipa marca a transferência como feita, com o comprovativo; payout.failed sai quando a equipa recusa o saque, e o valor volta ao saldo disponível.

data.object é um payout:

idtexto · obrigatório
padrão ^po_
object"payout" · obrigatório
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
statustexto · obrigatório
um de: paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
Exemplo de payout.paid
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payout.paid",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "po_01JA9O",
      "object": "payout",
      "amount": {
        "amount": 5000000,
        "currency": "AOA"
      },
      "status": "paid",
      "paid_at": "2026-12-10T15:00:00Z",
      "created_at": "2026-12-09T08:00:00Z"
    }
  }
}

refund.created

Um estorno ficou aceite (pendente ou já devolvido).

data.object é um refund:

idtexto · obrigatório
padrão ^re_
object"refund" · obrigatório
payment_idtexto · obrigatório
padrão ^pay_
amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
statustexto · obrigatório
um de: pending, succeeded
reasontexto
created_attexto (data e hora) · obrigatório
Exemplo de refund.created
{
  "id": "evt_01JA9X8Y7Z",
  "type": "refund.created",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "re_01JA9R",
      "object": "refund",
      "payment_id": "pay_01JA9P",
      "amount": {
        "amount": 500000,
        "currency": "AOA"
      },
      "status": "succeeded",
      "reason": "Devolução parcial a pedido do cliente.",
      "created_at": "2026-12-02T09:00:00Z"
    }
  }
}

subscription.cancelled

Uma subscrição foi cancelada.

Uma subscrição (cartões 8.1 a 8.4). Nasce do primeiro pagamento de uma sessão criada com kind subscription; cada ciclo seguinte é um pagamento normal, com o seu payment.succeeded e o seu recibo. As do Multicaixa Express, da referência e do BAI Paga renovam por um link de pagamento que o Spolly Payments manda ao cliente antes do fim do ciclo; as de cartão renovam sozinhas pelo Stripe.

data.object é um subscription:

idtexto · obrigatório
padrão ^sub_
object"subscription" · obrigatório
statustexto · obrigatório
active: em vigor. past_due: o ciclo acabou sem o seguinte pago, e a tolerância corre (o acesso mantém-se; ainda se paga até à data do aviso). cancelled: terminada a pedido. expired: terminada sem pedido, por falta de pagamento ou porque os ciclos contratados acabaram (end_reason diz qual).um de: active, past_due, cancelled, expired
amountmoney · obrigatório
O preço de cada ciclo.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos mensais e maiores renovam no dia do mês do primeiro pagamento (o dia-âncora): quem pagou a 31 renova a 28 em fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
Os ciclos contratados; null renova até ser cancelada.mínimo 1
cycleinteiro · obrigatório
O ciclo em vigor. O primeiro é o 1.mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
Até quando o ciclo em vigor está pago.
methodtexto · obrigatório
O método do próximo ciclo. O cliente troca-o na página dele, entre os métodos locais.um de: mcx, reference, baipaga, card
cancel_at_period_endbooleano · obrigatório
true quando o cancelamento foi pedido para o fim do ciclo: a subscrição continua active até current_period_end e não renova.
cancelled_attexto (data e hora)
Quando o cancelamento foi pedido.
cancelled_bytexto
Quem pediu o cancelamento: o cliente, na página dele, ou o comerciante, pela API.um de: customer, merchant
ended_attexto (data e hora)
Quando terminou (só em cancelled e expired).
end_reasontexto
Porque terminou: requested (alguém cancelou), unpaid (a tolerância acabou sem pagamento), completed (os ciclos contratados acabaram).um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
A sessão que a criou.padrão ^cs_
latest_payment_idtexto
No subscription.created e no subscription.renewed, o pagamento do ciclo.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadatametadata · obrigatório
Os metadados da sessão que a criou.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de subscription.cancelled
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.cancelled",
  "created_at": "2026-12-15T12:00:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "sub_01JA9S",
      "object": "subscription",
      "status": "active",
      "amount": {
        "amount": 990000,
        "currency": "AOA"
      },
      "interval": "month",
      "cycles": 12,
      "cycle": 1,
      "current_period_start": "2026-11-30T09:12:00Z",
      "current_period_end": "2026-12-30T09:12:00Z",
      "method": "reference",
      "cancel_at_period_end": true,
      "checkout_session_id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
      "customer": {
        "email": "cliente@exemplo.ao",
        "name": "Ana Domingos",
        "phone": "+244923000000"
      },
      "metadata": {
        "plano": "pro"
      },
      "cancelled_at": "2026-12-15T12:00:00Z",
      "cancelled_by": "customer"
    }
  }
}

subscription.created

Uma sessão em modo subscrição foi paga, e a subscrição começou.

Uma subscrição (cartões 8.1 a 8.4). Nasce do primeiro pagamento de uma sessão criada com kind subscription; cada ciclo seguinte é um pagamento normal, com o seu payment.succeeded e o seu recibo. As do Multicaixa Express, da referência e do BAI Paga renovam por um link de pagamento que o Spolly Payments manda ao cliente antes do fim do ciclo; as de cartão renovam sozinhas pelo Stripe.

data.object é um subscription:

idtexto · obrigatório
padrão ^sub_
object"subscription" · obrigatório
statustexto · obrigatório
active: em vigor. past_due: o ciclo acabou sem o seguinte pago, e a tolerância corre (o acesso mantém-se; ainda se paga até à data do aviso). cancelled: terminada a pedido. expired: terminada sem pedido, por falta de pagamento ou porque os ciclos contratados acabaram (end_reason diz qual).um de: active, past_due, cancelled, expired
amountmoney · obrigatório
O preço de cada ciclo.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos mensais e maiores renovam no dia do mês do primeiro pagamento (o dia-âncora): quem pagou a 31 renova a 28 em fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
Os ciclos contratados; null renova até ser cancelada.mínimo 1
cycleinteiro · obrigatório
O ciclo em vigor. O primeiro é o 1.mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
Até quando o ciclo em vigor está pago.
methodtexto · obrigatório
O método do próximo ciclo. O cliente troca-o na página dele, entre os métodos locais.um de: mcx, reference, baipaga, card
cancel_at_period_endbooleano · obrigatório
true quando o cancelamento foi pedido para o fim do ciclo: a subscrição continua active até current_period_end e não renova.
cancelled_attexto (data e hora)
Quando o cancelamento foi pedido.
cancelled_bytexto
Quem pediu o cancelamento: o cliente, na página dele, ou o comerciante, pela API.um de: customer, merchant
ended_attexto (data e hora)
Quando terminou (só em cancelled e expired).
end_reasontexto
Porque terminou: requested (alguém cancelou), unpaid (a tolerância acabou sem pagamento), completed (os ciclos contratados acabaram).um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
A sessão que a criou.padrão ^cs_
latest_payment_idtexto
No subscription.created e no subscription.renewed, o pagamento do ciclo.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadatametadata · obrigatório
Os metadados da sessão que a criou.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de subscription.created
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.created",
  "created_at": "2026-11-30T09:12:05Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "sub_01JA9S",
      "object": "subscription",
      "status": "active",
      "amount": {
        "amount": 990000,
        "currency": "AOA"
      },
      "interval": "month",
      "cycles": 12,
      "cycle": 1,
      "current_period_start": "2026-11-30T09:12:00Z",
      "current_period_end": "2026-12-30T09:12:00Z",
      "method": "reference",
      "cancel_at_period_end": false,
      "checkout_session_id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
      "customer": {
        "email": "cliente@exemplo.ao",
        "name": "Ana Domingos",
        "phone": "+244923000000"
      },
      "metadata": {
        "plano": "pro"
      },
      "latest_payment_id": "pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0"
    }
  }
}

subscription.past_due

A prestação de um ciclo não foi paga a tempo.

Uma subscrição (cartões 8.1 a 8.4). Nasce do primeiro pagamento de uma sessão criada com kind subscription; cada ciclo seguinte é um pagamento normal, com o seu payment.succeeded e o seu recibo. As do Multicaixa Express, da referência e do BAI Paga renovam por um link de pagamento que o Spolly Payments manda ao cliente antes do fim do ciclo; as de cartão renovam sozinhas pelo Stripe.

data.object é um subscription:

idtexto · obrigatório
padrão ^sub_
object"subscription" · obrigatório
statustexto · obrigatório
active: em vigor. past_due: o ciclo acabou sem o seguinte pago, e a tolerância corre (o acesso mantém-se; ainda se paga até à data do aviso). cancelled: terminada a pedido. expired: terminada sem pedido, por falta de pagamento ou porque os ciclos contratados acabaram (end_reason diz qual).um de: active, past_due, cancelled, expired
amountmoney · obrigatório
O preço de cada ciclo.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos mensais e maiores renovam no dia do mês do primeiro pagamento (o dia-âncora): quem pagou a 31 renova a 28 em fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
Os ciclos contratados; null renova até ser cancelada.mínimo 1
cycleinteiro · obrigatório
O ciclo em vigor. O primeiro é o 1.mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
Até quando o ciclo em vigor está pago.
methodtexto · obrigatório
O método do próximo ciclo. O cliente troca-o na página dele, entre os métodos locais.um de: mcx, reference, baipaga, card
cancel_at_period_endbooleano · obrigatório
true quando o cancelamento foi pedido para o fim do ciclo: a subscrição continua active até current_period_end e não renova.
cancelled_attexto (data e hora)
Quando o cancelamento foi pedido.
cancelled_bytexto
Quem pediu o cancelamento: o cliente, na página dele, ou o comerciante, pela API.um de: customer, merchant
ended_attexto (data e hora)
Quando terminou (só em cancelled e expired).
end_reasontexto
Porque terminou: requested (alguém cancelou), unpaid (a tolerância acabou sem pagamento), completed (os ciclos contratados acabaram).um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
A sessão que a criou.padrão ^cs_
latest_payment_idtexto
No subscription.created e no subscription.renewed, o pagamento do ciclo.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadatametadata · obrigatório
Os metadados da sessão que a criou.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de subscription.past_due
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.past_due",
  "created_at": "2026-12-30T09:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "sub_01JA9S",
      "object": "subscription",
      "status": "past_due",
      "amount": {
        "amount": 990000,
        "currency": "AOA"
      },
      "interval": "month",
      "cycles": 12,
      "cycle": 1,
      "current_period_start": "2026-11-30T09:12:00Z",
      "current_period_end": "2026-12-30T09:12:00Z",
      "method": "reference",
      "cancel_at_period_end": false,
      "checkout_session_id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
      "customer": {
        "email": "cliente@exemplo.ao",
        "name": "Ana Domingos",
        "phone": "+244923000000"
      },
      "metadata": {
        "plano": "pro"
      }
    }
  }
}

subscription.renewed

Um ciclo de uma subscrição foi pago.

Uma subscrição (cartões 8.1 a 8.4). Nasce do primeiro pagamento de uma sessão criada com kind subscription; cada ciclo seguinte é um pagamento normal, com o seu payment.succeeded e o seu recibo. As do Multicaixa Express, da referência e do BAI Paga renovam por um link de pagamento que o Spolly Payments manda ao cliente antes do fim do ciclo; as de cartão renovam sozinhas pelo Stripe.

data.object é um subscription:

idtexto · obrigatório
padrão ^sub_
object"subscription" · obrigatório
statustexto · obrigatório
active: em vigor. past_due: o ciclo acabou sem o seguinte pago, e a tolerância corre (o acesso mantém-se; ainda se paga até à data do aviso). cancelled: terminada a pedido. expired: terminada sem pedido, por falta de pagamento ou porque os ciclos contratados acabaram (end_reason diz qual).um de: active, past_due, cancelled, expired
amountmoney · obrigatório
O preço de cada ciclo.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA, e USD e EUR só pelo cartão (ADR 0003).um de: AOA, USD, EUR
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos mensais e maiores renovam no dia do mês do primeiro pagamento (o dia-âncora): quem pagou a 31 renova a 28 em fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
Os ciclos contratados; null renova até ser cancelada.mínimo 1
cycleinteiro · obrigatório
O ciclo em vigor. O primeiro é o 1.mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
Até quando o ciclo em vigor está pago.
methodtexto · obrigatório
O método do próximo ciclo. O cliente troca-o na página dele, entre os métodos locais.um de: mcx, reference, baipaga, card
cancel_at_period_endbooleano · obrigatório
true quando o cancelamento foi pedido para o fim do ciclo: a subscrição continua active até current_period_end e não renova.
cancelled_attexto (data e hora)
Quando o cancelamento foi pedido.
cancelled_bytexto
Quem pediu o cancelamento: o cliente, na página dele, ou o comerciante, pela API.um de: customer, merchant
ended_attexto (data e hora)
Quando terminou (só em cancelled e expired).
end_reasontexto
Porque terminou: requested (alguém cancelou), unpaid (a tolerância acabou sem pagamento), completed (os ciclos contratados acabaram).um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
A sessão que a criou.padrão ^cs_
latest_payment_idtexto
No subscription.created e no subscription.renewed, o pagamento do ciclo.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadatametadata · obrigatório
Os metadados da sessão que a criou.até 50 chaves
metadata.<chave>texto
até 500 carateres
Exemplo de subscription.renewed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.renewed",
  "created_at": "2026-12-28T15:40:11Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "sub_01JA9S",
      "object": "subscription",
      "status": "active",
      "amount": {
        "amount": 990000,
        "currency": "AOA"
      },
      "interval": "month",
      "cycles": 12,
      "cycle": 2,
      "current_period_start": "2026-12-30T09:12:00Z",
      "current_period_end": "2027-01-30T09:12:00Z",
      "method": "reference",
      "cancel_at_period_end": false,
      "checkout_session_id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
      "customer": {
        "email": "cliente@exemplo.ao",
        "name": "Ana Domingos",
        "phone": "+244923000000"
      },
      "metadata": {
        "plano": "pro"
      },
      "latest_payment_id": "pay_3Fz8Qw1Er5Ty7Ui9Op2As4"
    }
  }
}