API BridgePay

Documentação da API

Integre pagamentos M-Pesa e e-Mola, gerencie produtos, pedidos e webhooks programaticamente. Uma API REST simples, pensada para o mercado moçambicano.

Introdução

A API da BridgePay é REST: usa URLs previsíveis, recebe e devolve JSON, e usa os códigos de status HTTP padrão. Toda requisição autenticada é feita por HTTPS.

URL basehttps://pay.bridgepay.site/api/v1

Valores monetários em MZN (meticais), na unidade principal (ex.: 150.00).
Datas em ISO 8601 (UTC).
Autenticação via token Bearer (ver Autenticação).

Início rápido

Em três passos você faz sua primeira chamada autenticada:

No painel, vá em Programador → Chaves de API e crie uma chave. Você recebe um client_id e um client_secret (bp_live_…).
Troque essas credenciais por um access_token no endpoint de OAuth.
Use o token no header Authorization das chamadas seguintes.

# 1. Obter o token
curl -X POST https://pay.bridgepay.site/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "bp_live_xxxxxxxx"
  }'

# 2. Usar o token
curl https://pay.bridgepay.site/api/v1/orders \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Autenticação

A API usa o fluxo OAuth 2.0 client_credentials. Você troca o client_id + client_secret por um access_token (Bearer), que é enviado em todas as chamadas.

POST/v1/oauth/token

Aceita JSON ou application/x-www-form-urlencoded. Campos: client_id, client_secret.

curl -X POST https://pay.bridgepay.site/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "SEU_CLIENT_ID", "client_secret": "bp_live_xxxx" }'

Resposta

{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "token_type": "Bearer",
  "scope": "read write products offers orders webhooks"
}

Guarde o client_secret com segurança (nunca no frontend). Ele é mostrado só uma vez; se vazar, revogue a chave no painel e gere outra.

Pedidos

Lista as vendas confirmadas da sua conta.

GET/v1/orders

curl https://pay.bridgepay.site/api/v1/orders \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Resposta

{
  "success": true,
  "orders": [
    {
      "id": "a1b2c3d4-...",
      "customer": { "name": "Cliente BridgePay", "email": "cliente@exemplo.mz", "phone": "+258841234567" },
      "product": { "id": "prod_...", "name": "Curso de Excel" },
      "offer": { "id": "offer_prod_...", "name": "Curso de Excel (Oferta Padrão)", "price": 500 },
      "amount": 500,
      "currency": "MZN",
      "status": "paid",
      "created_at": "2026-07-22T10:00:00.000Z"
    }
  ]
}

Produtos

Liste seus produtos ou cadastre um novo.

GET/v1/products

curl https://pay.bridgepay.site/api/v1/products \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

POST/v1/products

Campos obrigatórios: title, price_mzn. Opcional: description.

curl -X POST https://pay.bridgepay.site/api/v1/products \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Meu Ebook", "price_mzn": 250, "description": "..." }'

Resposta

{
  "success": true,
  "product": { "id": "prod_...", "title": "Meu Ebook", "price_mzn": 250 }
}

Ofertas

Cada produto expõe uma oferta padrão (mapeamento 1:1), útil para integrações que trabalham com o conceito de oferta.

GET/v1/offers

curl https://pay.bridgepay.site/api/v1/offers \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Resposta

{
  "success": true,
  "offers": [
    {
      "id": "offer_prod_...",
      "product_id": "prod_...",
      "name": "Curso de Excel (Oferta Padrão)",
      "price": 500,
      "currency": "MZN",
      "status": "active",
      "created_at": "2026-07-22T10:00:00.000Z"
    }
  ]
}

Webhooks (API)

Gerencie o endpoint que recebe seus eventos de venda.

GET/v1/webhooks

POST/v1/webhooks

Cria ou atualiza. Campos: url (obrigatório), events (array; padrão ["purchase_approved"]). A resposta inclui o secret (whsec_…) usado para assinar as entregas.

curl -X POST https://pay.bridgepay.site/api/v1/webhooks \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://seu-site.com/webhook", "events": ["payment.completed"] }'

Resposta

{
  "success": true,
  "message": "Webhook configurado com sucesso.",
  "webhook": {
    "url": "https://seu-site.com/webhook",
    "secret": "whsec_xxxxxxxx",
    "events": ["payment.completed"],
    "is_active": true
  }
}

DELETE/v1/webhooks

Remove a configuração de webhook da sua conta.

Receber webhooks

Quando uma venda é aprovada, a BridgePay envia um POST para a sua url com o corpo do evento. Cada entrega inclui o header x-bridgepay-signature para você verificar a autenticidade.

Resposta

POST /seu-webhook
x-bridgepay-signature: t=1753180800,v1=<hmac_sha256_hex>

{
  "event": "payment.completed",
  "data": {
    "id": "tx_...",
    "customer": { "name": "...", "email": "...", "phone": "+258..." },
    "product": { "id": "prod_...", "name": "...", "price": 500 },
    "amount": 500,
    "currency": "MZN",
    "status": "paid",
    "created_at": "2026-07-22T10:00:00.000Z"
  }
}

Verificar a assinatura

A assinatura é o HMAC-SHA256 de `${timestamp}.${corpo_bruto}` usando o seu whsec_…. Compare em tempo constante:

# Pseudocódigo:
# header = "t=<ts>,v1=<sig>"
# esperado = HMAC_SHA256(secret, ts + "." + corpo_bruto)
# valido = (sig === esperado)

Responda 2xx rapidamente. Se sua URL falhar, a entrega é registrada com o erro para você reprocessar.

Códigos de erro

A API usa os códigos de status HTTP convencionais. O corpo traz um campo error com a descrição.

Status	Significado
200	Sucesso.
400	Requisição inválida (campos faltando ou malformados).
401	Token ausente, inválido ou chave desativada.
404	Recurso não encontrado.
429	Muitas requisições — aguarde e tente de novo.
500	Erro interno — tente novamente com backoff.

Suporte

Precisa de ajuda com a integração? Fale com a nossa equipe:

E-mailsuporte@bridgepay.site

WhatsApp+258852453741