EDPay JavaScript & TypeScript SDK

Biblioteca oficial para Node.js, Next.js, Express e runtimes modernos (Bun, Deno, Cloudflare Workers), além de módulo dedicado para checkout e modais no frontend do navegador.

edutecka/edpay-javascript-sdk

Produção v1.3.0

Repositório oficial no GitHub com código aberto sob licença MIT.

Ver no GitHub

Instalação via NPM

Instale a biblioteca utilizando npm, pnpm ou yarn:

Terminal

npm install @edutecka-mz/edpay-sdk

Inicialização do Cliente

Configure a instância com as credenciais do seu projeto:

edpay.ts

import { EDPayClient } from "@edutecka-mz/edpay-sdk";

// Inicializar com chaves de API (Server-to-Server)
const edpay = new EDPayClient({
  publicKey: process.env.EDPAY_PUBLIC_KEY!,
  privateKey: process.env.EDPAY_PRIVATE_KEY!,
  baseUrl: "https://api-pay.edutecka.com", // Opcional
});

Criar Pagamento Multicanal (Backend Server-to-Server)

Exemplo de criação de pagamento com tipagem TypeScript e promessas assíncronas:

create-payment.ts

// Criar pagamento multi-gateway agnóstico
const payment = await edpay.payments.create({
  amount: 1500, // 1.500,00 MZN
  currency: "MZN",
  reference: "FAT-2026-003",
  description: "Licenciamento de Software",
  customer: {
    name: "Teresa Langa",
    email: "[email protected]",
    phone: "+25884xxxxxxx",
  },
  metadata: {
    system_user_id: "usr_55102",
  },
}, {
  idempotencyKey: "req_order_js_98414",
});

console.log("ID do Pagamento:", payment.data.id);
console.log("Estado:", payment.data.status);

Integração do Checkout no Frontend (Navegador)

Utilize o módulo frontend ou o script standalone /v1/edpay.js para abrir o checkout seguro em modal sobreposto ou embuti-lo na página:

frontend-checkout.ts

// 1. Instalação / Importação Frontend ou CDN:
// <script src="https://pay.edutecka.com/v1/edpay.js"></script>
import { EDPay } from "@edutecka-mz/edpay-sdk/frontend";

// 2. Inicializar cliente frontend com Chave Pública segura
const edpay = new EDPay({
  publicKey: "pk_live_019283019283abcdef",
});

// 3. Abrir Checkout em Modal ou Embutir em Container
edpay.checkout({
  paymentUrl: "https://pay.edutecka.com/pay?token=tok_982f1b4c7a10",
  mode: "modal", // 'modal' | 'embedded' | 'redirect'
  onSuccess: (payment) => {
    console.log("Pagamento confirmado com sucesso:", payment);
    window.location.href = "/pedidos/sucesso";
  },
  onError: (err) => {
    console.warn("Pagamento não concluído:", err);
  },
  onClose: () => {
    console.log("Modal de pagamento fechado pelo cliente");
  },
});

Tratamento de Webhooks no Next.js (App Router)

Implementação padrão de Route Handler com validação de assinatura:

src/app/api/webhooks/edpay/route.ts

// Next.js App Router (src/app/api/webhooks/edpay/route.ts)
import { NextResponse } from "next/server";
import { edpay } from "@/lib/edpay";

export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-edpay-signature") || "";
  const webhookSecret = process.env.EDPAY_WEBHOOK_SECRET!;

  // Validação criptográfica da assinatura
  const isValid = edpay.webhooks.verifySignature(rawBody, signature, webhookSecret);
  if (!isValid) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const event = JSON.parse(rawBody);

  if (event.event === "payment.succeeded") {
    const payment = event.data;
    // Concluir pedido no sistema interno
  }

  return NextResponse.json({ received: true });
}