(15) Referência

Referência da API

Todas as rotas, com os campos, as respostas e os exemplos, geradas da especificação OpenAPI.

Sobre esta referência

Gerada de contratos/openapi.yaml, a especificação OpenAPI 3.1.0 da API, versão 2026-10-16. É a mesma especificação que os testes da API confrontam com as rotas registadas, por isso o que está aqui é o que a API faz. Os exemplos usam https://pay-api.vibra.ao; os servidores são:

https://pay-api.vibra.ao: Produção. Um nome de um nível, coberto pelo certificado universal da Cloudflare (ADR 0005)
http://localhost:8084: Desenvolvimento

O Vibra Pay é só checkout alojado: um produto cria uma sessão, manda o comprador para checkout.pay.vibra.ao, e recebe um webhook assinado quando o pagamento entra. Os eventos estão descritos em contratos/eventos/.

Este documento cresce com os cartões: cada rota entra aqui no mesmo commit em que entra na API, e a verificação do cartão 4.1 confronta-o com as rotas registadas (TestAsRotasV1BatemComAOpenAPI, na api). Hoje existem a sonda de saúde (cartão 0.2), a conta da chave (cartão 2.4), a sessão de checkout (cartão 4.1), os estornos (cartão 7.1), as subscrições (cartões 8.1 e 8.4), as contas ligadas (cartões 6.8 e 6.9) e os cupões (cartão 4.14).

Todos os POST de /v1 levam o cabeçalho Idempotency-Key: repetir o pedido com a mesma chave devolve a mesma resposta (com Idempotent-Replayed: true) e não cria nada outra vez. O modo (teste ou produção) é o da chave.

Dinheiro viaja sempre em unidades menores inteiras, e erros e mensagens em português europeu.

Os eventos que a API envia aos teus endpoints estão na referência dos eventos.

Operação

Sondas para quem opera o serviço

GET/metodossem chave

Que métodos a produção cobra agora, por moeda

Os métodos que uma sessão de produção aceitaria neste momento: os que têm um gateway configurado e ligado. Uma moeda sem nenhum método ativo não aparece. por_pedido diz os que só se oferecem quando a sessão os pede por nome em payment_methods (a transferência e o débito direto). Não diz nada sobre os gateways. É o que a página dos métodos da documentação mostra.

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/metodos"

Respostas

200
Os métodos ativos em produção.
modotexto · obrigatório
um de: live
moedaslista de objeto · obrigatório
moedas[].moedatexto · obrigatório
um de: AOA, USD, EUR, BRL
moedas[].metodoslista de objeto · obrigatório
moedas[].metodos[].metodotexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
moedas[].metodos[].por_pedidobooleano · obrigatório
JSON
```
{
  "modo": "live",
  "moedas": [
    {
      "moeda": "AOA",
      "metodos": [
        {
          "metodo": "mcx",
          "por_pedido": false
        },
        {
          "metodo": "reference",
          "por_pedido": false
        },
        {
          "metodo": "card",
          "por_pedido": false
        },
        {
          "metodo": "bank_transfer",
          "por_pedido": true
        }
      ]
    },
    {
      "moeda": "USD",
      "metodos": [
        {
          "metodo": "card",
          "por_pedido": false
        }
      ]
    }
  ]
}
```

GET/saudesem chave

O serviço está vivo, e a base de dados responde?

Responde 200 só quando a base de dados respondeu dentro do tempo limite. Com a base em baixo responde 503, e diz que falhou: uma leitura falhada nunca se apresenta como uma resposta legítima.

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/saude"

Respostas

200
Vivo, e a base responde.
estadotexto · obrigatório
um de: ok, degradado
versaotexto · obrigatório
A versão da construção, ou dev em desenvolvimento.
committexto · obrigatório
O commit da construção, ou dev em desenvolvimento.
basetexto · obrigatório
um de: ok, falhou
JSON
```
{
  "estado": "ok",
  "versao": "v0.1.0",
  "commit": "3f2a1b9",
  "base": "ok"
}
```
503
Vivo, mas a base não responde.
estadotexto · obrigatório
um de: ok, degradado
versaotexto · obrigatório
A versão da construção, ou dev em desenvolvimento.
committexto · obrigatório
O commit da construção, ou dev em desenvolvimento.
basetexto · obrigatório
um de: ok, falhou
JSON
```
{
  "estado": "degradado",
  "versao": "v0.1.0",
  "commit": "3f2a1b9",
  "base": "falhou"
}
```

Conta

A conta a que a chave de API pertence

GET/v1/conta

De que comerciante e de que modo é esta chave?

A primeira coisa a chamar depois de configurar uma chave: confirma que uma sk_test_ não foi parar a um servidor de produção, e o contrário. Não devolve dados do KYC nem a conta bancária. Com Vibra-Account, responde pela conta ligada.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/conta" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
A chave é válida.
merchant_idtexto · obrigatório
padrão ^mer_
nome_comercialtexto · obrigatório
modotexto · obrigatório
um de: test, live
JSON
```
{
  "merchant_id": "mer_01JA9SALUTO000000",
  "nome_comercial": "Saluto",
  "modo": "test"
}
```
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Sessões de checkout

A sessão de checkout: o produto cria-a e manda o comprador para o url. O regresso ao success_url não prova pagamento: confirma-se pelo webhook payment.succeeded, ou pelo GET da sessão.

POST/v1/checkout/sessions

Criar uma sessão de checkout

Devolve a sessão com o url do checkout alojado, para onde se manda o comprador. Sem payment_methods, aceita todos os que têm gateway na moeda e no modo da chave (AOA: mcx, reference, paypay, kwik, card; USD e EUR: só card; BRL: pix e card). Uma referência emitida no checkout deixa de se poder pagar quando a sessão expira (expires_at), e nunca depois.

A PayPay (paypay) e o KWiK (kwik) existem só em AOA. Na PayPay, o comprador paga na app da PayPay: o checkout mostra a ligação que a abre e o QR para a abrir noutro telemóvel. No KWiK, o comprador lê o QR com a app de qualquer banco, ou escreve o código de nove dígitos. Os dois expiram com a sessão.

A transferência bancária (bank_transfer) e o débito direto (direct_debit) existem só em AOA, e só se oferecem quando a sessão os pede por nome em payment_methods: uma lista vazia não os inclui. Na transferência, o dinheiro vai direto para a conta bancária do comerciante, e não passa pela Vibra (ADR 0020): o comprador vê a conta do comerciante (a escolhida para a aplicação da chave, senão a por omissão, senão a conta bancária do KYC; configuram-se no painel, em Contas de transferência), o valor e um descritivo único (TRF e oito carateres). O pagamento fica pendente até 7 dias, até o comerciante o confirmar no painel, ao ver o movimento no extrato dele (pode entrar depois de a sessão expirar). Confirmado, o payment.succeeded traz settlement: "merchant_account", e a taxa (fee) sai do saldo do comerciante. Um comerciante sem conta nenhuma não pode pedir a transferência (metodo_sem_gateway), uma sessão com platform_fee não a pode pedir (comissao_invalida), e uma transferência confirmada não se estorna pela API (pago_na_conta_do_comerciante): a devolução faz-se da conta do comerciante. No débito direto, o comprador dá o titular, o IBAN e o telemóvel, ativa o mandato no banco dele, e o pagamento confirma-se quando o banco liquida a primeira cobrança.

Confirmar o pagamento: pelo webhook, e não pelo regresso

Quando o comprador paga, o checkout manda-o para o success_url com session_id acrescentado. Esse regresso não prova nada: qualquer pessoa escreve aquele endereço no browser, o comprador pode fechar a página antes de lá chegar, e uma referência paga no multibanco horas depois nem sequer passa pelo browser. A encomenda dá-se por paga em dois sítios, e só nestes:

No webhook payment.succeeded, assinado (Vibra-Signature), que chega ao endpoint configurado no painel. É o caminho principal, e o único que apanha os pagamentos que acabam longe do browser.
Num GET /v1/checkout/sessions/{id} com a chave de API, do lado do servidor: status igual a complete e payment.status igual a succeeded. Serve para a página de agradecimento mostrar o estado certo enquanto o webhook não chega.

Exemplo, num servidor Node:

JavaScript

import { constructEvent } from "@aurennunes/vibra-pay/webhook"; // o SDK em JavaScript

// 1. O webhook: a fonte da verdade.
app.post("/webhooks/vibra", express.raw({ type: "application/json" }), (req, res) => {
  const evento = constructEvent(req.body, req.get("Vibra-Signature"), segredo); // lança se não bater
  if (evento.type === "payment.succeeded") {
    const sessao = evento.data.object.checkout_session_id;
    marcarEncomendaPaga(sessao); // idempotente: o mesmo evento pode chegar duas vezes
  }
  res.sendStatus(200);
});

// 2. O regresso: só mostra; não marca nada como pago.
app.get("/obrigado", async (req, res) => {
  const r = await fetch(`https://pay-api.vibra.ao/v1/checkout/sessions/${req.query.session_id}`, {
    headers: { Authorization: `Bearer ${process.env.VIBRA_SECRET_KEY}` },
  });
  const sessao = await r.json();
  res.render(sessao.status === "complete" ? "pago" : "a-confirmar");
});

A comissão da plataforma

Uma plataforma que vende em nome de um comerciante (um hotel, um lojista) cria a sessão com a chave do comerciante e acrescenta platform_fee: o mer_... da plataforma e o valor, em unidades menores da moeda da sessão. O comerciante tem de ter autorizado a plataforma no painel dele (Plataformas), com uma comissão máxima em pontos-base. Ao confirmar, o mesmo movimento do livro credita a plataforma e debita o comerciante pela comissão; a taxa do Vibra Payments calcula-se sobre o bruto e é do comerciante. Num estorno, a comissão volta ao comerciante em proporção ao estornado. Numa subscrição, a comissão repete-se em cada renovação, e a autorização confere-se em cada ciclo: revogada, o ciclo cobra-se sem comissão, e o payment.succeeded diz platform_fee: null e platform_fee_skipped.

Para onde foi o dinheiro: settlement

O objeto payment dos eventos traz settlement: balance quando o dinheiro entrou no saldo do comerciante no Vibra Pay (todos os métodos menos a transferência), e merchant_account quando entrou direto na conta bancária dele (a transferência bancária). O net é sempre o que fica ao comerciante, amount menos fee (e menos a comissão da plataforma, quando a há): com balance, é o que entra no saldo; com merchant_account, o comerciante recebeu o amount no banco e a fee sai do saldo dele (que pode ficar negativo, e abate-se com o que entrar depois).

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json), obrigatório

amountinteiro · obrigatório: Em unidades menores inteiras. Em AOA, múltiplo de 100 (os gateways angolanos cobram kwanzas inteiros).mínimo 1
currencytexto · obrigatório: 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
descriptiontexto: O que o comprador vê que está a pagar. Obrigatória sem line_items.até 500 carateres
line_itemslista de Linha: As linhas têm de somar amount.até 100 elementos
line_items[].descriptiontexto · obrigatório: 1 a 200 carateres
line_items[].unit_amountinteiro · obrigatório: Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
line_items[].quantityinteiro · obrigatório: de 1 a 10000
payment_methodslista de texto: Vazio aceita todos os que têm gateway na moeda e no modo.
success_urltexto (URL): Para onde voltar depois de pagar, com session_id acrescentado (ou no lugar de {CHECKOUT_SESSION_ID}). Sem ele, o checkout mostra a página de confirmação da Vibra. https em produção. O regresso não é prova de pagamento. Quem chega a https://kiala.ao/obrigado?pedido=1042&session_id=cs_live_... pode ter escrito o endereço à mão. A encomenda dá-se por paga no webhook payment.succeeded, ou num GET /v1/checkout/sessions/{id} feito pelo servidor com status igual a complete; a página de regresso só mostra esse estado. Exemplo completo na descrição de POST /v1/checkout/sessions.até 2000 carateres
cancel_urltexto (URL): Para onde voltar se o comprador desistir, com session_id. https em produção.até 2000 carateres
metadataobjeto: Devolvidos tal como vieram, na sessão e nos eventos.até 50 chaves
metadata.<chave>texto: até 500 carateres
customerCliente
customer.emailtexto: Para o email com a referência, e para o recibo.
customer.nametexto: até 200 carateres
customer.phonetexto: Telemóvel angolano; guarda-se normalizado (244XXXXXXXXX).
expires_ininteiro: A vida da sessão em segundos. 86400 (24 horas) por omissão.de 900 a 86400
kindtexto: subscription cobra o primeiro ciclo de uma subscrição, que nasce quando ele é pago. O preço de cada ciclo é o amount. Chama-se kind, e não mode, porque o mode da resposta é o da chave (test ou live).um de: payment, subscription · por omissão "payment"
subscriptionPlanoDaSubscricao: Obrigatório com kind subscription, e recusado sem ele.
subscription.intervaltexto · obrigatório: De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
subscription.cyclesinteiro ou nulo: Quantos ciclos se contratam, contando o primeiro. Sem ele, renova até ser cancelada.de 1 a 1000
subscription.first_cycle_amountinteiro: O valor do primeiro ciclo, quando é mais barato do que amount (um cupão do produto que vale só no primeiro mês). O primeiro pagamento cobra-o; as renovações cobram amount. Maior do que zero, menor do que amount, e em AOA múltiplo de 100. Com Visa e Mastercard, o Stripe cobra o primeiro ciclo com o desconto e renova sozinho pelo preço cheio.mínimo 1
platform_feeComissaoDaPlataforma: A comissão da plataforma (cartão 6.6): a plataforma que a recebe, que o comerciante da chave autorizou no painel, e o valor. Numa subscrição repete-se em cada renovação.
platform_fee.platformtexto: O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório: Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1
coupontexto: O código (ou o cpn_...) de um cupão do comerciante, neste modo (cartão 4.14). Confere-se agora: um cupão que não existe, desativado, expirado, esgotado, noutra moeda, ou que não desconte neste valor dá 422 cupao_invalido. Não vai com allow_promotion_codes, nem com o first_cycle_amount de uma subscrição.até 60 carateres
allow_promotion_codesbooleano: O comprador pode escrever um código de desconto no checkout.por omissão false

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/checkout/sessions" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>" \
  -H "Content-Type: application/json" \
  -d '{"amount":1500000,"currency":"AOA","description":"Vestido de capulana","success_url":"https://kiala.ao/obrigado?pedido=1042","cancel_url":"https://kiala.ao/carrinho","metadata":{"order_id":"1042"},"customer":{"email":"comprador@exemplo.ao"}}'

Respostas

201
A sessão criada (ou a mesma, numa repetição com a mesma chave).
- Idempotent-Replayed
  true quando a resposta vem de um pedido anterior com a mesma chave.
idtexto · obrigatório
É a capacidade do comprador para abrir o checkout. Não se publica.padrão ^cs_(test|live)_[0-9A-Za-z]{32}$
objecttexto · obrigatório
um de: checkout_session
modetexto · obrigatório
um de: test, live
statustexto · obrigatório
um de: open, complete, expired
urltexto (URL) · obrigatório
O checkout alojado desta sessão.
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
descriptiontexto · obrigatório
line_itemslista de Linha · obrigatório
line_items[].descriptiontexto · obrigatório
1 a 200 carateres
line_items[].unit_amountinteiro · obrigatório
Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
line_items[].quantityinteiro · obrigatório
de 1 a 10000
payment_methodslista de texto · obrigatório
Os métodos que o checkout oferece.
success_urltexto ou nulo · obrigatório
cancel_urltexto ou nulo · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
expires_attexto (data e hora) · obrigatório
created_attexto (data e hora) · obrigatório
completed_attexto (data e hora) ou nulo · obrigatório
paymentnulo ou objeto · obrigatório
O pagamento que completou a sessão, ou null.
payment.idtexto · obrigatório
padrão ^pay_
payment.statustexto · obrigatório
um de: succeeded
payment.methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
payment.amountDinheiro · obrigatório
O que o comprador pagou, com a taxa por cima quando a há.
payment.amount.amountinteiro · obrigatório
mínimo 0
payment.amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
payment.fee_on_topnulo ou Dinheiro · obrigatório
A parte do amount que é a taxa paga pelo comprador por cima (cartão 3.5), ou null.
payment.fee_on_top.amountinteiro · obrigatório
mínimo 0
payment.fee_on_top.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
kindtexto · obrigatório
renewal é a sessão de um ciclo seguinte, que o Vibra Pay abre e manda ao cliente.um de: payment, subscription, renewal
subscriptionnulo ou objeto · obrigatório
Numa sessão de subscrição ou de renovação, o plano e a subscrição; null numa de pagamento.
subscription.idtexto ou nulo · obrigatório
null enquanto o primeiro pagamento não foi confirmado.padrão ^sub_
subscription.intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
subscription.cyclesinteiro ou nulo · obrigatório
subscription.cycleinteiro ou nulo · obrigatório
Numa de renovação, o ciclo que ela paga.
subscription.first_cycle_amountinteiro ou nulo · obrigatório
O valor do primeiro ciclo, quando é mais barato do que o amount da sessão, ou null. Numa sessão de subscrição é o que o checkout cobra.
applicationtexto ou nulo · obrigatório
A aplicação do comerciante de onde a sessão vem: a da chave de API que a criou (ou do link de cobrança), ou null. Os eventos dela levam-na em application, e só vão para os endpoints dessa aplicação.padrão ^app_
platform_feenulo ou ComissaoDaPlataforma · obrigatório
A comissão da plataforma que a sessão pede, ou null.
platform_fee.platformtexto
O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1
fee_on_topbooleano · obrigatório
O comprador paga a taxa do Vibra Pay por cima do amount (cartão 3.5): a escolha da aplicação da chave, ou a global do comerciante, no painel, congelada quando a sessão nasceu. O pagamento cobra o amount mais a taxa do método que o comprador escolhe (2,5% nos métodos de kwanza, 4% em Visa e Mastercard), e o comerciante fica com o amount. Uma renovação herda-a da sessão que criou a subscrição.
discountnulo ou discount · obrigatório
O cupão aplicado e quanto desconta (cartão 4.14), ou null. O amount é sempre o preço antes dele: o checkout cobra amount menos discount.amount. Numa sessão de renovação, é o desconto deste ciclo.
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
allow_promotion_codesbooleano · obrigatório
O comprador pode escrever um código de desconto no checkout.
JSON
```
{
  "id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
  "object": "checkout_session",
  "mode": "test",
  "status": "open",
  "url": "https://checkout.pay.vibra.ao/cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
  "amount": {
    "amount": 1500000,
    "currency": "AOA"
  },
  "description": "Vestido de capulana",
  "line_items": [],
  "payment_methods": [
    "mcx",
    "reference",
    "card"
  ],
  "success_url": "https://kiala.ao/obrigado?pedido=1042",
  "cancel_url": "https://kiala.ao/carrinho",
  "metadata": {
    "order_id": "1042"
  },
  "customer": {
    "email": "comprador@exemplo.ao",
    "name": "",
    "phone": ""
  },
  "expires_at": "2026-11-30T10:15:00Z",
  "created_at": "2026-11-29T10:15:00Z",
  "completed_at": null,
  "payment": null,
  "kind": "payment",
  "subscription": null,
  "application": null,
  "platform_fee": null,
  "fee_on_top": false
}
```
400
Falta o Idempotency-Key, ou o corpo não é JSON válido.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "idempotencia_em_falta",
  "mensagem": "Os pedidos POST precisam do cabeçalho Idempotency-Key."
}
```
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
plataforma_nao_autorizada: a sessão pede platform_fee, e o comerciante da chave não tem uma autorização ativa para essa plataforma.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "plataforma_nao_autorizada",
  "mensagem": "O comerciante desta chave não autorizou esta plataforma a ficar com comissão. A autorização faz-se no painel dele, em Plataformas."
}
```
422
Campos por corrigir (dados_invalidos, com campos; um método que não existe na moeda, por exemplo bank_transfer ou direct_debit fora de AOA, vem em campos.payment_methods), moeda ou método sem gateway configurado neste modo (moeda_sem_gateway, metodo_sem_gateway: a transferência com um comerciante sem conta nenhuma para onde transferir, ou, em produção, o débito direto sem o Proxypay DDS), a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada), ou a comissão da plataforma acima do máximo que o comerciante autorizou (comissao_acima_do_maximo: amount maior do que chão(amount da sessão × max_bps ÷ 10000)) ou inválida (comissao_invalida: zero, negativa, a própria plataforma, a deixar o comerciante sem líquido depois da taxa, ou com bank_transfer em payment_methods, que vai direta para a conta do comerciante).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "moeda_sem_gateway",
  "mensagem": "Não há nenhum gateway configurado para cobrar em USD pelos métodos card neste modo (produção)."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/checkout/sessions/{id}

Ler uma sessão de checkout

É o que se chama no regresso do comprador: antes de responder, a API pergunta ao gateway pelos pagamentos pendentes. status é complete quando a sessão está paga, e payment diz por que pagamento.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador da sessão (cs_test_... ou cs_live_...).padrão ^cs_(test|live)_[0-9A-Za-z]{32}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/checkout/sessions/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
A sessão.
idtexto · obrigatório
É a capacidade do comprador para abrir o checkout. Não se publica.padrão ^cs_(test|live)_[0-9A-Za-z]{32}$
objecttexto · obrigatório
um de: checkout_session
modetexto · obrigatório
um de: test, live
statustexto · obrigatório
um de: open, complete, expired
urltexto (URL) · obrigatório
O checkout alojado desta sessão.
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
descriptiontexto · obrigatório
line_itemslista de Linha · obrigatório
line_items[].descriptiontexto · obrigatório
1 a 200 carateres
line_items[].unit_amountinteiro · obrigatório
Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
line_items[].quantityinteiro · obrigatório
de 1 a 10000
payment_methodslista de texto · obrigatório
Os métodos que o checkout oferece.
success_urltexto ou nulo · obrigatório
cancel_urltexto ou nulo · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
expires_attexto (data e hora) · obrigatório
created_attexto (data e hora) · obrigatório
completed_attexto (data e hora) ou nulo · obrigatório
paymentnulo ou objeto · obrigatório
O pagamento que completou a sessão, ou null.
payment.idtexto · obrigatório
padrão ^pay_
payment.statustexto · obrigatório
um de: succeeded
payment.methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
payment.amountDinheiro · obrigatório
O que o comprador pagou, com a taxa por cima quando a há.
payment.amount.amountinteiro · obrigatório
mínimo 0
payment.amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
payment.fee_on_topnulo ou Dinheiro · obrigatório
A parte do amount que é a taxa paga pelo comprador por cima (cartão 3.5), ou null.
payment.fee_on_top.amountinteiro · obrigatório
mínimo 0
payment.fee_on_top.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
kindtexto · obrigatório
renewal é a sessão de um ciclo seguinte, que o Vibra Pay abre e manda ao cliente.um de: payment, subscription, renewal
subscriptionnulo ou objeto · obrigatório
Numa sessão de subscrição ou de renovação, o plano e a subscrição; null numa de pagamento.
subscription.idtexto ou nulo · obrigatório
null enquanto o primeiro pagamento não foi confirmado.padrão ^sub_
subscription.intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
subscription.cyclesinteiro ou nulo · obrigatório
subscription.cycleinteiro ou nulo · obrigatório
Numa de renovação, o ciclo que ela paga.
subscription.first_cycle_amountinteiro ou nulo · obrigatório
O valor do primeiro ciclo, quando é mais barato do que o amount da sessão, ou null. Numa sessão de subscrição é o que o checkout cobra.
applicationtexto ou nulo · obrigatório
A aplicação do comerciante de onde a sessão vem: a da chave de API que a criou (ou do link de cobrança), ou null. Os eventos dela levam-na em application, e só vão para os endpoints dessa aplicação.padrão ^app_
platform_feenulo ou ComissaoDaPlataforma · obrigatório
A comissão da plataforma que a sessão pede, ou null.
platform_fee.platformtexto
O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório
Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1
fee_on_topbooleano · obrigatório
O comprador paga a taxa do Vibra Pay por cima do amount (cartão 3.5): a escolha da aplicação da chave, ou a global do comerciante, no painel, congelada quando a sessão nasceu. O pagamento cobra o amount mais a taxa do método que o comprador escolhe (2,5% nos métodos de kwanza, 4% em Visa e Mastercard), e o comerciante fica com o amount. Uma renovação herda-a da sessão que criou a subscrição.
discountnulo ou discount · obrigatório
O cupão aplicado e quanto desconta (cartão 4.14), ou null. O amount é sempre o preço antes dele: o checkout cobra amount menos discount.amount. Numa sessão de renovação, é o desconto deste ciclo.
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
allow_promotion_codesbooleano · obrigatório
O comprador pode escrever um código de desconto no checkout.
JSON
```
{
  "id": "cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
  "object": "checkout_session",
  "mode": "test",
  "status": "complete",
  "url": "https://checkout.pay.vibra.ao/cs_test_4f8Gk2LmQ9rT1vXz7bN3cH6sW0pY5aDe",
  "amount": {
    "amount": 1500000,
    "currency": "AOA"
  },
  "description": "Vestido de capulana",
  "line_items": [],
  "payment_methods": [
    "mcx",
    "reference",
    "card"
  ],
  "success_url": "https://kiala.ao/obrigado?pedido=1042",
  "cancel_url": null,
  "metadata": {
    "order_id": "1042"
  },
  "customer": {
    "email": "",
    "name": "",
    "phone": ""
  },
  "expires_at": "2026-11-30T10:15:00Z",
  "created_at": "2026-11-29T10:15:00Z",
  "completed_at": "2026-11-29T10:17:12Z",
  "payment": {
    "id": "pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0",
    "status": "succeeded",
    "method": "mcx",
    "amount": {
      "amount": 1500000,
      "currency": "AOA"
    },
    "fee_on_top": null
  },
  "kind": "payment",
  "subscription": null,
  "application": null,
  "platform_fee": null,
  "fee_on_top": false
}
```
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há sessão com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "sessao_nao_existe",
  "mensagem": "Não há nenhuma sessão com este identificador para esta chave."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Estornos

Devolver todo ou parte de um pagamento confirmado ao comprador. Nunca mais do que se cobrou. O webhook refund.created sai quando o estorno fica aceite.

POST/v1/refunds

Estornar um pagamento, total ou parcialmente

Devolve ao comprador todo o pagamento (sem amount, estorna o que resta) ou parte dele. Pode haver vários estornos parciais do mesmo pagamento, e a soma nunca passa o que se cobrou: um estorno acima do que resta é recusado com 422 estorno_acima_do_cobrado, mesmo com dois pedidos ao mesmo tempo.

O valor sai do saldo disponível do comerciante e, quando não chega, da reserva; se nem assim chegar, o saldo fica negativo e os saques param até os pagamentos seguintes o cobrirem. A taxa da Vibra do pagamento não se devolve.

O caminho depende de como se pagou:

Visa e Mastercard (card): o gateway devolve ao cartão do comprador, e a resposta traz status succeeded (ou pending, se o gateway ainda não o deu por feito). Se o gateway recusar, status é failed, com failure_reason, e o saldo volta ao que era. Sem resposta do gateway, processing: a API volta a pedir sozinha, e o GET diz o desfecho.
Multicaixa Express, referência: a equipa do Vibra Payments devolve por transferência, e o estorno fica pending até estar feita.

O webhook refund.created chega quando o estorno fica aceite (pending ou succeeded). Em modo teste, os pagamentos por Visa e Mastercard estornam-se como pelo gateway, sem dinheiro a mexer-se, e os outros ficam pending.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json), obrigatório

payment_idtexto · obrigatório: O pagamento a estornar, como veio no payment.succeeded ou no payment da sessão.padrão ^pay_
amountinteiro: Quanto devolver, em unidades menores, na moeda do pagamento (em AOA, kwanzas inteiros). Sem ele, estorna-se o que resta.mínimo 1
reasontexto: O motivo, que volta no estorno e no webhook.até 500 carateres

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/refunds" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0","amount":500000,"reason":"Devolução parcial a pedido do cliente."}'

Respostas

201
O estorno, com o estado em que ficou.
idtexto · obrigatório
padrão ^re_
objecttexto · obrigatório
um de: refund
payment_idtexto · obrigatório
padrão ^pay_
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
statustexto · obrigatório
processing: pedido ao gateway, sem resposta ainda. pending: à espera da transferência ao comprador (ou o gateway ainda não o deu por feito). succeeded: devolvido. failed: o gateway recusou, e o saldo voltou ao que era.um de: processing, pending, succeeded, failed
reasontexto · obrigatório
failure_reasontexto
Só nos failed, a razão do gateway.
created_attexto (data e hora) · obrigatório
JSON
```
{
  "id": "re_7Tq3Mn5Wx9Yz2Ab4Cd6Ef8",
  "object": "refund",
  "payment_id": "pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0",
  "amount": {
    "amount": 500000,
    "currency": "AOA"
  },
  "status": "pending",
  "reason": "Devolução parcial a pedido do cliente.",
  "created_at": "2026-12-02T09:00:00Z"
}
```
400
Falta o Idempotency-Key, ou o corpo não é JSON válido.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "idempotencia_em_falta",
  "mensagem": "Os pedidos POST precisam do cabeçalho Idempotency-Key."
}
```
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há pagamento com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "pagamento_nao_existe",
  "mensagem": "Não há nenhum pagamento com este identificador para esta chave."
}
```
409
O pagamento não está confirmado (pagamento_nao_pago), já foi todo estornado (pagamento_ja_estornado), ou foi uma transferência bancária direta para a conta do comerciante (pago_na_conta_do_comerciante), que não passou pela Vibra e se devolve dessa conta.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "pagamento_ja_estornado",
  "mensagem": "Este pagamento já foi todo estornado."
}
```
422
O estorno passa o que resta do pagamento (estorno_acima_do_cobrado, com o que resta na mensagem), campos por corrigir (dados_invalidos; em AOA o valor é em kwanzas inteiros), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "estorno_acima_do_cobrado",
  "mensagem": "O estorno passa o que resta do pagamento: restam 1000000 AOA (em unidades menores). Nunca se estorna mais do que se cobrou."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/refunds/{id}

Ler um estorno

É o que diz o desfecho de um estorno que ficou processing ou pending.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador do estorno (re_...).padrão ^re_[0-9A-Za-z]{16,}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/refunds/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
O estorno.
idtexto · obrigatório
padrão ^re_
objecttexto · obrigatório
um de: refund
payment_idtexto · obrigatório
padrão ^pay_
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
statustexto · obrigatório
processing: pedido ao gateway, sem resposta ainda. pending: à espera da transferência ao comprador (ou o gateway ainda não o deu por feito). succeeded: devolvido. failed: o gateway recusou, e o saldo voltou ao que era.um de: processing, pending, succeeded, failed
reasontexto · obrigatório
failure_reasontexto
Só nos failed, a razão do gateway.
created_attexto (data e hora) · obrigatório
JSON
```
{
  "id": "re_7Tq3Mn5Wx9Yz2Ab4Cd6Ef8",
  "object": "refund",
  "payment_id": "pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0",
  "amount": {
    "amount": 500000,
    "currency": "AOA"
  },
  "status": "succeeded",
  "reason": "Devolução parcial a pedido do cliente.",
  "created_at": "2026-12-02T09:00:00Z"
}
```
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há estorno com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "estorno_nao_existe",
  "mensagem": "Não há nenhum estorno com este identificador para esta chave."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Cupoes

Os cupões de desconto (cartão 4.14). Aplicam-se de duas formas: o coupon na criação da sessão, ou allow_promotion_codes, que deixa o comprador escrever o código no checkout. O pagamento nasce com o valor descontado, e a taxa é sobre o que se pagou. Um cupão por pagamento.

GET/v1/coupons

Listar os cupões

Do mais recente para o mais antigo, no modo da chave.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
limit (query)inteiro: de 1 a 100 · por omissão 20
starting_after (query)texto: O id do último cupão da página anterior.padrão ^cpn_
code (query)texto: Só o cupão com este código (sem distinguir maiúsculas).

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/coupons" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
Uma página de cupões.
object"list" · obrigatório
datalista de Cupao · obrigatório
data[].idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
data[].objecttexto · obrigatório
um de: coupon
data[].modetexto · obrigatório
um de: test, live
data[].codetexto · obrigatório
padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
data[].nametexto · obrigatório
até 120 carateres
data[].percent_offinteiro ou nulo · obrigatório
de 1 a 99
data[].amount_offnulo ou Dinheiro · obrigatório
O desconto de valor fixo, na moeda em que vale, ou null.
data[].amount_off.amountinteiro · obrigatório
mínimo 0
data[].amount_off.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
data[].durationtexto · obrigatório
Numa subscrição, em quantos ciclos vale. Num pagamento único vale uma vez.um de: once, repeating, forever
data[].duration_cyclesinteiro ou nulo · obrigatório
Só no repeating.de 2 a 1000
data[].max_redemptionsinteiro ou nulo · obrigatório
mínimo 1
data[].times_redeemedinteiro · obrigatório
As sessões pagas com o cupão. O limite conta também as abertas que ainda se podem pagar.mínimo 0
data[].expires_attexto (data e hora) ou nulo · obrigatório
data[].activebooleano · obrigatório
data[].validbooleano · obrigatório
Ativo, dentro da data, e com usos por gastar.
data[].metadataobjeto · obrigatório
data[].metadata.<chave>texto
data[].created_attexto (data e hora) · obrigatório
data[].updated_attexto (data e hora) · obrigatório
has_morebooleano · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/coupons

Criar um cupão

Um cupão é de percentagem (percent_off, 1 a 99) ou de valor fixo (amount_off e currency; só vale em sessões dessa moeda, e em AOA em kwanzas inteiros). O code é o que o comprador escreve: letras, números, - e _, de 3 a 40, guardado em maiúsculas, único por comerciante e por modo. Numa subscrição, duration diz em quantos ciclos vale: once (o primeiro), repeating (os primeiros duration_cycles) ou forever.

O desconto não muda depois de criado: um desconto novo é um cupão novo.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json), obrigatório

codetexto · obrigatório: Letras, números, - e _; guarda-se em maiúsculas.3 a 40 carateres
nametexto: até 120 carateres
percent_offinteiro: Ou isto, ou amount_off com currency.de 1 a 99
amount_offinteiro: Em unidades menores. Em AOA, múltiplo de 100.mínimo 1
currencytexto: um de: AOA, USD, EUR, BRL
durationtexto · obrigatório: um de: once, repeating, forever
duration_cyclesinteiro: Obrigatório no repeating, e só nele.de 2 a 1000
max_redemptionsinteiro: mínimo 1
expires_attexto (data e hora): No futuro.
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/coupons" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>" \
  -H "Content-Type: application/json" \
  -d '{"code":"BEMVINDO10","name":"Boas-vindas","percent_off":10,"duration":"once","max_redemptions":500}'

Respostas

201
O cupão.
idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
objecttexto · obrigatório
um de: coupon
modetexto · obrigatório
um de: test, live
codetexto · obrigatório
padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
nametexto · obrigatório
até 120 carateres
percent_offinteiro ou nulo · obrigatório
de 1 a 99
amount_offnulo ou Dinheiro · obrigatório
O desconto de valor fixo, na moeda em que vale, ou null.
amount_off.amountinteiro · obrigatório
mínimo 0
amount_off.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
durationtexto · obrigatório
Numa subscrição, em quantos ciclos vale. Num pagamento único vale uma vez.um de: once, repeating, forever
duration_cyclesinteiro ou nulo · obrigatório
Só no repeating.de 2 a 1000
max_redemptionsinteiro ou nulo · obrigatório
mínimo 1
times_redeemedinteiro · obrigatório
As sessões pagas com o cupão. O limite conta também as abertas que ainda se podem pagar.mínimo 0
expires_attexto (data e hora) ou nulo · obrigatório
activebooleano · obrigatório
validbooleano · obrigatório
Ativo, dentro da data, e com usos por gastar.
metadataobjeto · obrigatório
metadata.<chave>texto
created_attexto (data e hora) · obrigatório
updated_attexto (data e hora) · obrigatório
JSON
```
{
  "id": "cpn_live_Bq2Lm4Rt8Vx1Zb6Nc3Kd0Hy7",
  "object": "coupon",
  "mode": "live",
  "code": "BEMVINDO10",
  "name": "Boas-vindas",
  "percent_off": 10,
  "amount_off": null,
  "duration": "once",
  "duration_cycles": null,
  "max_redemptions": 500,
  "times_redeemed": 0,
  "expires_at": null,
  "active": true,
  "valid": true,
  "metadata": {},
  "created_at": "2026-11-02T09:00:00Z",
  "updated_at": "2026-11-02T09:00:00Z"
}
```
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
409
Já há um cupão com este código, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "codigo_repetido",
  "mensagem": "Já tens um cupão com este código neste modo."
}
```
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/coupons/{id}

Ler um cupão

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador do cupão (cpn_test_... ou cpn_live_...).padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/coupons/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
O cupão.
idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
objecttexto · obrigatório
um de: coupon
modetexto · obrigatório
um de: test, live
codetexto · obrigatório
padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
nametexto · obrigatório
até 120 carateres
percent_offinteiro ou nulo · obrigatório
de 1 a 99
amount_offnulo ou Dinheiro · obrigatório
O desconto de valor fixo, na moeda em que vale, ou null.
amount_off.amountinteiro · obrigatório
mínimo 0
amount_off.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
durationtexto · obrigatório
Numa subscrição, em quantos ciclos vale. Num pagamento único vale uma vez.um de: once, repeating, forever
duration_cyclesinteiro ou nulo · obrigatório
Só no repeating.de 2 a 1000
max_redemptionsinteiro ou nulo · obrigatório
mínimo 1
times_redeemedinteiro · obrigatório
As sessões pagas com o cupão. O limite conta também as abertas que ainda se podem pagar.mínimo 0
expires_attexto (data e hora) ou nulo · obrigatório
activebooleano · obrigatório
validbooleano · obrigatório
Ativo, dentro da data, e com usos por gastar.
metadataobjeto · obrigatório
metadata.<chave>texto
created_attexto (data e hora) · obrigatório
updated_attexto (data e hora) · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há cupão com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "cupao_nao_existe",
  "mensagem": "Este cupão não existe neste comerciante e neste modo."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

PATCH/v1/coupons/{id}

Mudar o nome, o limite, a data de fim, o ativo ou os metadados

Só isto muda. null em max_redemptions ou em expires_at tira o limite ou a data; o limite nunca fica abaixo de times_redeemed. Um cupão desativado deixa de se poder aplicar; as sessões e as subscrições que já o têm ficam com ele.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador do cupão (cpn_test_... ou cpn_live_...).padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$

Corpo (application/json), obrigatório

nametexto: até 120 carateres
max_redemptionsinteiro ou nulo: mínimo 1
expires_attexto (data e hora) ou nulo
activebooleano
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Exemplo

Terminal

curl -s -X PATCH "https://pay-api.vibra.ao/v1/coupons/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'

Respostas

200
O cupão, já mudado.
idtexto · obrigatório
padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
objecttexto · obrigatório
um de: coupon
modetexto · obrigatório
um de: test, live
codetexto · obrigatório
padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
nametexto · obrigatório
até 120 carateres
percent_offinteiro ou nulo · obrigatório
de 1 a 99
amount_offnulo ou Dinheiro · obrigatório
O desconto de valor fixo, na moeda em que vale, ou null.
amount_off.amountinteiro · obrigatório
mínimo 0
amount_off.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
durationtexto · obrigatório
Numa subscrição, em quantos ciclos vale. Num pagamento único vale uma vez.um de: once, repeating, forever
duration_cyclesinteiro ou nulo · obrigatório
Só no repeating.de 2 a 1000
max_redemptionsinteiro ou nulo · obrigatório
mínimo 1
times_redeemedinteiro · obrigatório
As sessões pagas com o cupão. O limite conta também as abertas que ainda se podem pagar.mínimo 0
expires_attexto (data e hora) ou nulo · obrigatório
activebooleano · obrigatório
validbooleano · obrigatório
Ativo, dentro da data, e com usos por gastar.
metadataobjeto · obrigatório
metadata.<chave>texto
created_attexto (data e hora) · obrigatório
updated_attexto (data e hora) · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há cupão com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "cupao_nao_existe",
  "mensagem": "Este cupão não existe neste comerciante e neste modo."
}
```
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Subscrições

Uma sessão criada com kind: "subscription" cobra o primeiro ciclo e, paga, cria a subscrição (subscription.created). Cada ciclo seguinte é um pagamento normal, com o seu payment.succeeded e o seu recibo, e renova a subscrição (subscription.renewed). No Multicaixa Express, na referência e, em BRL, no Pix (ADR 0017), o Vibra Pay manda ao cliente, antes do fim do ciclo, um link de uso único que abre a sessão de renovação já preenchida; sem pagamento, a subscrição passa a past_due no fim do ciclo e expira cinco dias depois. Com Visa e Mastercard, renova sozinha pelo Stripe.

GET/v1/subscriptions/{id}

Ler uma subscrição

A subscrição nasce quando o primeiro pagamento de uma sessão criada com kind: "subscription" é confirmado; o id vem no subscription.created e no campo subscription.id da sessão.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador da subscrição (sub_...).padrão ^sub_[0-9A-Za-z]{22}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/subscriptions/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
A subscrição.
idtexto · obrigatório
padrão ^sub_[0-9A-Za-z]{22}$
objecttexto · obrigatório
um de: subscription
statustexto · obrigatório
past_due: o ciclo acabou sem o seguinte pago, e ainda se paga até ao fim da tolerância (o acesso mantém-se). expired: terminou sem pedido (end_reason unpaid ou completed).um de: active, past_due, cancelled, expired
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou Dinheiro
O que o primeiro ciclo custou, quando foi mais barato do que amount, ou null. As renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
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 (cycles; null quer dizer todos). O ciclo n paga amount menos discount.amount enquanto n for menor ou igual a cycles.
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
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
cycleinteiro · obrigatório
mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.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, nos dois modos, e o débito direto, contra o mandato); se a cobrança falhar, a subscrição 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
cancelled_attexto (data e hora)
cancelled_bytexto
um de: customer, merchant
ended_attexto (data e hora)
end_reasontexto
um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
padrão ^cs_
latest_payment_idtexto
O último pagamento aprovado da subscrição (o primeiro ciclo ou uma renovação), na leitura pela /v1, no cancelamento e nos eventos que o trazem.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há subscrição com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "subscricao_nao_existe",
  "mensagem": "Não há nenhuma subscrição com este identificador para esta chave."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/subscriptions/{id}/cancel

Cancelar uma subscrição

Por omissão cancela no fim do ciclo pago: a subscrição continua active até current_period_end, com cancel_at_period_end: true, e não renova. Com at_period_end: false termina já. O webhook subscription.cancelled sai no momento do pedido, nos dois casos. Numa cancelada no fim do ciclo, sai outro subscription.cancelled quando o ciclo acaba e ela termina de facto, com status cancelled, ended_at e end_reason requested: o do pedido (com status active e cancel_at_period_end: true) diz que vai acabar, e o do fim diz que acabou. Corta-se o acesso pelo status terminado.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador da subscrição (sub_...).padrão ^sub_[0-9A-Za-z]{22}$
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json)

at_period_endbooleano: por omissão true

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/subscriptions/<id>/cancel" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>"

Respostas

200
A subscrição cancelada.
idtexto · obrigatório
padrão ^sub_[0-9A-Za-z]{22}$
objecttexto · obrigatório
um de: subscription
statustexto · obrigatório
past_due: o ciclo acabou sem o seguinte pago, e ainda se paga até ao fim da tolerância (o acesso mantém-se). expired: terminou sem pedido (end_reason unpaid ou completed).um de: active, past_due, cancelled, expired
amountDinheiro · obrigatório
Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório
mínimo 0
amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou Dinheiro
O que o primeiro ciclo custou, quando foi mais barato do que amount, ou null. As renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório
mínimo 0
first_cycle_amount.currencytexto · obrigatório
um de: AOA, USD, EUR, BRL
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 (cycles; null quer dizer todos). O ciclo n paga amount menos discount.amount enquanto n for menor ou igual a cycles.
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
intervaltexto · obrigatório
De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
cycleinteiro · obrigatório
mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
methodtexto · obrigatório
Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.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, nos dois modos, e o débito direto, contra o mandato); se a cobrança falhar, a subscrição 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
cancelled_attexto (data e hora)
cancelled_bytexto
um de: customer, merchant
ended_attexto (data e hora)
end_reasontexto
um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório
padrão ^cs_
latest_payment_idtexto
O último pagamento aprovado da subscrição (o primeiro ciclo ou uma renovação), na leitura pela /v1, no cancelamento e nos eventos que o trazem.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há subscrição com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "subscricao_nao_existe",
  "mensagem": "Não há nenhuma subscrição com este identificador para esta chave."
}
```
409
A subscrição já terminou.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "subscricao_terminada",
  "mensagem": "Esta subscrição já terminou: não há nada a cancelar."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/subscriptions/{id}/portal

Um link de uso único da página do cliente

A página onde o cliente cancela, muda o método do próximo ciclo e vê os recibos, sem conta. O link serve uma vez e vale 24 horas: aberto, dá uma sessão de uma hora no checkout, e reaberto já não serve. O cliente pode também pedir os links por email, na própria página. Repetir o pedido dá outro link (a resposta não fica na memória da idempotência, porque o link é uma credencial), e os dois valem uma vez cada.

Parâmetros

Vibra-Account (cabeçalho)texto: Só para plataformas com as contas ligadas habilitadas: o mer_... de uma conta ligada da plataforma, no mesmo modo da chave. O pedido faz-se em nome dela (a sessão, o pagamento e o estorno são da conta; a platform_fee.platform pode ir vazia, e é a plataforma). Em produção, uma escrita pede a conta verificada (403 conta_por_verificar). As recusas do cabeçalho, antes da rota: 403 contas_ligadas_nao_habilitadas (a plataforma não está habilitada), 404 conta_nao_existe (não é uma conta ligada desta plataforma), 403 conta_de_outro_modo (criada com uma chave do outro modo), e 400 vibra_account_nao_serve_aqui nas rotas /v1/accounts, onde a conta vai no caminho.padrão ^mer_
id (caminho)texto · obrigatório: O identificador da subscrição (sub_...).padrão ^sub_[0-9A-Za-z]{22}$
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/subscriptions/<id>/portal" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>"

Respostas

201
O link.
objecttexto · obrigatório
um de: subscription_portal
subscriptiontexto · obrigatório
padrão ^sub_
urltexto (URL) · obrigatório
expires_attexto (data e hora) · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
404
Não há subscrição com este identificador para esta chave (o modo conta).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "subscricao_nao_existe",
  "mensagem": "Não há nenhuma subscrição com este identificador para esta chave."
}
```
409
A subscrição já terminou.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Contas ligadas

As contas ligadas (ADR 0025): uma plataforma habilitada pela equipa do Vibra Pay cria e gere pela API os vendedores que vendem por ela, e o vendedor nunca fala connosco. A plataforma entrega a verificação simplificada (o documento de identificação e o comprovativo do IBAN), cobra em nome da conta com o cabeçalho Vibra-Account em qualquer rota de /v1 (e fica com a comissão, até ao máximo da habilitação), lê o saldo, pede os saques, e recebe os eventos da conta nos webhooks dela, com account no envelope. Sem habilitação ativa, todas estas rotas dão 403 contas_ligadas_nao_habilitadas.

GET/v1/accounts

Listar as contas ligadas

Da mais recente para a mais antiga, no modo da chave.

Parâmetros

limit (query)inteiro: de 1 a 100 · por omissão 20
starting_after (query)texto: O id da última conta da página anterior.padrão ^mer_
reference (query)texto: Só a conta com esta referência.

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/accounts" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
Uma página de contas.
object"list" · obrigatório
datalista de ContaLigada · obrigatório
data[].idtexto · obrigatório
padrão ^mer_
data[].object"account" · obrigatório
data[].modetexto · obrigatório
O modo da chave que criou a conta. Uma conta ligada vive num modo só.um de: test, live
data[].nametexto · obrigatório
O nome que o comprador vê no checkout.
data[].legal_nametexto · obrigatório
O nome legal do titular, tal como no documento de identificação.
data[].tax_idtexto · obrigatório
O NIF, se o houver.
data[].emailtexto · obrigatório
data[].phonetexto · obrigatório
data[].referencetexto · obrigatório
A referência da plataforma (o id do vendedor do lado dela), única por plataforma e modo.
data[].metadatametadata · obrigatório
Os metadados que o comerciante pôs na sessão, devolvidos tal como vieram.até 50 chaves
data[].metadata.<chave>texto
até 500 carateres
data[].verificationobjeto · obrigatório
data[].verification.statustexto · obrigatório
um de: pending, in_review, verified, rejected, more_documents
data[].verification.reasontexto · obrigatório
O motivo da equipa, em rejected e more_documents.
data[].verification.missinglista de texto · obrigatório
O que falta entregar para a verificação seguir sozinha para análise.
data[].bank_accountnulo ou objeto · obrigatório
data[].bank_account.idtexto · obrigatório
padrão ^cb_
data[].bank_account.iban_last4texto · obrigatório
padrão ^[0-9A-Z]{4}$
data[].bank_account.holdertexto · obrigatório
data[].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
data[].bank_account.created_attexto (data e hora) · obrigatório
data[].documentslista de objeto · obrigatório
data[].documents[].idtexto · obrigatório
padrão ^doc_
data[].documents[].object"account_document" · obrigatório
data[].documents[].typetexto · obrigatório
um de: identity_document, bank_account_proof, other
data[].documents[].file_nametexto · obrigatório
data[].documents[].content_typetexto · obrigatório
um de: application/pdf, image/jpeg, image/png
data[].documents[].sizeinteiro · obrigatório
mínimo 1
data[].documents[].created_attexto (data e hora) · obrigatório
data[].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.
data[].payouts_enabledbooleano · obrigatório
Se a conta pode sacar: verificada, com a conta bancária verificada.
data[].created_attexto (data e hora) · obrigatório
has_morebooleano · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/accounts

Criar uma conta ligada

Cria um vendedor da plataforma, no modo da chave (uma conta ligada vive num modo só). Os eventos da conta saem pelos endpoints da aplicação da chave que a criou. Com o legal_name, um identity_document e a conta bancária com o comprovativo, a verificação segue sozinha para análise; em teste, aprova-se sozinha.

Parâmetros

Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json), obrigatório

nametexto: O nome que o comprador vê no checkout.até 120 carateres
legal_nametexto: O nome legal do titular, tal como no documento de identificação.até 200 carateres
tax_idtexto: O NIF, se o houver (9 a 14 letras e dígitos).
emailtexto
phonetexto: até 40 carateres
referencetexto: O id do vendedor do lado da plataforma, único por plataforma e modo.até 200 carateres
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/accounts" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Kizomba Eventos","legal_name":"Joana Manuel","email":"joana@kizomba.ao","phone":"+244923456789","reference":"vendedor_481","metadata":{"plano":"pro"}}'

Respostas

201
A conta criada.
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
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
409
Já há uma conta desta plataforma, neste modo, com esta referência (referencia_repetida).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/accounts/{id}

Ler uma conta ligada

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/accounts/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
A conta.
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
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

PATCH/v1/accounts/{id}

Alterar uma conta ligada

Só muda o que vier no corpo. metadata substitui os metadados todos. O nome legal e o NIF só mudam enquanto a verificação os deixar (antes de entregue, ou recusada, ou com documentos pedidos).

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$

Corpo (application/json), obrigatório

nametexto: O nome que o comprador vê no checkout.até 120 carateres
legal_nametexto: O nome legal do titular, tal como no documento de identificação.até 200 carateres
tax_idtexto: O NIF, se o houver (9 a 14 letras e dígitos).
emailtexto
phonetexto: até 40 carateres
referencetexto: O id do vendedor do lado da plataforma, único por plataforma e modo.até 200 carateres
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Exemplo

Terminal

curl -s -X PATCH "https://pay-api.vibra.ao/v1/accounts/<id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
A conta, depois da alteração.
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
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
409
O nome legal ou o NIF com a verificação em análise ou aprovada (verificacao_nao_deixa), ou a referência repetida (referencia_repetida).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/accounts/{id}/documents

Entregar um documento da verificação

O documento de identificação do titular (identity_document: bilhete de identidade ou passaporte) ou o comprovativo do IBAN (bank_account_proof), em PDF, JPEG ou PNG, até 10 MiB. O tipo do ficheiro reconhece-se pelo conteúdo. Com a conta já verificada, só entra o comprovativo, para mudar de IBAN.

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (multipart/form-data), obrigatório

O corpo tal como vem, sem campos fixos.

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/accounts/<id>/documents" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>"

Respostas

201
O documento.
idtexto · obrigatório
padrão ^doc_
object"account_document" · obrigatório
typetexto · obrigatório
um de: identity_document, bank_account_proof, other
file_nametexto · obrigatório
content_typetexto · obrigatório
um de: application/pdf, image/jpeg, image/png
sizeinteiro · obrigatório
created_attexto (data e hora) · obrigatório
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
409
A verificação está em análise (verificacao_nao_deixa), ou a conta já tem o máximo de documentos (documentos_demais).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

PUT/v1/accounts/{id}/bank_account

Definir a conta bancária dos saques

O IBAN angolano, o titular (o mesmo nome legal da conta, ou o mesmo NIF em holder_tax_id) e o comprovativo já entregue. Com a conta verificada, o IBAN novo fica pending_verification até a equipa o verificar: até lá não há saques, e nas 72 horas seguintes nenhum saque se aprova sozinho.

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$

Corpo (application/json), obrigatório

ibantexto · obrigatório: O IBAN angolano (AO06...), com ou sem espaços.
holdertexto · obrigatório: O titular, tal como no comprovativo do banco.
holder_tax_idtexto: O NIF do titular, quando o nome não bate letra a letra com o legal_name.
proof_documenttexto · obrigatório: Um documento bank_account_proof desta conta.padrão ^doc_

Exemplo

Terminal

curl -s -X PUT "https://pay-api.vibra.ao/v1/accounts/<id>/bank_account" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iban":"AO06004000010123456789012","holder":"Joana Manuel","proof_document":"doc_01JA9IBANxxxxxxxxxxxxx"}'

Respostas

200
A conta ligada, com a conta bancária nova.
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
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
409
A verificação está em análise (verificacao_nao_deixa).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/accounts/{id}/balance

Ler o saldo de uma conta ligada

Lido do livro, por moeda. available é o que se pode sacar.

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/accounts/<id>/balance" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
O saldo.
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
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/accounts/{id}/payouts

Listar os saques de uma conta ligada

Os 100 mais recentes.

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/accounts/<id>/payouts" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
Os saques.
object"list" · obrigatório
datalista de Saque · obrigatório
data[].idtexto · obrigatório
padrão ^po_
data[].object"payout" · obrigatório
data[].amountmoney · obrigatório
Dinheiro em unidades menores inteiras (cêntimos), nunca com vírgula flutuante. 1.000,00 Kz é {"amount": 100000, "currency": "AOA"}.
data[].amount.amountinteiro · obrigatório
mínimo 0
data[].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
data[].statustexto · obrigatório
pending (pedido), processing (aprovado, à espera da transferência), paid ou failed.um de: pending, processing, paid, failed
data[].failure_reasontexto
Só em payout.failed: o motivo da recusa, escrito pela equipa para o comerciante ler, ou o da devolução pelo banco.
data[].paid_attexto (data e hora)
data[].created_attexto (data e hora) · obrigatório
data[].metadatametadata
Os metadados que o comerciante pôs na sessão, devolvidos tal como vieram.até 50 chaves
data[].metadata.<chave>texto
até 500 carateres
has_morebooleano · obrigatório
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

POST/v1/accounts/{id}/payouts

Pedir um saque de uma conta ligada

Tira o valor do saldo disponível da conta para a conta bancária verificada (payout.created). Até ao limite da habilitação, sem nada que o risco aponte e sem um IBAN mudado nas últimas 72 horas, o saque aprova-se sozinho (payout.processing); os outros esperam pela equipa. A equipa faz a transferência e marca como pago (payout.paid), ou recusa, e o valor volta ao disponível (payout.failed). Em teste, o saque aprova-se e paga-se sozinho. Só em AOA, e nunca abaixo do mínimo da conta: o global (5.000 Kz de partida), ou um próprio que a equipa tenha dado à conta. A recusa (422, campo amount) diz o valor.

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$
Idempotency-Key (cabeçalho)texto · obrigatório: Um valor único por operação (um UUID serve), até 255 carateres. A mesma chave com o mesmo corpo devolve a mesma resposta durante 24 horas; com outro corpo dá 422 idempotencia_reutilizada.1 a 255 carateres

Corpo (application/json), obrigatório

amountinteiro · obrigatório: Em unidades menores; em AOA, kwanzas inteiros (múltiplo de 100). Nunca abaixo do mínimo da conta, que a equipa configura (5.000 Kz por omissão).mínimo 100
currencytexto: um de: AOA · por omissão "AOA"
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/v1/accounts/<id>/payouts" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: <chave-unica>" \
  -H "Content-Type: application/json" \
  -d '{"amount":2500000,"currency":"AOA","metadata":{"pedido_na_plataforma":"saq_9921"}}'

Respostas

201
O saque, no estado em que ficou.
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
400
Falta o Idempotency-Key num POST, ou o corpo não é o esperado.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
Sem habilitação (contas_ligadas_nao_habilitadas), ou o saque não pode ser feito (saque_recusado).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
404
A conta ligada não existe nesta plataforma, neste modo.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "conta_nao_existe",
  "mensagem": "Esta conta ligada não existe nesta plataforma, neste modo."
}
```
409
A conta por verificar (conta_por_verificar), a conta bancária por verificar (conta_bancaria_por_verificar), o saldo negativo (saldo_negativo) ou o valor acima do disponível (saldo_insuficiente).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
422
Campos por corrigir (dados_invalidos, com campos), ou a mesma Idempotency-Key com outro corpo (idempotencia_reutilizada).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

GET/v1/accounts/{id}/payouts/{payout_id}

Ler um saque de uma conta ligada

Parâmetros

id (caminho)texto · obrigatório: O identificador da conta ligada (mer_...).padrão ^mer_[0-9A-Za-z]{16,}$
payout_id (caminho)texto · obrigatório: padrão ^po_

Exemplo

Terminal

curl -s "https://pay-api.vibra.ao/v1/accounts/<id>/payouts/<payout_id>" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

Respostas

200
O saque.
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
401
Sem chave, ou com uma chave revogada, expirada ou desconhecida.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "chave_invalida",
  "mensagem": "A chave de API não é válida."
}
```
403
A conta da chave não tem as contas ligadas habilitadas.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "contas_ligadas_nao_habilitadas",
  "mensagem": "Esta conta não tem as contas ligadas habilitadas. Fala com a equipa do Vibra Pay."
}
```
404
A conta ou o saque não existe (conta_nao_existe, saque_nao_existe).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
503
Não foi possível validar a chave agora (a base não respondeu). Repetir mais tarde.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "indisponivel",
  "mensagem": "Não foi possível validar a chave. Tenta de novo."
}
```

Avisos dos gateways (interna)

Interna: não é para quem integra. A entrada dos avisos que os gateways (MoMenu, Proxypay, Stripe) mandam quando uma cobrança fica decidida. Está aqui para quem opera e para quem configura o endereço em cada gateway; nenhum SDK a chama.

POST/gateways/{gateway}sem chave

Recebe o aviso de um gateway (só os gateways chamam esta rota).

Rota pública, sem chave de API: a autorização é a assinatura de cada gateway, verificada com o segredo dele (cartão 5.1).

Gateway	Corpo	Assinatura	Segredo na API
`momenu`	JSON	`x-webhook-signature` (HMAC-SHA256 hexadecimal de `carimbo.corpo`) e `x-webhook-timestamp`	`PAYMENTS_MOMENU_WEBHOOK_SECRET`
`proxypay`	JSON do pagamento	`X-Signature` (HMAC-SHA256 hexadecimal do corpo)	`PAYMENTS_PROXYPAY_API_KEY`
`stripe`	JSON do evento	`Stripe-Signature` (`t=...,v1=...`)	`PAYMENTS_STRIPE_WEBHOOK_SECRET` (`whsec_...`)

O aviso nunca é a última palavra. Mesmo assinado, a API pergunta ao gateway pelo estado da cobrança (com a referência guardada no pagamento) e age pelo que o gateway responde: um aviso de pagamento que o gateway desmente não muda nada. O corpo de cada entrega fica guardado para auditoria, e a reentrega de um evento que já teve efeito não faz mais nada (um evento, um movimento no livro).

No stripe, as subscrições por cartão (cartão 8.2): invoice.paid e invoice.payment_succeeded de um ciclo confirmam-se contra a factura, e cada factura paga é um pagamento (com o subscription.renewed), e um só, mesmo com os dois avisos; invoice.payment_failed, customer.subscription.updated e customer.subscription.deleted confirmam-se contra a subscrição no Stripe, e dão subscription.past_due e subscription.cancelled.

No stripe, o Pix (cartão 4.10): a sessão acaba antes de o dinheiro entrar (checkout.session.completed com payment_status: unpaid, que não muda nada), e o pagamento chega em checkout.session.async_payment_succeeded (ou falha em checkout.session.async_payment_failed), confirmado contra a sessão e o payment intent no Stripe. Sem esses avisos ligados no Stripe, a consulta periódica dos pendentes confirma-o na mesma.

Respostas: 200 quando o aviso foi tratado (incluindo ignorado, desmentido ou duplicado), 401 com a assinatura errada, 503 quando o gateway deve voltar a tentar (a consulta falhou, ou falta o segredo).

Parâmetros

gateway (caminho)texto · obrigatório: um de: momenu, baipaga, proxypay, stripe

Corpo (application/json, application/xml), obrigatório

O corpo tal como vem, sem campos fixos.

Exemplo

Terminal

curl -s -X POST "https://pay-api.vibra.ao/gateways/<gateway>"

Respostas

200
O aviso foi tratado.
recebidotrue · obrigatório
JSON
```
{
  "recebido": true
}
```
401
A assinatura não confere.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "assinatura_invalida",
  "mensagem": "A assinatura do aviso não confere."
}
```
404
Não há entrada para este gateway (o de ensaio não tem).
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "gateway_desconhecido",
  "mensagem": "Não há entrada de avisos para este gateway."
}
```
413
O corpo passa de 64 KiB.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "aviso_grande_demais",
  "mensagem": "O aviso passa do tamanho máximo."
}
```
503
Não foi processado agora; o gateway deve voltar a tentar.
camposobjeto
Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório
Código estável, para o programa decidir.
mensagemtexto · obrigatório
Explicação em português, para mostrar a uma pessoa.
JSON
```
{
  "erro": "tente_mais_tarde",
  "mensagem": "O aviso não foi processado agora. Tente outra vez mais tarde."
}
```

Os modelos

Os objetos que os pedidos e as respostas usam, tal como estão em components.schemas.

Conta

merchant_idtexto · obrigatório: padrão ^mer_
nome_comercialtexto · obrigatório
modotexto · obrigatório: um de: test, live

Dinheiro

Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.

amountinteiro · obrigatório: mínimo 0
currencytexto · obrigatório: um de: AOA, USD, EUR, BRL

Metodo

Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.

Um valor simples: string, um de mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit.

Linha

descriptiontexto · obrigatório: 1 a 200 carateres
unit_amountinteiro · obrigatório: Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
quantityinteiro · obrigatório: de 1 a 10000

Cliente

emailtexto: Para o email com a referência, e para o recibo.
nametexto: até 200 carateres
phonetexto: Telemóvel angolano; guarda-se normalizado (244XXXXXXXXX).

PedidoSessao

amountinteiro · obrigatório: Em unidades menores inteiras. Em AOA, múltiplo de 100 (os gateways angolanos cobram kwanzas inteiros).mínimo 1
currencytexto · obrigatório: 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
descriptiontexto: O que o comprador vê que está a pagar. Obrigatória sem line_items.até 500 carateres
line_itemslista de Linha: As linhas têm de somar amount.até 100 elementos
line_items[].descriptiontexto · obrigatório: 1 a 200 carateres
line_items[].unit_amountinteiro · obrigatório: Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
line_items[].quantityinteiro · obrigatório: de 1 a 10000
payment_methodslista de texto: Vazio aceita todos os que têm gateway na moeda e no modo.
success_urltexto (URL): Para onde voltar depois de pagar, com session_id acrescentado (ou no lugar de {CHECKOUT_SESSION_ID}). Sem ele, o checkout mostra a página de confirmação da Vibra. https em produção. O regresso não é prova de pagamento. Quem chega a https://kiala.ao/obrigado?pedido=1042&session_id=cs_live_... pode ter escrito o endereço à mão. A encomenda dá-se por paga no webhook payment.succeeded, ou num GET /v1/checkout/sessions/{id} feito pelo servidor com status igual a complete; a página de regresso só mostra esse estado. Exemplo completo na descrição de POST /v1/checkout/sessions.até 2000 carateres
cancel_urltexto (URL): Para onde voltar se o comprador desistir, com session_id. https em produção.até 2000 carateres
metadataobjeto: Devolvidos tal como vieram, na sessão e nos eventos.até 50 chaves
metadata.<chave>texto: até 500 carateres
customerCliente
customer.emailtexto: Para o email com a referência, e para o recibo.
customer.nametexto: até 200 carateres
customer.phonetexto: Telemóvel angolano; guarda-se normalizado (244XXXXXXXXX).
expires_ininteiro: A vida da sessão em segundos. 86400 (24 horas) por omissão.de 900 a 86400
kindtexto: subscription cobra o primeiro ciclo de uma subscrição, que nasce quando ele é pago. O preço de cada ciclo é o amount. Chama-se kind, e não mode, porque o mode da resposta é o da chave (test ou live).um de: payment, subscription · por omissão "payment"
subscriptionPlanoDaSubscricao: Obrigatório com kind subscription, e recusado sem ele.
subscription.intervaltexto · obrigatório: De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
subscription.cyclesinteiro ou nulo: Quantos ciclos se contratam, contando o primeiro. Sem ele, renova até ser cancelada.de 1 a 1000
subscription.first_cycle_amountinteiro: O valor do primeiro ciclo, quando é mais barato do que amount (um cupão do produto que vale só no primeiro mês). O primeiro pagamento cobra-o; as renovações cobram amount. Maior do que zero, menor do que amount, e em AOA múltiplo de 100. Com Visa e Mastercard, o Stripe cobra o primeiro ciclo com o desconto e renova sozinho pelo preço cheio.mínimo 1
platform_feeComissaoDaPlataforma: A comissão da plataforma (cartão 6.6): a plataforma que a recebe, que o comerciante da chave autorizou no painel, e o valor. Numa subscrição repete-se em cada renovação.
platform_fee.platformtexto: O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório: Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1
coupontexto: O código (ou o cpn_...) de um cupão do comerciante, neste modo (cartão 4.14). Confere-se agora: um cupão que não existe, desativado, expirado, esgotado, noutra moeda, ou que não desconte neste valor dá 422 cupao_invalido. Não vai com allow_promotion_codes, nem com o first_cycle_amount de uma subscrição.até 60 carateres
allow_promotion_codesbooleano: O comprador pode escrever um código de desconto no checkout.por omissão false

ComissaoDaPlataforma

A comissão da plataforma (cartão 6.6): a plataforma que a recebe, que o comerciante da chave autorizou no painel, e o valor. Numa subscrição repete-se em cada renovação.

platformtexto: O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
amountinteiro · obrigatório: Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1

PlanoDaSubscricao

Obrigatório com kind subscription, e recusado sem ele.

intervaltexto · obrigatório: De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo: Quantos ciclos se contratam, contando o primeiro. Sem ele, renova até ser cancelada.de 1 a 1000
first_cycle_amountinteiro: O valor do primeiro ciclo, quando é mais barato do que amount (um cupão do produto que vale só no primeiro mês). O primeiro pagamento cobra-o; as renovações cobram amount. Maior do que zero, menor do que amount, e em AOA múltiplo de 100. Com Visa e Mastercard, o Stripe cobra o primeiro ciclo com o desconto e renova sozinho pelo preço cheio.mínimo 1

Intervalo

De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.

Um valor simples: string, um de week, month, quarter, half_year, year.

Sessao

idtexto · obrigatório: É a capacidade do comprador para abrir o checkout. Não se publica.padrão ^cs_(test|live)_[0-9A-Za-z]{32}$
objecttexto · obrigatório: um de: checkout_session
modetexto · obrigatório: um de: test, live
statustexto · obrigatório: um de: open, complete, expired
urltexto (URL) · obrigatório: O checkout alojado desta sessão.
amountDinheiro · obrigatório: Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório: mínimo 0
amount.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
descriptiontexto · obrigatório
line_itemslista de Linha · obrigatório
line_items[].descriptiontexto · obrigatório: 1 a 200 carateres
line_items[].unit_amountinteiro · obrigatório: Preço unitário em unidades menores (em AOA, kwanzas inteiros).mínimo 1
line_items[].quantityinteiro · obrigatório: de 1 a 10000
payment_methodslista de texto · obrigatório: Os métodos que o checkout oferece.
success_urltexto ou nulo · obrigatório
cancel_urltexto ou nulo · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
expires_attexto (data e hora) · obrigatório
created_attexto (data e hora) · obrigatório
completed_attexto (data e hora) ou nulo · obrigatório
paymentnulo ou objeto · obrigatório: O pagamento que completou a sessão, ou null.
payment.idtexto · obrigatório: padrão ^pay_
payment.statustexto · obrigatório: um de: succeeded
payment.methodtexto · obrigatório: Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.um de: mcx, reference, baipaga, paypay, kwik, card, pix, bank_transfer, direct_debit
payment.amountDinheiro · obrigatório: O que o comprador pagou, com a taxa por cima quando a há.
payment.amount.amountinteiro · obrigatório: mínimo 0
payment.amount.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
payment.fee_on_topnulo ou Dinheiro · obrigatório: A parte do amount que é a taxa paga pelo comprador por cima (cartão 3.5), ou null.
payment.fee_on_top.amountinteiro · obrigatório: mínimo 0
payment.fee_on_top.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
kindtexto · obrigatório: renewal é a sessão de um ciclo seguinte, que o Vibra Pay abre e manda ao cliente.um de: payment, subscription, renewal
subscriptionnulo ou objeto · obrigatório: Numa sessão de subscrição ou de renovação, o plano e a subscrição; null numa de pagamento.
subscription.idtexto ou nulo · obrigatório: null enquanto o primeiro pagamento não foi confirmado.padrão ^sub_
subscription.intervaltexto · obrigatório: De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
subscription.cyclesinteiro ou nulo · obrigatório
subscription.cycleinteiro ou nulo · obrigatório: Numa de renovação, o ciclo que ela paga.
subscription.first_cycle_amountinteiro ou nulo · obrigatório: O valor do primeiro ciclo, quando é mais barato do que o amount da sessão, ou null. Numa sessão de subscrição é o que o checkout cobra.
applicationtexto ou nulo · obrigatório: A aplicação do comerciante de onde a sessão vem: a da chave de API que a criou (ou do link de cobrança), ou null. Os eventos dela levam-na em application, e só vão para os endpoints dessa aplicação.padrão ^app_
platform_feenulo ou ComissaoDaPlataforma · obrigatório: A comissão da plataforma que a sessão pede, ou null.
platform_fee.platformtexto: O identificador do comerciante da plataforma. Obrigatório, menos com o cabeçalho Vibra-Account: aí pode faltar, e a plataforma é a da chave (ADR 0025).padrão ^mer_[0-9A-Za-z]{16,}$
platform_fee.amountinteiro · obrigatório: Em unidades menores da moeda da sessão (em AOA, múltiplo de 100). Nunca acima do máximo autorizado.mínimo 1
fee_on_topbooleano · obrigatório: O comprador paga a taxa do Vibra Pay por cima do amount (cartão 3.5): a escolha da aplicação da chave, ou a global do comerciante, no painel, congelada quando a sessão nasceu. O pagamento cobra o amount mais a taxa do método que o comprador escolhe (2,5% nos métodos de kwanza, 4% em Visa e Mastercard), e o comerciante fica com o amount. Uma renovação herda-a da sessão que criou a subscrição.
discountnulo ou discount · obrigatório: O cupão aplicado e quanto desconta (cartão 4.14), ou null. O amount é sempre o preço antes dele: o checkout cobra amount menos discount.amount. Numa sessão de renovação, é o desconto deste ciclo.
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
allow_promotion_codesbooleano · obrigatório: O comprador pode escrever um código de desconto no checkout.

Subscricao

O mesmo objeto dos eventos (contratos/eventos/objetos.schema.json#/$defs/subscription).

idtexto · obrigatório: padrão ^sub_[0-9A-Za-z]{22}$
objecttexto · obrigatório: um de: subscription
statustexto · obrigatório: past_due: o ciclo acabou sem o seguinte pago, e ainda se paga até ao fim da tolerância (o acesso mantém-se). expired: terminou sem pedido (end_reason unpaid ou completed).um de: active, past_due, cancelled, expired
amountDinheiro · obrigatório: Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório: mínimo 0
amount.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
first_cycle_amountnulo ou Dinheiro: O que o primeiro ciclo custou, quando foi mais barato do que amount, ou null. As renovações cobram amount.
first_cycle_amount.amountinteiro · obrigatório: mínimo 0
first_cycle_amount.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
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 (cycles; null quer dizer todos). O ciclo n paga amount menos discount.amount enquanto n for menor ou igual a cycles.
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
intervaltexto · obrigatório: De quanto em quanto tempo renova. Os ciclos de um mês ou mais renovam no dia do mês do primeiro pagamento (hora de Luanda): quem paga a 31 renova a 28 de fevereiro e volta ao 31 em março.um de: week, month, quarter, half_year, year
cyclesinteiro ou nulo · obrigatório
cycleinteiro · obrigatório: mínimo 1
current_period_starttexto (data e hora) · obrigatório
current_period_endtexto (data e hora) · obrigatório
methodtexto · obrigatório: Multicaixa Express, referência, a app da PayPay, o KWiK (o QR ou o código que a app de qualquer banco paga, pela PayPay), Visa e Mastercard (card, Stripe Checkout), Pix (Stripe Checkout, só em BRL), transferência bancária e débito direto (Proxypay DDS). A PayPay e o KWiK só em AOA. Os dois últimos só em AOA, e só quando pedidos por nome em payment_methods; a transferência vai direta para a conta bancária do comerciante.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, nos dois modos, e o débito direto, contra o mandato); se a cobrança falhar, a subscrição 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
cancelled_attexto (data e hora)
cancelled_bytexto: um de: customer, merchant
ended_attexto (data e hora)
end_reasontexto: um de: requested, unpaid, completed
checkout_session_idtexto · obrigatório: padrão ^cs_
latest_payment_idtexto: O último pagamento aprovado da subscrição (o primeiro ciclo ou uma renovação), na leitura pela /v1, no cancelamento e nos eventos que o trazem.padrão ^pay_
customerobjeto · obrigatório
customer.emailtexto · obrigatório
customer.nametexto · obrigatório
customer.phonetexto · obrigatório
metadataobjeto · obrigatório
metadata.<chave>texto

Cupao

idtexto · obrigatório: padrão ^cpn_(test|live)_[A-Za-z0-9]{24}$
objecttexto · obrigatório: um de: coupon
modetexto · obrigatório: um de: test, live
codetexto · obrigatório: padrão ^[A-Z0-9][A-Z0-9_-]{2,39}$
nametexto · obrigatório: até 120 carateres
percent_offinteiro ou nulo · obrigatório: de 1 a 99
amount_offnulo ou Dinheiro · obrigatório: O desconto de valor fixo, na moeda em que vale, ou null.
amount_off.amountinteiro · obrigatório: mínimo 0
amount_off.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
durationtexto · obrigatório: Numa subscrição, em quantos ciclos vale. Num pagamento único vale uma vez.um de: once, repeating, forever
duration_cyclesinteiro ou nulo · obrigatório: Só no repeating.de 2 a 1000
max_redemptionsinteiro ou nulo · obrigatório: mínimo 1
times_redeemedinteiro · obrigatório: As sessões pagas com o cupão. O limite conta também as abertas que ainda se podem pagar.mínimo 0
expires_attexto (data e hora) ou nulo · obrigatório
activebooleano · obrigatório
validbooleano · obrigatório: Ativo, dentro da data, e com usos por gastar.
metadataobjeto · obrigatório
metadata.<chave>texto
created_attexto (data e hora) · obrigatório
updated_attexto (data e hora) · obrigatório

PedidoCupao

codetexto · obrigatório: Letras, números, - e _; guarda-se em maiúsculas.3 a 40 carateres
nametexto: até 120 carateres
percent_offinteiro: Ou isto, ou amount_off com currency.de 1 a 99
amount_offinteiro: Em unidades menores. Em AOA, múltiplo de 100.mínimo 1
currencytexto: um de: AOA, USD, EUR, BRL
durationtexto · obrigatório: um de: once, repeating, forever
duration_cyclesinteiro: Obrigatório no repeating, e só nele.de 2 a 1000
max_redemptionsinteiro: mínimo 1
expires_attexto (data e hora): No futuro.
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

AlteracaoCupao

nametexto: até 120 carateres
max_redemptionsinteiro ou nulo: mínimo 1
expires_attexto (data e hora) ou nulo
activebooleano
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

PedidoEstorno

payment_idtexto · obrigatório: O pagamento a estornar, como veio no payment.succeeded ou no payment da sessão.padrão ^pay_
amountinteiro: Quanto devolver, em unidades menores, na moeda do pagamento (em AOA, kwanzas inteiros). Sem ele, estorna-se o que resta.mínimo 1
reasontexto: O motivo, que volta no estorno e no webhook.até 500 carateres

Estorno

idtexto · obrigatório: padrão ^re_
objecttexto · obrigatório: um de: refund
payment_idtexto · obrigatório: padrão ^pay_
amountDinheiro · obrigatório: Dinheiro em unidades menores inteiras, nunca com vírgula flutuante. 15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}.
amount.amountinteiro · obrigatório: mínimo 0
amount.currencytexto · obrigatório: um de: AOA, USD, EUR, BRL
statustexto · obrigatório: processing: pedido ao gateway, sem resposta ainda. pending: à espera da transferência ao comprador (ou o gateway ainda não o deu por feito). succeeded: devolvido. failed: o gateway recusou, e o saldo voltou ao que era.um de: processing, pending, succeeded, failed
reasontexto · obrigatório
failure_reasontexto: Só nos failed, a razão do gateway.
created_attexto (data e hora) · obrigatório

DadosDaContaLigada

No POST, o name é obrigatório; no PATCH, todos são opcionais.

nametexto: O nome que o comprador vê no checkout.até 120 carateres
legal_nametexto: O nome legal do titular, tal como no documento de identificação.até 200 carateres
tax_idtexto: O NIF, se o houver (9 a 14 letras e dígitos).
emailtexto
phonetexto: até 40 carateres
referencetexto: O id do vendedor do lado da plataforma, único por plataforma e modo.até 200 carateres
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Metadados

Um valor simples: object.

ContaLigada

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

DocumentoDaConta

idtexto · obrigatório: padrão ^doc_
object"account_document" · obrigatório
typetexto · obrigatório: um de: identity_document, bank_account_proof, other
file_nametexto · obrigatório
content_typetexto · obrigatório: um de: application/pdf, image/jpeg, image/png
sizeinteiro · obrigatório
created_attexto (data e hora) · obrigatório

NovaContaBancaria

ibantexto · obrigatório: O IBAN angolano (AO06...), com ou sem espaços.
holdertexto · obrigatório: O titular, tal como no comprovativo do banco.
holder_tax_idtexto: O NIF do titular, quando o nome não bate letra a letra com o legal_name.
proof_documenttexto · obrigatório: Um documento bank_account_proof desta conta.padrão ^doc_

Saldo

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

PedidoSaque

amountinteiro · obrigatório: Em unidades menores; em AOA, kwanzas inteiros (múltiplo de 100). Nunca abaixo do mínimo da conta, que a equipa configura (5.000 Kz por omissão).mínimo 100
currencytexto: um de: AOA · por omissão "AOA"
metadataMetadados: até 20 chaves
metadata.<chave>texto: até 500 carateres

Saque

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

Erro

camposobjeto: Só no 422 dados_invalidos, com uma mensagem por campo.
campos.<chave>texto
errotexto · obrigatório: Código estável, para o programa decidir.
mensagemtexto · obrigatório: Explicação em português, para mostrar a uma pessoa.

Saude

estadotexto · obrigatório: um de: ok, degradado
versaotexto · obrigatório: A versão da construção, ou dev em desenvolvimento.
committexto · obrigatório: O commit da construção, ou dev em desenvolvimento.
basetexto · obrigatório: um de: ok, falhou