如何使用 TypeScript 接入 imsafu

imsafu 是一个支付处理服务，允许您创建和查询支付。本文档将引导您完成访问 imsafu 服务。

准备

在开始之前，请确保满足以下先决条件：

1. 在您的计算机上安装了Node.js(> v18)。
2. 安装了软件包管理器（如npm或yarn）。

安装依赖项

访问 imsafu 服务没有任何固定的依赖，在这里我们提供了一些默认的依赖库，您可以替换成任何有类似功能的其他库

运行以下命令来安装依赖：

npm install axios ulid ethers

import 所需模块

在您的TypeScript文件中，从已安装的依赖项中导入所需的模块。将以下导入语句添加到文件顶部：

import axios from "axios";
import { ulid } from "ulid";
import { utils } from "ethers";

创建 imsafu 所需变量

与 imsafu 测试服务器连接可以使用一下变量。如果想要连接正式服务器可以 加入等待列表

const options = {
  "url": "https://devnet.imsafu.com",
  "api": "https://allowpay-api-devnet.fly.dev/v1",
  "apiSecret": "your-api-secret",
  "receiver": "your-wallet-account"
  "merchantBrand": "imsafu demo",
  "merchantRedirectURL": "https://merchant.com/redirect"
};

创建新的支付

首先我们需要生成一个 32 位的 hex 字符串作为新订单的 ID

const newOrderID = utils.hexlify(Buffer.from(ulid().padEnd(32), "utf8"));

要创建新的支付，我们首先需要实现一个createPayment方法。此方法接受支付金额作为参数，并返回一个解析为PaymentResponse对象的 Promise。

async function createPayment(amount: number): Promise<PaymentResponse> {
  const newOrderID = utils.hexlify(Buffer.from(ulid().padEnd(32), "utf8")); // 生成新 OrderID

  const payload = {
    payment: {
      orderID: newOrderID,
      receiver: options.receiver,
      amount: amount.toString(),
    },
    notifyURL: `${options.url}/notify`,
  };

  const res = await axios.post(`${options.api}/depositPay`, payload, {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${options.apiSecret}`,
    },
  });

  return res.data;
}

生成支付链接

首先写一个方法用于生成支付链接

function buildPaymentURL(itemMemo: string, res: PaymentResponse): string {
  const urlSearchParams = new URLSearchParams();
  urlSearchParams.append("payID", res.payment.payID);
  urlSearchParams.append("brand", options.merchantBrand);
  urlSearchParams.append("memo", itemMemo);
  urlSearchParams.append("redirect_url", options.merchantRedirectURL);
  urlSearchParams.append("currency", "USD");
  const url = new URL(`${options.url}/payment_qrcode`);
  url.search = urlSearchParams.toString();
  return url.toString();
}

const amount = 100
const createPaymentResponse = await createPayment(amount)
const paymentURL = buildPaymentURL("test item", createPaymentResponse)

用户支付

将生成的 paymentURL 显示给用户，用户点击后可以在网页打开支付界面。具体支付流程可以参考 使用 imsafu 支付

检索支付信息

在用户支付完成后，imsafu 会向创建订单是传入的notifyURL发送body中包含payID的POST请求，我们需要通过getPayment接口检索支付信息，并确认用户支付是否成功。

要检索支付的信息，我们需要先实现getPayment方法。此方法接受支付ID（payID）作为参数，并返回一个解析为PaymentResponse对象的Promise。

async getPayment(payID: string): Promise<PaymentResponse> {
  const res = await axios.get<PaymentResponse>(
    `${options.api}/depositPays/${payID}`,
  );

  return res.data;
}

// 从 notify 请求中获得 payID

const paymentResponse = await getPayment(payID)

// 进行其他操作

附录: 代码中使用的类型定义

export interface Payment {
  payID: string;
  orderID: string;
  receiver: string;
  amount: string;
  originalAmount: string;
  maxFeeAmount: string;
  deadline: string;
}

export interface Chain {
  id: number;
  symbol: string;
  name: string;
}

export interface Token {
  symbol: string;
  address: string;
}

export interface ReceiveTx {
  chain: Chain;
  txID: string;
  confirmedAt: string;
  amount: string;
  feeAmount: string;
  token: Token;
}

export interface Deposit {
  chainID: number;
  token: string;
}

export interface PaymentResponse {
  status: string;
  payment: Payment;
  owner: string;
  depositAddress: string;
  callID: number;
  receiveTx: ReceiveTx | null;
  deposits: Deposit[] | null;
}

请注意，以上代码示例仅用于演示目的，实际使用时需要根据具体情况进行适当的调整和安全性增强。