Vibra Pay
Entrar no painel
Índice

(16) 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 Vibra Pay envia ao comerciante. Chega assinado no cabeçalho Vibra-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: account.updated, balance.available, checkout.session.expired, payment.failed, payment.held, payment.released, payment.succeeded, payout.created, payout.failed, payout.paid, payout.processing, 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_
applicationtexto ou nulo
A aplicação do comerciante de onde o evento vem (a da chave de API ou do link de cobrança que criou a sessão), ou null. O Vibra Pay só entrega o evento aos endpoints da mesma aplicação; um endpoint sem aplicação recebe os eventos sem aplicação. Sai em todos os eventos desde 2026-10-17; os anteriores (e os reenvios deles) não o têm.padrão ^app_
accounttexto
Só nos eventos de uma conta ligada (ADR 0025): a conta de onde o evento vem. O evento chega à plataforma dona da conta (merchant_id é a plataforma), pelos endpoints da aplicação por onde a conta nasceu (application). Sem este campo, o evento é do próprio comerciante.padrão ^mer_
api_versiontexto · obrigatório
padrão ^\d{4}-\d{2}-\d{2}$
dataobjeto · obrigatório
data.objectobjeto · obrigatório

Os tipos

  • account.updatedUma conta ligada (cartão 6.8, ADR 0025): o vendedor de uma plataforma, criado e gerido por ela pela API, que nunca fala com o Vibra Pay. A verificação (KYC) é a da equipa, com o documento de identificação e o comprovativo do IBAN que a plataforma entrega.
  • balance.availableO saldo de uma conta, por moeda, lido do livro (cartão 6.8). available é o que se pode sacar; pending ainda não foi libertado; reserved é a reserva.
  • checkout.session.expiredUma sessão chegou ao fim do prazo sem ser paga.
  • payment.failedUma tentativa de pagamento falhou (recusada, ou o tempo acabou). A sessão continua aberta para outra tentativa.
  • payment.heldUm pagamento pago ficou em análise de risco: o dinheiro entrou, e o líquido fica no pendente até a equipa da Vibra o libertar. Não é uma falha, e a encomenda não se cancela por causa dele; se quiseres, espera pelo payment.released para entregar.
  • payment.releasedA análise de risco de um pagamento terminou, e ele foi libertado: o líquido segue a retenção normal.
  • payment.succeededUm pagamento ficou confirmado pelo gateway. É o evento que marca a encomenda como paga.
  • payout.createdUm saque do saldo disponível para a conta bancária verificada (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.
  • payout.failedUm saque foi recusado, e o valor voltou ao saldo disponível.
  • payout.paidUm saque foi transferido para a tua conta bancária.
  • payout.processingUm saque do saldo disponível para a conta bancária verificada (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.
  • refund.createdUm estorno ficou aceite (pendente ou já devolvido).
  • subscription.cancelledUma subscrição foi cancelada.
  • subscription.createdUma sessão em modo subscrição foi paga, e a subscrição começou.
  • subscription.past_dueA prestação de um ciclo não foi paga a tempo.
  • subscription.renewedUm ciclo de uma subscrição foi pago.

account.updated

Uma conta ligada (cartão 6.8, ADR 0025): o vendedor de uma plataforma, criado e gerido por ela pela API, que nunca fala com o Vibra Pay. A verificação (KYC) é a da equipa, com o documento de identificação e o comprovativo do IBAN que a plataforma entrega.

data.object é um account:

idtexto · obrigatório
padrão ^mer_
object"account" · obrigatório
modetexto · obrigatório
O modo da chave que criou a conta. Uma conta ligada vive num modo só.um de: test, live
nametexto · obrigatório
O nome que o comprador vê no checkout.
legal_nametexto · obrigatório
O nome legal do titular, tal como no documento de identificação.
tax_idtexto · obrigatório
O NIF, se o houver.
emailtexto · obrigatório
phonetexto · obrigatório
referencetexto · obrigatório
A referência da plataforma (o id do vendedor do lado dela), única por plataforma e modo.
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
verificationobjeto · obrigatório
verification.statustexto · obrigatório
um de: pending, in_review, verified, rejected, more_documents
verification.reasontexto · obrigatório
O motivo da equipa, em rejected e more_documents.
verification.missinglista de texto · obrigatório
O que falta entregar para a verificação seguir sozinha para análise.
bank_accountnulo ou objeto · obrigatório
bank_account.idtexto · obrigatório
padrão ^cb_
bank_account.iban_last4texto · obrigatório
padrão ^[0-9A-Z]{4}$
bank_account.holdertexto · obrigatório
bank_account.statustexto · obrigatório
Um IBAN mudado depois da verificação fica pending_verification até a equipa o verificar, e a conta não saca até lá.um de: verified, pending_verification
bank_account.created_attexto (data e hora) · obrigatório
documentslista de objeto · obrigatório
documents[].idtexto · obrigatório
padrão ^doc_
documents[].object"account_document" · obrigatório
documents[].typetexto · obrigatório
um de: identity_document, bank_account_proof, other
documents[].file_nametexto · obrigatório
documents[].content_typetexto · obrigatório
um de: application/pdf, image/jpeg, image/png
documents[].sizeinteiro · obrigatório
mínimo 1
documents[].created_attexto (data e hora) · obrigatório
charges_enabledbooleano · obrigatório
Se a plataforma pode cobrar em nome da conta: com a habilitação ativa, e em produção só depois da verificação.
payouts_enabledbooleano · obrigatório
Se a conta pode sacar: verificada, com a conta bancária verificada.
created_attexto (data e hora) · obrigatório
Exemplo de account.updated
{
  "id": "evt_01JA9X8Y8C",
  "type": "account.updated",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9BILHETEIRA",
  "application": "app_01JA9BILHETES",
  "account": "mer_01JA9VENDEDOR",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "mer_01JA9VENDEDOR",
      "object": "account",
      "mode": "live",
      "name": "Kizomba Eventos",
      "legal_name": "Joana Manuel",
      "tax_id": "",
      "email": "joana@kizomba.ao",
      "phone": "+244923456789",
      "reference": "vendedor_481",
      "metadata": {
        "plano": "pro"
      },
      "verification": {
        "status": "verified",
        "reason": "",
        "missing": []
      },
      "bank_account": {
        "id": "cb_01JA9CONTA",
        "iban_last4": "1234",
        "holder": "Joana Manuel",
        "status": "verified",
        "created_at": "2026-11-29T09:00:00Z"
      },
      "documents": [
        {
          "id": "doc_01JA9BI",
          "object": "account_document",
          "type": "identity_document",
          "file_name": "bi.pdf",
          "content_type": "application/pdf",
          "size": 182340,
          "created_at": "2026-11-29T08:58:00Z"
        },
        {
          "id": "doc_01JA9IBAN",
          "object": "account_document",
          "type": "bank_account_proof",
          "file_name": "iban.pdf",
          "content_type": "application/pdf",
          "size": 90211,
          "created_at": "2026-11-29T08:59:00Z"
        }
      ],
      "charges_enabled": true,
      "payouts_enabled": true,
      "created_at": "2026-11-29T08:55:00Z"
    }
  }
}

balance.available

O saldo de uma conta, por moeda, lido do livro (cartão 6.8). available é o que se pode sacar; pending ainda não foi libertado; reserved é a reserva.

data.object é um balance:

object"balance" · obrigatório
accounttexto · obrigatório
padrão ^mer_
availablelista de signed_money · obrigatório
available[].amountinteiro · obrigatório
available[].currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
pendinglista de signed_money · obrigatório
pending[].amountinteiro · obrigatório
pending[].currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
reservedlista de signed_money · obrigatório
reserved[].amountinteiro · obrigatório
reserved[].currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
Exemplo de balance.available
{
  "id": "evt_01JA9X8Y8D",
  "type": "balance.available",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9BILHETEIRA",
  "application": "app_01JA9BILHETES",
  "account": "mer_01JA9VENDEDOR",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "object": "balance",
      "account": "mer_01JA9VENDEDOR",
      "available": [
        {
          "amount": 4875000,
          "currency": "AOA"
        }
      ],
      "pending": [
        {
          "amount": 0,
          "currency": "AOA"
        }
      ],
      "reserved": [
        {
          "amount": 0,
          "currency": "AOA"
        }
      ]
    }
  }
}

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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",
  "application": null,
  "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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
feemoney · obrigatório
A taxa da Vibra.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
netmoney · obrigatório
O que fica ao comerciante: amount menos fee e menos a comissão da plataforma (platform_fee), quando a há. Com settlement balance, é o que entra no saldo dele no Vibra Pay; com merchant_account (a transferência bancária, que entra direta na conta dele), é o que lhe fica depois da taxa, que sai do saldo dele, e nada disto passa pelo saldo.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
settlementtexto · obrigatório
Para onde foi o dinheiro: balance, o saldo do comerciante no Vibra Pay (todos os métodos menos a transferência); merchant_account, a conta bancária do comerciante (a transferência bancária, cartão 4.12, ADR 0020). Numa merchant_account, o comerciante confirma o pagamento no painel, e a taxa (fee) sai do saldo dele.um de: balance, merchant_account
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (pela PayPay), Visa e Mastercard (card, Stripe), Pix (Stripe, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA; a transferência e o débito direto só em AOA, e só quando a sessão os pede por nome.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
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
paid_after_expirytrue
Só quando é verdade: o pagamento entrou depois do prazo da sessão (uma referência do MoMenu, que se pode pagar no ATM depois da sessão expirar). O dinheiro entrou e está no saldo do comerciante; entregar ou estornar é decisão dele.
platform_feenulo ou platform_fee
A comissão que a plataforma recebeu neste pagamento, ou null. Só nos pagos; nos falhados é null.
platform_fee.platformtexto · obrigatório
O comerciante da plataforma.padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda do pagamento.mínimo 1
fee_on_topnulo ou money
A parte do amount que o comprador pagou por cima, quando o comerciante lhe passa a taxa do Vibra Pay (cartão 3.5): é igual ao fee, e o net é o valor da cobrança. null quando a taxa sai do valor, como sempre.
fee_on_top.amountinteiro · obrigatório
mínimo 0
fee_on_top.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
platform_fee_skippedtexto
Só quando a sessão pediu comissão e ela não se aplicou: o comerciante revogou a autorização (authorization_revoked), o máximo autorizado já não a cobre (above_maximum), ou a taxa mudou e a comissão já não cabe no líquido (exceeds_net). O pagamento entrou sem comissão.um de: authorization_revoked, above_maximum, exceeds_net
discountnulo ou discount
O cupão que a sessão aplicou (cartão 4.14), ou null. O amount já é o valor depois do desconto.
discount.couponcoupon · obrigatório
O cupão aplicado (cartão 4.14), como estava quando se aplicou. Um cupão é de percentagem (percent_off) ou de valor fixo (amount_off, só na moeda dele); o desconto dele não muda depois de criado.
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
O código que o comprador escreve, em maiúsculas.padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
discount.coupon.nametexto · obrigatório
até 120 carateres
discount.coupon.percent_offnulo ou inteiro · obrigatório
discount.coupon.amount_offnulo ou money · obrigatório
discount.coupon.durationtexto · obrigatório
Numa subscrição: once vale no primeiro ciclo, repeating nos primeiros duration_cycles, forever em todos. Num pagamento único vale uma vez.um de: once, repeating, forever
discount.coupon.duration_cyclesnulo ou inteiro · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
Exemplo de payment.failed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payment.failed",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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"
      },
      "settlement": "balance",
      "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.",
      "discount": null
    }
  }
}

payment.held

Um pagamento pago ficou em análise de risco: o dinheiro entrou, e o líquido fica no pendente até a equipa da Vibra o libertar. Não é uma falha, e a encomenda não se cancela por causa dele; se quiseres, espera pelo payment.released para entregar.

O pagamento foi pago e confirmado, mas o líquido ficou retido para análise de risco (cartão 9.8): não passa a disponível nem entra num saque até a equipa o libertar. Pode chegar logo a seguir ao payment.succeeded, ou mais tarde, numa disputa. Não é uma falha: não se cancela a encomenda por causa dele.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
feemoney · obrigatório
A taxa da Vibra.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
netmoney · obrigatório
O que fica ao comerciante: amount menos fee e menos a comissão da plataforma (platform_fee), quando a há. Com settlement balance, é o que entra no saldo dele no Vibra Pay; com merchant_account (a transferência bancária, que entra direta na conta dele), é o que lhe fica depois da taxa, que sai do saldo dele, e nada disto passa pelo saldo.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
settlementtexto · obrigatório
Para onde foi o dinheiro: balance, o saldo do comerciante no Vibra Pay (todos os métodos menos a transferência); merchant_account, a conta bancária do comerciante (a transferência bancária, cartão 4.12, ADR 0020). Numa merchant_account, o comerciante confirma o pagamento no painel, e a taxa (fee) sai do saldo dele.um de: balance, merchant_account
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (pela PayPay), Visa e Mastercard (card, Stripe), Pix (Stripe, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA; a transferência e o débito direto só em AOA, e só quando a sessão os pede por nome.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
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
paid_after_expirytrue
Só quando é verdade: o pagamento entrou depois do prazo da sessão (uma referência do MoMenu, que se pode pagar no ATM depois da sessão expirar). O dinheiro entrou e está no saldo do comerciante; entregar ou estornar é decisão dele.
platform_feenulo ou platform_fee
A comissão que a plataforma recebeu neste pagamento, ou null. Só nos pagos; nos falhados é null.
platform_fee.platformtexto · obrigatório
O comerciante da plataforma.padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda do pagamento.mínimo 1
fee_on_topnulo ou money
A parte do amount que o comprador pagou por cima, quando o comerciante lhe passa a taxa do Vibra Pay (cartão 3.5): é igual ao fee, e o net é o valor da cobrança. null quando a taxa sai do valor, como sempre.
fee_on_top.amountinteiro · obrigatório
mínimo 0
fee_on_top.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
platform_fee_skippedtexto
Só quando a sessão pediu comissão e ela não se aplicou: o comerciante revogou a autorização (authorization_revoked), o máximo autorizado já não a cobre (above_maximum), ou a taxa mudou e a comissão já não cabe no líquido (exceeds_net). O pagamento entrou sem comissão.um de: authorization_revoked, above_maximum, exceeds_net
discountnulo ou discount
O cupão que a sessão aplicou (cartão 4.14), ou null. O amount já é o valor depois do desconto.
discount.couponcoupon · obrigatório
O cupão aplicado (cartão 4.14), como estava quando se aplicou. Um cupão é de percentagem (percent_off) ou de valor fixo (amount_off, só na moeda dele); o desconto dele não muda depois de criado.
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
O código que o comprador escreve, em maiúsculas.padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
discount.coupon.nametexto · obrigatório
até 120 carateres
discount.coupon.percent_offnulo ou inteiro · obrigatório
discount.coupon.amount_offnulo ou money · obrigatório
discount.coupon.durationtexto · obrigatório
Numa subscrição: once vale no primeiro ciclo, repeating nos primeiros duration_cycles, forever em todos. Num pagamento único vale uma vez.um de: once, repeating, forever
discount.coupon.duration_cyclesnulo ou inteiro · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
Exemplo de payment.held
{
  "id": "evt_01JA9X8Y8A",
  "type": "payment.held",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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"
      },
      "settlement": "balance",
      "method": "mcx",
      "created_at": "2026-11-30T10:14:58Z",
      "metadata": {
        "order_id": "1042"
      },
      "platform_fee": null,
      "discount": null
    }
  }
}

payment.released

A análise de risco de um pagamento terminou, e ele foi libertado: o líquido segue a retenção normal.

A análise de risco terminou e o pagamento foi libertado: o líquido segue a retenção normal até ficar disponível.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
feemoney · obrigatório
A taxa da Vibra.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
netmoney · obrigatório
O que fica ao comerciante: amount menos fee e menos a comissão da plataforma (platform_fee), quando a há. Com settlement balance, é o que entra no saldo dele no Vibra Pay; com merchant_account (a transferência bancária, que entra direta na conta dele), é o que lhe fica depois da taxa, que sai do saldo dele, e nada disto passa pelo saldo.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
settlementtexto · obrigatório
Para onde foi o dinheiro: balance, o saldo do comerciante no Vibra Pay (todos os métodos menos a transferência); merchant_account, a conta bancária do comerciante (a transferência bancária, cartão 4.12, ADR 0020). Numa merchant_account, o comerciante confirma o pagamento no painel, e a taxa (fee) sai do saldo dele.um de: balance, merchant_account
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (pela PayPay), Visa e Mastercard (card, Stripe), Pix (Stripe, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA; a transferência e o débito direto só em AOA, e só quando a sessão os pede por nome.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
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
paid_after_expirytrue
Só quando é verdade: o pagamento entrou depois do prazo da sessão (uma referência do MoMenu, que se pode pagar no ATM depois da sessão expirar). O dinheiro entrou e está no saldo do comerciante; entregar ou estornar é decisão dele.
platform_feenulo ou platform_fee
A comissão que a plataforma recebeu neste pagamento, ou null. Só nos pagos; nos falhados é null.
platform_fee.platformtexto · obrigatório
O comerciante da plataforma.padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda do pagamento.mínimo 1
fee_on_topnulo ou money
A parte do amount que o comprador pagou por cima, quando o comerciante lhe passa a taxa do Vibra Pay (cartão 3.5): é igual ao fee, e o net é o valor da cobrança. null quando a taxa sai do valor, como sempre.
fee_on_top.amountinteiro · obrigatório
mínimo 0
fee_on_top.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
platform_fee_skippedtexto
Só quando a sessão pediu comissão e ela não se aplicou: o comerciante revogou a autorização (authorization_revoked), o máximo autorizado já não a cobre (above_maximum), ou a taxa mudou e a comissão já não cabe no líquido (exceeds_net). O pagamento entrou sem comissão.um de: authorization_revoked, above_maximum, exceeds_net
discountnulo ou discount
O cupão que a sessão aplicou (cartão 4.14), ou null. O amount já é o valor depois do desconto.
discount.couponcoupon · obrigatório
O cupão aplicado (cartão 4.14), como estava quando se aplicou. Um cupão é de percentagem (percent_off) ou de valor fixo (amount_off, só na moeda dele); o desconto dele não muda depois de criado.
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
O código que o comprador escreve, em maiúsculas.padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
discount.coupon.nametexto · obrigatório
até 120 carateres
discount.coupon.percent_offnulo ou inteiro · obrigatório
discount.coupon.amount_offnulo ou money · obrigatório
discount.coupon.durationtexto · obrigatório
Numa subscrição: once vale no primeiro ciclo, repeating nos primeiros duration_cycles, forever em todos. Num pagamento único vale uma vez.um de: once, repeating, forever
discount.coupon.duration_cyclesnulo ou inteiro · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
Exemplo de payment.released
{
  "id": "evt_01JA9X8Y9B",
  "type": "payment.released",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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"
      },
      "settlement": "balance",
      "method": "mcx",
      "created_at": "2026-11-30T10:14:58Z",
      "metadata": {
        "order_id": "1042"
      },
      "platform_fee": null,
      "discount": null
    }
  }
}

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
feemoney · obrigatório
A taxa da Vibra.
fee.amountinteiro · obrigatório
mínimo 0
fee.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
netmoney · obrigatório
O que fica ao comerciante: amount menos fee e menos a comissão da plataforma (platform_fee), quando a há. Com settlement balance, é o que entra no saldo dele no Vibra Pay; com merchant_account (a transferência bancária, que entra direta na conta dele), é o que lhe fica depois da taxa, que sai do saldo dele, e nada disto passa pelo saldo.
net.amountinteiro · obrigatório
mínimo 0
net.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
settlementtexto · obrigatório
Para onde foi o dinheiro: balance, o saldo do comerciante no Vibra Pay (todos os métodos menos a transferência); merchant_account, a conta bancária do comerciante (a transferência bancária, cartão 4.12, ADR 0020). Numa merchant_account, o comerciante confirma o pagamento no painel, e a taxa (fee) sai do saldo dele.um de: balance, merchant_account
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (pela PayPay), Visa e Mastercard (card, Stripe), Pix (Stripe, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA; a transferência e o débito direto só em AOA, e só quando a sessão os pede por nome.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
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
paid_after_expirytrue
Só quando é verdade: o pagamento entrou depois do prazo da sessão (uma referência do MoMenu, que se pode pagar no ATM depois da sessão expirar). O dinheiro entrou e está no saldo do comerciante; entregar ou estornar é decisão dele.
platform_feenulo ou platform_fee
A comissão que a plataforma recebeu neste pagamento, ou null. Só nos pagos; nos falhados é null.
platform_fee.platformtexto · obrigatório
O comerciante da plataforma.padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda do pagamento.mínimo 1
fee_on_topnulo ou money
A parte do amount que o comprador pagou por cima, quando o comerciante lhe passa a taxa do Vibra Pay (cartão 3.5): é igual ao fee, e o net é o valor da cobrança. null quando a taxa sai do valor, como sempre.
fee_on_top.amountinteiro · obrigatório
mínimo 0
fee_on_top.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
platform_fee_skippedtexto
Só quando a sessão pediu comissão e ela não se aplicou: o comerciante revogou a autorização (authorization_revoked), o máximo autorizado já não a cobre (above_maximum), ou a taxa mudou e a comissão já não cabe no líquido (exceeds_net). O pagamento entrou sem comissão.um de: authorization_revoked, above_maximum, exceeds_net
discountnulo ou discount
O cupão que a sessão aplicou (cartão 4.14), ou null. O amount já é o valor depois do desconto.
discount.couponcoupon · obrigatório
O cupão aplicado (cartão 4.14), como estava quando se aplicou. Um cupão é de percentagem (percent_off) ou de valor fixo (amount_off, só na moeda dele); o desconto dele não muda depois de criado.
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
O código que o comprador escreve, em maiúsculas.padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
discount.coupon.nametexto · obrigatório
até 120 carateres
discount.coupon.percent_offnulo ou inteiro · obrigatório
discount.coupon.amount_offnulo ou money · obrigatório
discount.coupon.durationtexto · obrigatório
Numa subscrição: once vale no primeiro ciclo, repeating nos primeiros duration_cycles, forever em todos. Num pagamento único vale uma vez.um de: once, repeating, forever
discount.coupon.duration_cyclesnulo ou inteiro · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
Exemplo de payment.succeeded
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payment.succeeded",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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"
      },
      "settlement": "balance",
      "method": "mcx",
      "created_at": "2026-11-30T10:14:58Z",
      "metadata": {
        "order_id": "1042"
      },
      "platform_fee": null,
      "discount": null
    }
  }
}

payout.created

Um saque do saldo disponível para a conta bancária verificada (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
statustexto · obrigatório
pending (pedido), processing (aprovado, à espera da transferência), paid ou failed.um de: pending, processing, paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler, ou o da devolução pelo banco.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
metadatametadata
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 payout.created
{
  "id": "evt_01JA9X8Y8A",
  "type": "payout.created",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9BILHETEIRA",
  "application": "app_01JA9BILHETES",
  "account": "mer_01JA9VENDEDOR",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "po_01JA9P",
      "object": "payout",
      "amount": {
        "amount": 2500000,
        "currency": "AOA"
      },
      "status": "pending",
      "created_at": "2026-11-30T10:15:00Z",
      "metadata": {
        "pedido_na_plataforma": "saq_9921"
      }
    }
  }
}

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 (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
statustexto · obrigatório
pending (pedido), processing (aprovado, à espera da transferência), paid ou failed.um de: pending, processing, paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler, ou o da devolução pelo banco.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
metadatametadata
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 payout.failed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payout.failed",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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",
      "metadata": {}
    }
  }
}

payout.paid

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

Um saque do saldo disponível para a conta bancária verificada (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
statustexto · obrigatório
pending (pedido), processing (aprovado, à espera da transferência), paid ou failed.um de: pending, processing, paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler, ou o da devolução pelo banco.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
metadatametadata
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 payout.paid
{
  "id": "evt_01JA9X8Y7Z",
  "type": "payout.paid",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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",
      "metadata": {}
    }
  }
}

payout.processing

Um saque do saldo disponível para a conta bancária verificada (cartões 6.2, 6.3 e 6.9). payout.created sai quando o saque é pedido (no painel, ou pela plataforma de uma conta ligada), payout.processing quando é aprovado (pela equipa, ou sozinho, dentro do limite da habilitação da plataforma), payout.paid quando a transferência está feita, e payout.failed quando a equipa o recusa e o valor volta ao saldo disponível. Em produção a transferência é feita pela equipa, no banco ou pela PayPay; uma transferência pela PayPay que o banco devolve depois de paga dá um payout.failed a seguir ao payout.paid, e o valor volta ao saldo disponível. Em teste só existem os saques das contas ligadas, e pagam-se sozinhos.

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
statustexto · obrigatório
pending (pedido), processing (aprovado, à espera da transferência), paid ou failed.um de: pending, processing, paid, failed
failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler, ou o da devolução pelo banco.
paid_attexto (data e hora)
created_attexto (data e hora) · obrigatório
metadatametadata
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 payout.processing
{
  "id": "evt_01JA9X8Y8B",
  "type": "payout.processing",
  "created_at": "2026-11-30T10:15:00Z",
  "mode": "live",
  "merchant_id": "mer_01JA9BILHETEIRA",
  "application": "app_01JA9BILHETES",
  "account": "mer_01JA9VENDEDOR",
  "api_version": "2026-10-16",
  "data": {
    "object": {
      "id": "po_01JA9P",
      "object": "payout",
      "amount": {
        "amount": 2500000,
        "currency": "AOA"
      },
      "status": "processing",
      "created_at": "2026-11-30T10:15:00Z",
      "metadata": {
        "pedido_na_plataforma": "saq_9921"
      }
    }
  }
}

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; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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",
  "application": null,
  "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.

Sai em dois momentos. No pedido de um cancelamento para o fim do ciclo, com a subscrição ainda active e cancel_at_period_end true: vai acabar em current_period_end. E quando a subscrição termina de facto (cancelada já, no fim do ciclo de uma cancelada no fim, por falta de pagamento ou com os ciclos acabados), com status cancelled ou expired, ended_at e end_reason: acabou, e é por este que o produto corta o acesso. Uma cancelada no fim do ciclo dá os dois.

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. As renovações cobram-no, menos o desconto do cupão nos ciclos que ele cobre (discount).
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou money
O que o primeiro ciclo custou, quando foi mais barato do que amount (um cupão que vale só no primeiro, cartão 8.6), ou null. Só o primeiro ciclo; as renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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 que renovam por link na moeda da subscrição (em BRL, o Pix).um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
renewaltexto · obrigatório
Como renova o ciclo seguinte. automatic: cobra-se sozinho, sem o cliente agir (Visa e Mastercard e o débito direto); se a cobrança falhar, passa a past_due e o cliente recebe o aviso com o link do ciclo. notice: o cliente recebe o aviso com o link e paga (Multicaixa Express, referência, Pix, transferência).um de: automatic, notice
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
discountnulo ou subscription_discount
O cupão da subscrição (cartão 4.14), ou null: o desconto de cada ciclo que cobre, e quantos. O amount continua a ser o preço cheio.
discount.couponobjeto · obrigatório
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
discount.cyclesnulo ou inteiro · obrigatório
Exemplo de subscription.cancelled
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.cancelled",
  "created_at": "2026-12-15T12:00:00Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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",
      "renewal": "notice",
      "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",
      "discount": null
    }
  }
}

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 Pix (só em BRL, ADR 0017) renovam por um link de pagamento que o Vibra Pay manda ao cliente antes do fim do ciclo; as de Visa e Mastercard e as de débito direto renovam sozinhas (Visa e Mastercard pelo Stripe em produção, o débito direto contra o mandato), e o campo renewal diz qual é o caso.

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. As renovações cobram-no, menos o desconto do cupão nos ciclos que ele cobre (discount).
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou money
O que o primeiro ciclo custou, quando foi mais barato do que amount (um cupão que vale só no primeiro, cartão 8.6), ou null. Só o primeiro ciclo; as renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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 que renovam por link na moeda da subscrição (em BRL, o Pix).um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
renewaltexto · obrigatório
Como renova o ciclo seguinte. automatic: cobra-se sozinho, sem o cliente agir (Visa e Mastercard e o débito direto); se a cobrança falhar, passa a past_due e o cliente recebe o aviso com o link do ciclo. notice: o cliente recebe o aviso com o link e paga (Multicaixa Express, referência, Pix, transferência).um de: automatic, notice
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
discountnulo ou subscription_discount
O cupão da subscrição (cartão 4.14), ou null: o desconto de cada ciclo que cobre, e quantos. O amount continua a ser o preço cheio.
discount.couponobjeto · obrigatório
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
discount.cyclesnulo ou inteiro · obrigatório
Exemplo de subscription.created
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.created",
  "created_at": "2026-11-30T09:12:05Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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",
      "renewal": "notice",
      "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",
      "discount": null
    }
  }
}

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 Pix (só em BRL, ADR 0017) renovam por um link de pagamento que o Vibra Pay manda ao cliente antes do fim do ciclo; as de Visa e Mastercard e as de débito direto renovam sozinhas (Visa e Mastercard pelo Stripe em produção, o débito direto contra o mandato), e o campo renewal diz qual é o caso.

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. As renovações cobram-no, menos o desconto do cupão nos ciclos que ele cobre (discount).
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou money
O que o primeiro ciclo custou, quando foi mais barato do que amount (um cupão que vale só no primeiro, cartão 8.6), ou null. Só o primeiro ciclo; as renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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 que renovam por link na moeda da subscrição (em BRL, o Pix).um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
renewaltexto · obrigatório
Como renova o ciclo seguinte. automatic: cobra-se sozinho, sem o cliente agir (Visa e Mastercard e o débito direto); se a cobrança falhar, passa a past_due e o cliente recebe o aviso com o link do ciclo. notice: o cliente recebe o aviso com o link e paga (Multicaixa Express, referência, Pix, transferência).um de: automatic, notice
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
discountnulo ou subscription_discount
O cupão da subscrição (cartão 4.14), ou null: o desconto de cada ciclo que cobre, e quantos. O amount continua a ser o preço cheio.
discount.couponobjeto · obrigatório
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
discount.cyclesnulo ou inteiro · obrigatório
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",
  "application": null,
  "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",
      "renewal": "notice",
      "cancel_at_period_end": false,
      "checkout_session_id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
      "customer": {
        "email": "cliente@exemplo.ao",
        "name": "Ana Domingos",
        "phone": "+244923000000"
      },
      "metadata": {
        "plano": "pro"
      },
      "discount": null
    }
  }
}

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 Pix (só em BRL, ADR 0017) renovam por um link de pagamento que o Vibra Pay manda ao cliente antes do fim do ciclo; as de Visa e Mastercard e as de débito direto renovam sozinhas (Visa e Mastercard pelo Stripe em produção, o débito direto contra o mandato), e o campo renewal diz qual é o caso.

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. As renovações cobram-no, menos o desconto do cupão nos ciclos que ele cobre (discount).
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou money
O que o primeiro ciclo custou, quando foi mais barato do que amount (um cupão que vale só no primeiro, cartão 8.6), ou null. Só o primeiro ciclo; as renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
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 que renovam por link na moeda da subscrição (em BRL, o Pix).um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
renewaltexto · obrigatório
Como renova o ciclo seguinte. automatic: cobra-se sozinho, sem o cliente agir (Visa e Mastercard e o débito direto); se a cobrança falhar, passa a past_due e o cliente recebe o aviso com o link do ciclo. notice: o cliente recebe o aviso com o link e paga (Multicaixa Express, referência, Pix, transferência).um de: automatic, notice
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
discountnulo ou subscription_discount
O cupão da subscrição (cartão 4.14), ou null: o desconto de cada ciclo que cobre, e quantos. O amount continua a ser o preço cheio.
discount.couponobjeto · obrigatório
discount.coupon.idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
discount.coupon.codetexto · obrigatório
discount.amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
discount.amount.amountinteiro · obrigatório
mínimo 0
discount.amount.currencytexto · obrigatório
Código ISO 4217. Na v1: AOA; USD e EUR só por Visa e Mastercard (ADR 0003); BRL por Visa e Mastercard e pelo Pix (ADR 0016).um de: AOA, USD, EUR, BRL
discount.cyclesnulo ou inteiro · obrigatório
Exemplo de subscription.renewed
{
  "id": "evt_01JA9X8Y7Z",
  "type": "subscription.renewed",
  "created_at": "2026-12-28T15:40:11Z",
  "mode": "test",
  "merchant_id": "mer_01JA9SALUTO",
  "application": null,
  "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",
      "renewal": "notice",
      "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",
      "discount": null
    }
  }
}