BridgePay — 07. API Reference & Public Documentation

Esta é a especificação da API oficial da BridgePay, projetada para ser servida em docs.bridgepay.site e integrada por desenvolvedores locais.

---

1. Visão Geral (Overview)

A API da BridgePay baseia-se na arquitetura REST, permitindo a integração direta de sistemas externos para processamento de pagamentos móveis (M-Pesa e e-Mola) e conciliação automática de vendas.

Base URL: https://api.bridgepay.site

Versão: Todos os endpoints usam o prefixo /v1.

Formato: Todos os payloads de requisição e resposta trafegam em JSON.

---

2. Autenticação (Authentication)

Todas as chamadas para endpoints protegidos devem incluir o cabeçalho HTTP Authorization contendo um token do tipo Bearer:

Authorization: Bearer <token_ou_api_key>

Tipos de Token Suportados:

JWT de Usuário: Gerado temporariamente após autenticação no portal do vendedor.

API Key Privada: Token persistente gerado na aba "Desenvolvedor" do dashboard (bp_live_...).

---

3. Escopos de Permissão (Scopes)

Para chaves de API (API Keys), o sistema valida permissões explícitas (escopos) associadas a cada chave no banco de dados. Caso uma chave faça uma chamada para um recurso não autorizado, a API retornará o status 403 Forbidden.

Tabela de Escopos Suportados:

| Escopo | Descrição |

| :--- | :--- |

| orders.read | Permite listar e consultar transações e assinaturas de compradores. |

| orders.write | Permite processar reembolsos, criar pedidos ou alterar status de transações. |

| products.read | Permite listar produtos digitais cadastrados no catálogo. |

| products.write | Permite cadastrar, editar e remover produtos digitais. |

| affiliates.read | Permite consultar indicações e saldos acumulados de parceiros. |

| affiliates.write | Permite registrar e aprovar novas afiliações. |

---

4. Respostas de Erro de Autenticação

Abaixo estão mapeados os retornos de segurança padrão da API:

401 Unauthorized

Retornado se o token/API Key estiver ausente, inválido ou expirado.

{
  "status": "error",
  "message": "Token ausente ou inválido.",
  "error_code": "unauthorized"
}

403 Forbidden (Insufficient Scope)

Retornado quando a chave de API é válida, mas não possui permissão para executar a ação desejada:

{
  "status": "error",
  "message": "Permission denied for this endpoint.",
  "error_code": "insufficient_scope",
  "required_scopes": ["orders.write"],
  "missing_scopes": ["orders.write"],
  "granted_scopes": ["orders.read"],
  "hint": "Adicione o escopo ausente nas configurações da chave de API no seu painel desenvolvedor."
}

---

5. Referência de Endpoints (v1)

5.1 Criar Cobrança (Initiate Checkout)

Inicia uma cobrança via push USSD diretamente para o telefone do comprador.

URL: POST /v1/checkout

Escopo necessário: orders.write

Request Body:

{
  "productId": "prod_87654a9d",
  "amount": 150.00,
  "buyerPhone": "+258841234567",
  "paymentMethod": "mpesa",
  "buyerName": "Celso de Moçambique",
  "buyerEmail": "celso@exemplo.com",
  "callbackUrl": "https://meusite.com/api/bridgepay-callback"
}

Response (200 OK - Pendente de PIN):

{
  "success": true,
  "transactionId": "tx_bridge_88746b2a",
  "status": "pending",
  "message": "Push enviado com sucesso. Aguardando inserção do PIN M-Pesa."
}

5.2 Consultar Status do Pedido (Get Status)

Obtém o estado atual de uma transação.

URL: GET /v1/checkout/:transactionId

Escopo necessário: orders.read

Response (200 OK - Confirmado):

{
  "transactionId": "tx_bridge_88746b2a",
  "status": "confirmed",
  "amount": 150.00,
  "paymentMethod": "mpesa",
  "confirmedAt": "2026-07-05T20:53:11Z"
}

---

6. Integração de Webhooks

A BridgePay envia notificações automáticas em tempo real para os servidores do vendedor sempre que o status de uma cobrança muda.

Validação de Assinatura (Segurança HMAC)

Cada payload enviado contém o cabeçalho x-bridgepay-signature. O vendedor deve validar se a assinatura recebida coincide com o hash gerado a partir do seu segredo do webhook (webhook_secret).

Fórmula da Assinatura:

x-bridgepay-signature = HMAC-SHA256(payload_body_string, webhook_secret)

Payload do Webhook (Exemplo):

{
  "event": "payment.completed",
  "data": {
    "transactionId": "tx_bridge_88746b2a",
    "amount": 150.00,
    "paymentMethod": "mpesa",
    "buyerPhone": "+258841234567",
    "status": "success",
    "timestamp": "2026-07-05T20:53:11Z"
  }
}

Vendedores devem responder 200 OK para confirmar o recebimento da notificação.