Engineering · 11 min de leitura
Para programadores
Uma API limpa para cobranças e pagamentos.
Chaves OAuth2, uma sandbox, pedidos de pagamento ao estilo Daraja e webhooks assinados — integre numa tarde.
Chaves sandbox gratuitas em minutos. Chaves live após uma breve revisão.
# 1. Exchange your key pair for a 1-hour token curl -s https://pesa-bridge.com/api/bridgepay/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{"client_id":"pk_test_…","client_secret":"sk_test_…"}' # 2. Push a payment prompt to the customer's phone curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/stk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"payer_msisdn":"254708374149","amount":250, "reference":"INV-1001","idem":"inv-1001-1"}'← 200 {"charge_ref":"STK0000123","state":"pending"}→ webhook charge.completed KES 250.00 ✓
Guia rápido
Do zero a uma encomenda paga em quatro passos
Tudo funciona no sandbox com chaves de teste, para construir o fluxo completo antes de qualquer dinheiro real se mover.
- 1
Crie uma conta
Registe-se na consola do programador. As chaves de teste e live são emitidas de imediato.
/developer/signup - 2
Obtenha um token
Troque o seu par de chaves por um token Bearer válido durante uma hora.
POST /oauth/token - 3
Cobre um telemóvel
Envie um pedido de pagamento. O cliente aprova no próprio telemóvel com o seu PIN.
POST /partner/stk - 4
Receba o webhook
Um evento charge.completed assinado informa o seu servidor de que a encomenda está paga.
charge.completed ✓
O que pode construir
Uma só API para receber, pagar e tudo o que está à volta
53 endpoints em 12 grupos, com uma única forma de autenticação e um único formato de erro.
Concebida para dinheiro
Uma API que se comporta como um sistema de pagamentos.
A maioria das APIs move dados. Esta move dinheiro — por isso é idempotente, assinada e construída em torno de um ciclo de vida de cobrança em que pode confiar.
A autenticação é OAuth2 client-credentials: troca uma chave e um segredo por um token bearer de curta duração. Cada chamada que altera estado transporta uma chave de idempotência, para que uma repetição por falha de rede liquide exatamente uma vez — a propriedade mais importante quando há dinheiro real envolvido.
Uma cobrança é uma cobrança. Envia-a para o número de um cliente; um pedido de pagamento surge no telemóvel; ele confirma com um PIN. A cobrança percorre os estados pendente → autorizada → concluída (ou recusada / expirada / falhada), e o resultado chega-lhe de duas formas: consultando o endpoint de estado ou — melhor — recebendo um webhook no momento em que muda.
Os webhooks são assinados com HMAC-SHA256 usando um segredo que só você e o PesaBridge partilham, e reenviados com recuo progressivo até o seu endpoint confirmar — para que possa construir sobre eles sem receio de um evento perdido ou forjado. Os endpoints de saldo e transações fecham o ciclo da reconciliação, e uma sandbox executa o mesmo contrato, para que lance com confiança.
Ciclo de vida da cobrança
pendingauthorisedcompleteddeclinedexpiredfailed
webhook · charge.completed
{
"event": "charge.completed",
"charge_ref": "STK9F2A",
"amount": 250.00,
"currency": "KES",
"state": "completed",
"signature": "hmac-sha256…"
}Ferramentas
Mais do que uma API: as ferramentas à volta
Explore, teste e depure a sua integração sem escrever código descartável nem publicar um servidor.
Referência da API
Uma superfície pequena e previsível.
POST
/oauth/tokenTroque credenciais de cliente por um token bearer.POST
/partner/stkEnvie uma cobrança (pedido de pagamento) a um cliente.GET
/partner/statusConsulte o estado de uma cobrança.GET
/partner/balanceConsulte o saldo de uma conta de cobrança.POST
/biz/requestPedido de pagamento do comerciante.POST
/ussdCallback do gateway de menus USSD.Segurança e conformidade
A confiança é o produto.
Os serviços financeiros vivem ou morrem pela exatidão e pelo controlo. O PesaBridge incorpora ambos no núcleo.
Partidas dobradas por construção
Cada movimento regista débitos e créditos equilibrados — os livros reconciliam a zero, sempre.
PIN, KYC e limites
Níveis de KYC configuráveis, limites por transação e diários, tentativas de PIN e bloqueio de carteira.
Idempotente e reversível
As chaves de idempotência impedem cobranças em duplicado; um motor de reversão unificado desfaz qualquer departamento.
Webhooks assinados
Assinaturas HMAC-SHA256 e reenvios para que os sistemas parceiros confiem em cada callback.
Trilho de auditoria completo
Lançamentos de razão imutáveis e histórico de transações para reguladores e disputas.
Conformidade por país
Tipos de documento, regras de KYC e tarifas mudam com o mercado, a partir da configuração.
Entrar em produção
Do sandbox à produção sem reescrever uma linha
O mesmo código funciona nos dois modos: a chave que usa decide qual. Quando a integração estiver pronta, peça acesso live e troque as chaves.
SandboxRevisãoLive
- Assinaturas dos webhooks verificadas, com uma janela temporal
- Uma chave de idempotência em cada cobrança e pagamento
- Chaves secretas apenas no seu servidor
- Um endpoint de webhook live com o seu próprio segredo de assinatura
- Conciliação diária com a API de transações
190+
Países onde pode lançar
4
Aplicações nativas, uma plataforma
4
Canais — App · USSD · Web · API
100%
Partidas dobradas, sempre equilibrado
Perguntas frequentes
Perguntas, respondidas.
O PesaBridge é uma plataforma que partilho ou é minha?
É sua. O PesaBridge é um produto que a BridgeERP revende — cada operador tem a sua própria implementação, com marca e configuração próprias. Sem base de dados partilhada, sem superadministrador partilhado.
Que países e moedas são suportados?
Todos. País, moeda, idioma e regras de KYC são configuração extraída do conjunto ISO completo — não estão fixos no código. Temos mercados ativos hoje e criamos novos sem uma reescrita.
Funciona em telemóveis básicos?
Sim. A carteira completa funciona em USSD — enviar, levantar, pagar contas, comprar em lojas, saldo de telemóvel, saldo e extratos — liquidando na mesma razão das apps.
Posso ligar os meus próprios bancos e canais de pagamento?
Sim. Os canais são adaptadores plugáveis — bancos, mobile money, cartões e PSPs — por isso liga apenas o que o seu mercado precisa.
Com que rapidez podemos entrar em produção?
Semanas, não anos. Configure a sua marca e país, ligue os seus canais, depois publique as suas apps, código USSD e portais web a partir de uma só plataforma.
É seguro e auditável?
Cada movimento é de partidas dobradas e equilibrado a zero, protegido por PIN e KYC, com webhooks assinados e um trilho de auditoria completo para os reguladores.
Que apps recebem os operadores e os seus clientes?
Quatro aplicações Android nativas: uma aplicação de Utilizador para clientes, uma aplicação de Agente / Superagente para depósitos, levantamentos e float, uma aplicação de Comerciante para receber e liquidar, e uma aplicação de Empresa para pagamentos em massa com dupla aprovação, que também funciona como portal web. As versões iOS estão no roteiro.
Como funciona a liquidação e a reconciliação?
Os fundos liquidam na carteira relevante em tempo real. Cada transação produz lançamentos equilibrados na razão que pode reconciliar, com extratos e exportações, e uma ponte de razão geral para o seu sistema contabilístico.
Consegue gerir crédito, poupanças e finanças de grupo?
Sim — crédito por descoberto, empréstimos de microfinança com planos e carteira em risco, poupanças com objetivos e grupos de poupança (chama / cadeia) fazem parte da plataforma e ativam-se por mercado.
Suportam desembolso em massa para salários, ajudas ou subsídios?
Sim. O portal Corporativo e a API fazem pagamentos em massa para milhares de carteiras com aprovação maker/checker, listas de beneficiários, agendamento e reconciliação completa.
O que é preciso para o gerir no dia a dia?
Um único painel de administração do operador gere marca, tarifas, KYC, a rede de agentes e comerciantes, a razão, reversões, apoio e indicadores — sem código para as operações do dia a dia.
Quem é dono da implementação e dos dados?
Você. Cada operador gere a sua própria implementação com a sua própria base de dados — com marca e configuração próprias. É um produto que revende como seu, não um inquilino SaaS partilhado.
Leitura recomendada
Guias da equipa PesaBridge
Artigos em inglês.
Continue a explorar
Para onde ir a seguir
Pronto para lançar a sua carteira?
Agende uma demonstração e criamos a sua marca, país e canais — e mostramos-lhe as apps, o painel e a API.
Prefere falar? Ligue para +254 746 883809