Documentação da API

Do zero ao webhook validado

Roteiro curto para sair do zero e terminar com cobrança criada, pagamento simulado e webhook validado no seu servidor. Tudo no sandbox.

Antes de começar (2 min)

  1. Conta aprovada no painel (criar conta).
  2. Desenvolvedores → Chaves de API → Nova chave, ambiente Sandbox. Copie a uw_test_....
  3. Webhooks: cadastre a URL do seu receptor e copie o segredo whsec_....

Com curl (3 min)

export UNEWAY_API_KEY=uw_test_SUA_CHAVE
export PEDIDO=pedido-$(date +%s)   # order_id precisa ser único na sua conta

# 1. A chave funciona?
curl https://api.uneway.pro/api/v1/developer/me -H "Authorization: Bearer $UNEWAY_API_KEY"

# 2. Cobrança MB WAY (Multibanco: troque para /payments/multibanco e tire o phone; Pix: /payments/europix)
curl -X POST https://api.uneway.pro/api/v1/payments/mbway \
  -H "Authorization: Bearer $UNEWAY_API_KEY" \
  -H "Idempotency-Key: $PEDIDO" \
  -H "Content-Type: application/json" \
  -d "{\"order_id\":\"$PEDIDO\",\"amount\":25.00,\"phone\":\"351912345678\"}"

# 3. Simule o pagamento (só sandbox) e consulte
curl -X POST https://api.uneway.pro/api/v1/developer/payments/$PEDIDO/simulate \
  -H "Authorization: Bearer $UNEWAY_API_KEY" -H "Content-Type: application/json" -d '{"status":"paid"}'
curl https://api.uneway.pro/api/v1/developer/payments/$PEDIDO -H "Authorization: Bearer $UNEWAY_API_KEY"

Repetir o passo 2 com a mesma Idempotency-Key devolve a mesma resposta (header Idempotent-Replayed: true) e não cria outra cobrança.

Com os scripts prontos (5 min)

Baixe uneway-examples.zip (Node 18+ ou PHP 8.1+, sem dependências). O script de integração cria MB WAY, Multibanco e Pix, repete a criação com a mesma Idempotency-Key, consulta, simula o pagamento, lista e mostra o saldo. O receptor valida a assinatura HMAC e trata o evento uma vez só.

Node
# terminal 1: receptor de webhooks
UNEWAY_WEBHOOK_SECRET=whsec_... PORT=3000 node node/webhook-receptor.mjs

# terminal 2: integração
UNEWAY_API_KEY=uw_test_... node node/integracao.mjs
PHP
# terminal 1: receptor de webhooks
UNEWAY_WEBHOOK_SECRET=whsec_... php -S 127.0.0.1:3000 php/webhook.php

# terminal 2: integração
UNEWAY_API_KEY=uw_test_... php php/integracao.php

O receptor precisa de uma URL pública (em produção, https). Para testar no seu computador use um túnel (ngrok, Cloudflare Tunnel) e cadastre essa URL em Webhooks. Cada simulação dispara payment.paid; a criação dispara payment.created.

Antes de ir para produção

  • Libere o pedido só no webhook payment.paid com assinatura válida, nunca no retorno da criação.
  • Trate o evento pelo id (o mesmo evento pode chegar mais de uma vez) e responda 2xx em até 10 s.
  • Guarde a Idempotency-Key junto com o pedido e reenvie a mesma em retentativas.
  • Confira erros pelo código (error.code ou error_code) e registre o request_id.
  • Troque para a chave uw_live_ (conta aprovada e e-mail confirmado) e o segredo de produção.