基金支付

基于反应的综合支付 SDK 将 Fundly 的支付能力整合到您的应用程序中 。 支持多种支付模式,包括UPI,QR代码,现金,支票,和Fundly Pay.

* 安装

npm install @fundly.ai/payment-sdk

QQ 快速启动

基本用途( 反应)

import { PaymentOptionPage, sdkConfig } from '@fundly.ai/payment-sdk';
import '@fundly.ai/payment-sdk/css';

function App() {
  // Configure SDK callbacks (optional but recommended)
  React.useEffect(() => {
    sdkConfig.configure({
      onNavigateHome: () => {
        console.log('User wants to go back');
        // Handle navigation in your app
      },
      onShareText: (text) => {
        console.log('Share text:', text);
        // Handle text sharing (e.g., payment link)
      },
      onShareImage: (base64Data, fileName, fileType) => {
        console.log('Share image:', fileName);
        // Handle image sharing (e.g., receipt)
      },
      onOpenCamera: async () => {
        // Return captured image as base64
        return { name: 'photo.jpg', type: 'image/jpeg', data: 'base64...' };
      },
      onOpenGallery: async () => {
        // Return selected image as base64
        return { name: 'image.jpg', type: 'image/jpeg', data: 'base64...' };
      }
    });
  }, []);

  return (
    <PaymentOptionPage
      config={{
        environment: "production", // "production", "preprod", or "uat" (default: "production")
        // Preferred (X-40): pass your host app's own access token instead — see
        // "Authentication (X-40)" below. partnerCredentials is @deprecated but still works.
        partnerCredentials: {
          username: "YOUR_USERNAME",
          password: "YOUR_PASSWORD"
        },
        distributorIdnum: "YOUR_DISTRIBUTOR_ID",
        chemistId: "YOUR_CHEMIST_ID", // Either chemistId or leadId is required
        // leadId: "YOUR_LEAD_ID", // Alternative to chemistId for lead-based payments
        typeOfApp: "FUNDLY_CUSTOMER_APP", // or "FUNDLY_COLLECT_APP"
        paymentInvoice: [
          { invoiceId: "INV001", paidAmount: 1000 }
        ],
        payableValue: "1000",
        paymentType: "INVOICE_COLLECT", // or "DIRECT_COLLECT"
      }}
      onPaymentCollected={(response) => {
        console.log('Payment successful!', response);
        // Handle successful payment
      }}
      onPaymentFailed={(response) => {
        console.log('Payment failed', response);
        // Handle failed payment
      }}
    />
  );
}

QQ 嵌入脚本( 无反应 / npm)

使用嵌入的脚本将 Fundly Pay 集成到 Angular, Vue, plain HTML, Flustter WebView, 或 Android WebView ——不需要反应依赖或构建系统.

从 CDN 装入

<!-- CSS (required) -->
<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@fundly.ai/[email protected]/dist/embed.css" />

<!-- JS (self-contained — React bundled in) -->
<script
  src="https://cdn.jsdelivr.net/npm/@fundly.ai/[email protected]/dist/embed.js"
  integrity="SHA384_HASH_FROM_RELEASE_NOTES"
  crossorigin="anonymous"
></script>

总是使用 已版本的 URL 在生产中。 这个 latest 化名 (@latest自动更新,并可能引入断裂变化.

快速启动( Plain HTML)

<div id="fundly-root"></div>

<script>
  FundlySDK.mount('fundly-root', {
    flow: 'collection',                  // 'collection' | 'repayment' | 'transactions'
    config: {
      environment: 'production',
      partnerCredentials: { username: 'YOUR_USER', password: 'YOUR_PASS' },
      distributorIdnum: 'DIST_001',
      chemistId: 'CHEM_001',
      payableValue: '5000',
      paymentType: 'INVOICE_COLLECT',
      typeOfApp: 'WEB',
      paymentInvoice: [{ invoiceId: 'INV-001', paidAmount: 5000 }],
    },
    onPaymentCollected: function(response) {
      console.log('Payment success', response);
      FundlySDK.unmount('fundly-root');
    },
    onNavigateHome: function() {
      window.location.href = '/dashboard';
    },
  });
</script>

内嵌 API

平台指南

见 互联网档案馆的存檔,存档日期2013-12-02 全面整合的例子包括:

• 角 (标记 +) ngOnInit编号 :ngOnDestroy(中文(简体) )
• Vue 3 (月出/ 月出前)
• Fluster InAppWebView (达特桥处理器)
• Android Web View (科特林语) @JavascriptInterface(中文(简体) )

QQ 配置

认证(X-40)

截止 1.8.0,通过 accessToken ——您的主机应用程序本身的登录用户JWT——而不是 partnerCredentials时 accessToken 设定, SDK 每一次请求都使用它, 永远不会 电话 /auth/login 作为Partner;它只保存在记忆中,从未写给 localStorage。 。 。 . partnerCredentials 仍在工作(@deprecated用于不能提供的主机 一个用户符号。 一个 accessToken 或者说 partnerCredentials 需要时间.

config={{
  accessToken: currentUser.jwt, // your app's own session token
  onTokenExpired: () => {
    // Called once if a Fundly backend rejects the token with 401. There is no refresh
    // endpoint today — send the user back to login.
    redirectToLogin();
  },
  // ...rest of PaymentConfig
}}

支付配置

interface PartnerCredentials {
  username: string;               // Partner username
  password: string;               // Partner password
}

interface PaymentConfig {
  environment?: 'production' | 'preprod' | 'uat'; // Environment to use (default: "production")
  /** @deprecated Use accessToken instead. */
  partnerCredentials?: PartnerCredentials;
  accessToken?: string;            // Host's own access token — preferred. One of accessToken/partnerCredentials required.
  onTokenExpired?: () => void;     // Called at most once on a 401 while using accessToken
  distributorIdnum: string;       // Required: Distributor business ID
  chemistId?: string;             // Optional: Chemist/Retailer business ID (either chemistId or leadId required)
  leadId?: string;                // Optional: Lead ID for lead-based payments (either chemistId or leadId required)
  typeOfApp: 'FUNDLY_CUSTOMER_APP' | 'FUNDLY_COLLECT_APP';
  paymentInvoice: Array<{
    invoiceId: string;
    paidAmount: number;
  }>;
  payableValue: string;           // Total amount as string
  paymentType: 'INVOICE_COLLECT' | 'DIRECT_COLLECT';
  salesmanId?: number;            // Optional: Salesman ID
  payerMobileNumber?: string;     // Optional: Payer mobile number
  redirectionUrl?: string;        // Optional: URL to redirect after UPI payment
  transactionId?: string;         // Optional: Transaction ID to display result
  showResultOnly?: boolean;       // Optional: Skip payment options, show result only
  successButtonText?: string;     // Optional: Button text on success drawer (default: "Home")
  failureButtonText?: string;     // Optional: Button text on failure drawer (default: "Go Back")
}

回电支付

这个 PaymentOptionPage 组件接受处理支付完成的可选回调 :

<PaymentOptionPage
  config={paymentConfig}
  onPaymentCollected={(response) => {
    // Called when payment is successful
    // Navigate to success page, show receipt, etc.
  }}
  onPaymentFailed={(response) => {
    // Called when payment fails
    // Transaction status: FAILED, CANCELLED, or DECLINED
    // Show error message, retry option, etc.
  }}
/>

说明: 对于 迪纳米切尔, (中文(简体) ), 缴款 链接,以及 乌皮 支付模式, SDK 自动计算交易状态直至支付完成或失败.

SDK 回调

使用配置特定平台的行为 sdkConfig.configure()数字 :

import { sdkConfig } from '@fundly.ai/payment-sdk';

sdkConfig.configure({
  // Called when user wants to exit the SDK
  onNavigateHome: () => void;

  // Called when user wants to share text (payment link)
  onShareText: (text: string) => void;

  // Called when user wants to share image (receipt)
  onShareImage: (base64Data: string, fileName: string, fileType: string) => void;

  // Called when user wants to share image with byte data (Android WebView)
  onShareByteImage: (byteUrl: string, receiptText: string) => void;

  // Called when user wants to capture photo (cheque/cash proof)
  onOpenCamera: () => Promise<ImageFile | null>;

  // Called when user wants to select image from gallery
  onOpenGallery: () => Promise<ImageFile | null>;
});

图像文件接口 :

interface ImageFile {
  name: string;    // File name
  type: string;    // MIME type (e.g., 'image/jpeg')
  data: string;    // Base64 encoded image data
}

环境配置

SDK支持三种环境: 生产, (中文(简体) ), 预程序 (生产前),和 宽度 (用户验收测试).

环境选项

使用 environment 参数在 PaymentConfig数字 :

生产环境(违约)

默认或何时 environment: "production",SDK使用生产URL:

<PaymentOptionPage
  config={{
    environment: "production", // or omit this parameter for production
    partnerCredentials: {
      username: "YOUR_USERNAME",
      password: "YOUR_PASSWORD"
    },
    distributorIdnum: "YOUR_DISTRIBUTOR_ID",
    chemistId: "YOUR_CHEMIST_ID",
    // ... other config
  }}
/>

生产前环境

用于中转和生产前测试:

<PaymentOptionPage
  config={{
    environment: "preprod", // Pre-production environment
    partnerCredentials: {
      username: "YOUR_USERNAME",
      password: "YOUR_PASSWORD"
    },
    distributorIdnum: "YOUR_DISTRIBUTOR_ID",
    chemistId: "YOUR_CHEMIST_ID",
    // ... other config
  }}
/>

UAT 环境

用户接受测试 :

<PaymentOptionPage
  config={{
    environment: "uat", // UAT environment
    partnerCredentials: {
      username: "YOUR_USERNAME",
      password: "YOUR_PASSWORD"
    },
    distributorIdnum: "YOUR_DISTRIBUTOR_ID",
    chemistId: "YOUR_CHEMIST_ID",
    // ... other config
  }}
/>

示例:基于环境的配置

// Automatically switch based on your app's environment
const getEnvironment = () => {
  switch (process.env.NODE_ENV) {
    case 'production':
      return 'production';
    case 'staging':
      return 'preprod';
    case 'test':
      return 'uat';
    default:
      return 'preprod';
  }
};

<PaymentOptionPage
  config={{
    environment: getEnvironment(),
    partnerCredentials: {
      username: process.env.PARTNER_USERNAME,
      password: process.env.PARTNER_PASSWORD
    },
    // ... other config
  }}
/>

环境 URL

每个环境都使用内部配置的不同API端点. SDK基于 environment 您提供的参数 .

重要注释 :

• 总是使用 宽度 或者说 预程序 开发和测试过程中的环境
• 切换到 生产 生产部署的环境(默认)
• 环境会影响整个SDK的所有API呼叫
• 为每一种环境使用适当的证书
• 基金支持特定环境证书和配置

++ 支持的支付模式

SDK 根据您的配置自动显示可用的支付选项 :

1. 基金支付 - 用信贷额度一击支付
2. 生成 QR - 动态 UPI QR 代码生成,用于即时支付
3. 支付链接 - 创建并共享支付链接
4. 乌皮 - 通过支付网关直接支付UPI(支持所有UPI应用程序)
5. 扫描 QR - 扫描分销商的静态QR代码
6. 现金 - 经检察官办公室核查的现金支付
7. 支票 - 有图像上传和验证的支票付款

UPI 支付流程

UPI支付模式提供了一个无缝支付体验:

1. 用户选择 UPI 选项 - SDK 显示 UPI 支付选择
2. 重定向到支付网关 - 用户被重定向到安全支付页面
3. 全额付款 - 用户使用任何UPI应用程序(Google Pay、PhonePe、Paytm等)完成付款
4. 自动返回 - 付款后,用户自动重定向回您的应用程序
5. 状态投票 - SDK自动进行支付状况调查并显示结果

关键特性 :

• 自动交易状态跟踪
• 支持所有主要 UPI 应用程序
• 支付UPI的零额外费用
• 安全支付网关集成

只显示付款结果

有时您可能想要仅显示支付结果(成功/失败)而不显示支付选项。 这在下列情况下是有用的:

• 用户从付款网关返回方向
• 您想要显示交易当前状态
• 你分别处理付款启动

使用例 : 用户启动 UPI 支付 /scan-qr 页面中,将重定向到付款网关,完成付款,然后返回 /scan-qr?orderId=PTXN123您的应用程序检测到命令并打开 SDK 只显示结果 .

// Detect payment return in your app
useEffect(() => {
  const urlParams = new URLSearchParams(window.location.search);
  const orderIdFromUrl = urlParams.get("orderId") || urlParams.get("transactionId");

  if (orderIdFromUrl) {
    // User returned from payment gateway - show SDK with result only
    setShowPaymentSDK(true);
    setTransactionId(orderIdFromUrl);
  }
}, []);

// Render SDK in result-only mode
{showPaymentSDK && (
  <PaymentOptionPage
    config={{
      // ... your config
      transactionId: transactionId,        // Transaction ID to fetch
      showResultOnly: true,                // Skip payment options UI
      redirectionUrl: window.location.href // For consistency
    }}
    onPaymentCollected={(response) => {
      console.log('Payment successful!', response);
      // Handle success, navigate, etc.
    }}
    onPaymentFailed={(response) => {
      console.log('Payment failed', response);
      // Handle failure
    }}
  />
)}

如何运作:

1. SDK 使用提供的交易状态 transactionId
2. 如果状态是 SUCCESS编号 :COMPLETED - 显示成功抽屉和电话 onPaymentCollected
3. 如果状态是 FAILED编号 :CANCELLED编号 :DECLINED 显示失败抽屉和电话 onPaymentFailed
4. 如果状态还在 PENDING编号 :PROCESSING ~ 向 UPI 抽屉显示投票结果直至完成

QQ 客户类型:化学与铅

SDK支持两种类型的客户来收取付款:

基于化学剂的付款(现有客户)

注册化学家/有固定账户的零售商:

<PaymentOptionPage
  config={{
    partnerCredentials: { username: "...", password: "..." },
    distributorIdnum: "DIST123",
    chemistId: "CHEM456", // Use chemistId for registered customers
    typeOfApp: "FUNDLY_CUSTOMER_APP",
    // ... other config
  }}
/>

铅基付款(新客户/预期客户)

对于还没有化学账户的线索或新客户:

<PaymentOptionPage
  config={{
    partnerCredentials: { username: "...", password: "..." },
    distributorIdnum: "DIST123",
    leadId: "LEAD789", // Use leadId for leads/new customers
    typeOfApp: "FUNDLY_CUSTOMER_APP",
    // ... other config
  }}
/>

重要注释 :

• 您必须提供 无论是 chemistId 或者说 leadId (不是两者)
• 如果两者都提供, chemistId 优先排序
• 基于铅的付款支持与基于化学的付款相同的支付方式
• 利用适当的客户识别资料跟踪分析事件

QQ 用户界面自定义

自定义按钮文本

您可以自定义在成功和失败抽屉上显示的按钮文本, 以更好地匹配您的应用程序的导航行为 :

<PaymentOptionPage
  config={{
    // ... your config
    successButtonText: "Close",    // Custom text for success drawer button
    failureButtonText: "Close",    // Custom text for failure drawer button
  }}
/>

常用案例 :

1. 有标签关闭的网络应用程序

当您的应用程序在新标签中打开 SDK时, 付款后应该关闭 :

config={{
  successButtonText: "Close",
  failureButtonText: "Close",
}}

sdkConfig.configure({
  onNavigateHome: () => {
    window.close(); // Close the tab/window
  }
});

2. 单页申请(SPA)

当返回到您的应用程序中的特定页面时 :

config={{
  successButtonText: "Back to Dashboard",
  failureButtonText: "Retry Payment",
}}

sdkConfig.configure({
  onNavigateHome: () => {
    navigate('/dashboard'); // Use your router
  }
});

3. 默认行为

如果不指定自定义文本,则使用默认值:

• 成功抽屉 : "家园"
• 失败抽屉 : 滚回去

{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}史蒂林 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得呢

在您的应用程序中导入 CSS 文件 :

import '@fundly.ai/payment-sdk/css';

SDK在内部使用Tailwind CSS,并提供干净,可移动的第一个UI.

QQ 认证和安全

合伙人证书

SDK需要合作伙伴证书才能认证. 重要的安全考虑:

import { PaymentOptionPage } from '@fundly.ai/payment-sdk';

<PaymentOptionPage
  config={{
    partnerCredentials: {
      username: process.env.PARTNER_USERNAME, // Use environment variables
      password: process.env.PARTNER_PASSWORD  // NEVER hardcode credentials
    },
    // ... other config
  }}
/>

安保最佳做法:

• 从不将证书承诺给版本控制
• 将证书存储在环境变量或安全金库中
• 对沙盒和生产环境使用不同的证书
• 定期轮换全权证书
• 在应用程序中执行适当的访问控制

访问托肯( 可选)

您也可以为额外的认证设置 JWT 令牌 :

import { setAccessToken } from '@fundly.ai/payment-sdk';

// Set token before rendering PaymentOptionPage
setAccessToken('your-jwt-token');

分析跟踪

SDK使用CleverTap分析自动跟踪支付事件. 不需要手动配置 - 分析在制作时自动初始化 PaymentOptionPage 组件.

自动分析初始化

当 SDK 挂载时, 它会自动初始化分析 , 基于相应的环境设置 environment 参数 PaymentConfig。 。 。 .

有轨事件(v2)

SDK追踪到支付寿命周期中的两起事件:

1. 联合国. Payment_SDK_Launched

支付选项屏幕满载时开火 .

主要领域包括:

• invoice_count, (中文(简体) ), payment_amount, (中文(简体) ), payment_type, (中文(简体) ), partial_payment
• supplier_id, (中文(简体) ), supplier_name, (中文(简体) ), user_type, (中文(简体) ), user_uuid
• session_id, (中文(简体) ), platform, (中文(简体) ), sdk_version, (中文(简体) ), sdk_entry_point
• is_payment_enabled, (中文(简体) ), status
• 所有9个 payment_option_* 可用布尔数
• scan_channel, (中文(简体) ), scan_origin, (中文(简体) ), salesman_name
• 从上游结转的田地: view_id, (中文(简体) ), scan_id, (中文(简体) ), bill_id, (中文(简体) ), bill_type, (中文(简体) ), bill_status, (中文(简体) ), bill_total_amount, (中文(简体) ), outstanding_amount, (中文(简体) ), notification_id, (中文(简体) ), notification_channel (非QR/非通知流量的数值)

2. 联合国. Payment_Initiated

用户选择付款方式和收益时开火.

主要领域包括:

• fundly_transaction_id, (中文(简体) ), invoice_count, (中文(简体) ), partial_payment
• payment_amount, (中文(简体) ), payment_type, (中文(简体) ), payment_method, (中文(简体) ), payment_mode
• payment_channel, (中文(简体) ), payment_gateway, (中文(简体) ), otp_required, (中文(简体) ), retry_count
• supplier_id, (中文(简体) ), supplier_name, (中文(简体) ), user_type, (中文(简体) ), user_uuid
• session_id, (中文(简体) ), platform, (中文(简体) ), mobile_changed
• 基金 酌情支付贷款领域

说明: Payment_Transaction 实值 没有 被SDK开除了 属于后端所有.

分析失败

所有分析电话都是用试接接接接的 追踪失败永远不会阻断或中断付款流量.

API 参考

构成部分

PaymentOptionPage

主要支付 UI 组件, 包含所有支付选项 .

道具 :

• config: PaymentConfig - 付款配置对象

公用事业

sdkConfig.configure(callbacks: SDKCallbacks)

为 SDK 行为配置特定平台的回调.

setAccessToken(token: string)

设置 API 呼叫的认证符 .

getAccessToken(): string | null

获取当前认证符 .

发展

建造SDK

npm run build          # Build React npm package + embed script
npm run build:embed    # Build embed script only (faster)

测试

npm run test:embed     # Run Playwright integration tests for embed.js

要求数 npm run build 首先生产 dist/embed.js。 。 。 .

SRI Hash(用于发行笔记)

npm run sri            # Compute SHA-384 hash + print CDN URLs

本地测试

# Link locally
npm link

# In your test project
npm link @fundly.ai/payment-sdk

取消链接

npm unlink @fundly.ai/payment-sdk

QQ 类型脚本支持

SDK被用TypeScript来写,并提供了完整的类型定义. 导入类型 :

import type {
  PaymentConfig,
  PartnerCredentials,
  PaymentInvoice,
  SDKCallbacks,
  ImageFile,
  Environment
} from '@fundly.ai/payment-sdk';

* 解决问题

未显示支付选项

• 验证认证符已设定
• 检查 typeOfApp 匹配您的使用大小写
• 保证 paymentInvoice 数组格式化

相机/电池不工作

• 执行 onOpenCamera 财务报告和审定财务报表 onOpenGallery 调用
• 返回正确格式的图像数据( Base64 字符串)

SDK 未关闭

• 执行 onNavigateHome 回调
• 在应用程序的路由系统中处理导航

许可证

MIT 许可证 基金开发商

++ 辅助

关于议题和问题清单:

• 电子邮件 : 支助@fundly.ai