Documentação para programadores

API NERIAYMA

Integre pagamentos em Kwanza e internacionais no seu site, app ou sistema em minutos. Sandbox incluído para testar sem dinheiro real.

Criar conta de teste Ver primeiro pagamento

Assinatura HMAC

Webhooks assinados para validar a origem de cada evento.

REST + JSON

Endpoints simples com respostas JSON previsíveis.

Multimoeda

AOA, USD, EUR e BRL com conversão automática.

Checkout ou iframe

Redirecione ou embeba o pagamento no seu site.

Autenticação

Todas as chamadas usam uma chave de API no cabeçalho Authorization. Crie chaves de teste (nry_test_) e de produção (nry_live_) no painel, em Programadores.

cURL / JSON

curl https://neriayma.lovable.app/api/public/v1/payments \
  -H "Authorization: Bearer nry_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Criar um pagamento

Cria uma cobrança e devolve o URL de checkout. Para Multicaixa Express devolve o frame_url; para QR No Express também; para cartão/Pix/Multibanco devolve redirect_url da Stripe. amount é sempre em cêntimos (ex.: 25000 = Kz 250,00).

cURL / JSON

POST https://neriayma.lovable.app/api/public/v1/payments
{
  "amount": 25000,
  "currency": "AOA",
  "method": "multicaixa_express",
  "description": "Plano mensal",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.ao",
    "phone": "+244900000000"
  },
  "success_url": "https://seusite.ao/obrigado",
  "cancel_url": "https://seusite.ao/cancelado"
}

// Resposta
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "N7K3M2QW9ABX",
  "status": "pending",
  "amount": 25000,
  "currency": "AOA",
  "method": "multicaixa_express",
  "frame_url": "https://pagamentonline.emis.co.ao/...",
  "checkout_url": "https://neriayma.lovable.app/pagar/api-n7k3m2qw9abx"
}

Consultar estado

Obtenha o estado atual de um pagamento. Para Stripe, o estado é sincronizado em tempo real com a sessão de checkout.

cURL / JSON

GET https://neriayma.lovable.app/api/public/v1/payments/{id}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "N7K3M2QW9ABX",
  "status": "paid",
  "amount": 25000,
  "currency": "AOA",
  "method": "multicaixa_express",
  "paid_at": "2026-08-23T10:30:00.000Z",
  "created_at": "2026-08-23T10:15:00.000Z"
}

Métodos suportados

Kwanza (AOA): multicaixa_express e reference (QR No Express). Internacionais: card, pix e multibanco. Moedas aceites: AOA, USD, EUR, BRL.

cURL / JSON

// Kwanza (AOA)
"method": "multicaixa_express"
"method": "reference"

// Internacional
"method": "card"       // EUR/USD
"method": "pix"         // BRL
"method": "multibanco"  // EUR

Integrar no site

A forma mais simples é redirecionar o cliente para checkout_url. Para uma experiência embed, use o frame_url dentro de um iframe. No fim, o cliente é redirecionado para success_url ou cancel_url.

cURL / JSON

// Redirecionamento simples
window.location.href = data.checkout_url;

// Embed com iframe
<iframe
  src={data.frame_url}
  width="100%"
  height="520"
  frameBorder="0"
/>

Webhooks

Cada entrega inclui o cabeçalho X-Neriayma-Signature com um HMAC SHA-256 do corpo, calculado com o segredo do endpoint. Valide sempre a assinatura antes de processar.

cURL / JSON

X-Neriayma-Event: payment.completed
X-Neriayma-Signature: sha256=<hmac>

{
  "id": "...",
  "event": "payment.completed",
  "created_at": "2026-08-23T10:30:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "N7K3M2QW9ABX",
    "amount": 250,
    "currency": "AOA",
    "method": "multicaixa_express",
    "status": "paid"
  }
}

Pronto para integrar?

Crie a sua conta, gere chaves de teste e comece a cobrar em Kwanza hoje mesmo.

Começar integração