@devhubpty/yappy

SDK for Yappy (Banco General) mobile payment integration in Panama.

Part of the @panama-payments monorepo.

Features

• Server-side client (YappyClient) with automatic retry, structured logging, and PCI-safe sanitization via @devhubpty/core
• Webhook validation with HMAC-SHA256 and crypto.timingSafeEqual
• React hooks and components for both the official web component and fully custom UIs
• Vanilla JS integration for Vue, Svelte, Angular, and plain HTML
• TypeScript-first with strict mode and full JSDoc documentation
• Test utilities for generating valid webhook payloads

Installation

npm install @devhubpty/yappy @devhubpty/core

Quick Start

Server

import { YappyClient } from '@devhubpty/yappy/server';

const yappy = new YappyClient({
  merchantId: process.env.YAPPY_MERCHANT_ID!,
  urlDomain: process.env.YAPPY_URL_DOMAIN!,
  environment: 'sandbox',
});

const result = await yappy.initCheckout({
  ipnUrl: 'https://api.mystore.com/webhooks/yappy',
  total: '25.00',
  subtotal: '25.00',
  discount: '0.00',
  taxes: '0.00',
});

React (Web Component)

import { YappyButton } from '@devhubpty/yappy/react';

<YappyButton
  checkoutEndpoint="/api/yappy/checkout"
  onSuccess={(detail) => router.push('/success')}
  environment="sandbox"
/>

React (Custom UI)

import { useYappyPendingCheck, YappyPhoneInput, YappyPendingModal } from '@devhubpty/yappy/react';

const { status, timeLeft, startPayment, cancelPayment } = useYappyPendingCheck({
  checkoutEndpoint: '/api/yappy/checkout',
  statusEndpoint: '/api/yappy/status',
  onSuccess: ({ orderId }) => router.push(`/success?order=${orderId}`),
});

Webhook

import { validateYappyHash, YappyStatus } from '@devhubpty/yappy/server';

const result = validateYappyHash(req.query, process.env.CLAVE_SECRETA!);
if (result.valid && result.status === YappyStatus.Executed) {
  await fulfillOrder(result.orderId);
}

Documentation

• Getting Started -- 7-step credential guide
• Payment Flows -- Mermaid diagrams for all flows
• Integration Guide -- React, vanilla JS, webhooks
• API Reference -- All exports and types
• Environment Variables -- Configuration reference
• Database Model -- Suggested schema

Package Exports

| Entry Point | Description | |-------------|-------------| | @devhubpty/yappy/server | YappyClient, webhook utilities, error classes | | @devhubpty/yappy/react | React hooks and components | | @devhubpty/yappy/vanilla | Framework-agnostic web component integration |

Contributors

• captainsparrow10
• Reddsito

License

MIT