@ekzs/connect

TypeScript SDK for e-Kwanza Pagamento Integrado v2.4 — abstracts the three payment rails:

| Rail | Method | Customer experience | |------|--------|---------------------| | gpo | AppyPay charges | Multicaixa Express push | | emis_ref | AppyPay charges (REF_) | Pay at ATM / home banking | | ticket | Ticket API | SMS code + QR in é-Kwanza wallet |

Install

npm install @ekzs/connect

Quickstart

import { EkzConnect } from "@ekzs/connect";

const ekz = new EkzConnect({
  clientId: process.env.EKWANZA_CLIENT_ID!,
  clientSecret: process.env.EKWANZA_CLIENT_SECRET!,
  merchantIdentifier: process.env.EKWANZA_MERCHANT_ACCOUNT!,
  apiKey: process.env.EKWANZA_API_KEY!,
  paymentMethodIdGpo: process.env.EKWANZA_PAYMENT_METHOD_GPO,
  paymentMethodIdEmisRef: process.env.EKWANZA_PAYMENT_METHOD_REF,
  appyWinrestEndpoint: process.env.EKWANZA_APPY_WINREST_ENDPOINT,
  notificationToken: process.env.EKWANZA_NOTIFICATION_TOKEN,
  partnerRegistrationNumber: process.env.EKWANZA_COMPANY_REGISTRATION,
  env: "sandbox",
});

// Multicaixa Express
await ekz.gpo.charge({
  amountAoa: 15000,
  merchantTransactionId: "ORDER-001",
  phoneNumber: "935095730",
});

// Referência EMIS
await ekz.emisRef.charge({
  amountAoa: 15000,
  merchantTransactionId: "ORDER-002",
});

// Ticket / QR / SMS
await ekz.ticket.create({
  amountAoa: 15000,
  merchantTransactionId: "ORDER-003",
  mobileNumber: "935095730",
});

// Webhook
const event = ekz.webhooks.normalize(req.body);
if (event.status === "paid") { /* fulfill order */ }

Webhook verification (Ticket)

const valid = ekz.webhooks.verifyTicketSignature({
  signature: req.headers["x-signature"],
  body: req.body,
});

EKWANZA_APPY_WINREST_ENDPOINT is required for AppyPay-backed rails (gpo and emis_ref). EKWANZA_CHARGES_URL is optional; by default the SDK selects sandbox or production charge endpoints from EKWANZA_ENV.

Built for Ekz Connect — merchant portal + developer sandbox.