js-stronghold-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stronghold Pay JS SDK & REST API

Stronghold Pay JS SDK 与 REST API

Stronghold Pay is a payment infrastructure platform enabling online and in-store payment acceptance via ACH/bank debit. Two integration paths exist:

Stronghold.Pay.JS SDK — Frontend drop-in UI components for payment source linking, charges, and tips
REST API v2 — Server-side API for full control over customers, charges, payment sources, and PayLinks

Stronghold Pay是一个支付基础设施平台，支持通过ACH/银行借记方式接收线上和线下支付。提供两种集成方式：

Stronghold.Pay.JS SDK — 用于支付源关联、收费和小费功能的前端嵌入式UI组件
REST API v2 — 服务器端API，可全面控制客户、收费、支付源和PayLink

Integration Architecture

集成架构

┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Frontend   │────▶│  Your Backend    │────▶│  Stronghold API  │
│  (Pay.JS)   │     │  (Secret Key)    │     │  api.stronghold  │
│             │     │                  │     │  pay.com         │
│ publishable │     │ SH-SECRET-KEY    │     │                  │
│ key only    │     │ header           │     │                  │
└─────────────┘     └──────────────────┘     └──────────────────┘

Frontend uses the publishable key (
```
pk_sandbox_...
```
/
```
pk_live_...
```
) and customer tokens
Backend uses the secret key (
```
sk_sandbox_...
```
/
```
sk_live_...
```
) via
```
SH-SECRET-KEY
```
header
Customer tokens are generated server-side, passed to frontend, and expire after 12 hours

┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Frontend   │────▶│  Your Backend    │────▶│  Stronghold API  │
│  (Pay.JS)   │     │  (Secret Key)    │     │  api.stronghold  │
│             │     │                  │     │  pay.com         │
│ publishable │     │ SH-SECRET-KEY    │     │                  │
│ key only    │     │ header           │     │                  │
└─────────────┘     └──────────────────┘     └──────────────────┘

前端使用可发布密钥（
```
pk_sandbox_...
```
/
```
pk_live_...
```
）和客户令牌
后端通过
```
SH-SECRET-KEY
```
请求头使用保密密钥（
```
sk_sandbox_...
```
/
```
sk_live_...
```
）
客户令牌由服务器端生成，传递给前端，有效期为12小时

Quick Start

快速开始

1. Include the SDK

1. 引入SDK

html

<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
  <script src="https://api.strongholdpay.com/v2/js"></script>
</head>

html

<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
  <script src="https://api.strongholdpay.com/v2/js"></script>
</head>

2. Initialize the client

2. 初始化客户端

const strongholdPay = Stronghold.Pay({
  publishableKey: "pk_sandbox_...",
  environment: "sandbox", // 'sandbox' or 'live'
  integrationId: "integration_...",
});

const strongholdPay = Stronghold.Pay({
  publishableKey: "pk_sandbox_...",
  environment: "sandbox", // 'sandbox' 或 'live'
  integrationId: "integration_...",
});

3. Generate a customer token (server-side)

3. 生成客户令牌（服务器端）

bash

curl --request GET \
  --url https://api.strongholdpay.com/v2/customers/{customer_id}/token \
  --header 'SH-SECRET-KEY: sk_sandbox_...' \
  --header 'Accept: application/json'

Response:

json

{
  "response_id": "resp_...",
  "time": "2024-01-15T12:00:00Z",
  "status_code": 200,
  "result": {
    "token": "<jwt>",
    "expiry": "2024-01-16T00:00:00Z"
  }
}

bash

curl --request GET \
  --url https://api.strongholdpay.com/v2/customers/{customer_id}/token \
  --header 'SH-SECRET-KEY: sk_sandbox_...' \
  --header 'Accept: application/json'

响应：

json

{
  "response_id": "resp_...",
  "time": "2024-01-15T12:00:00Z",
  "status_code": 200,
  "result": {
    "token": "<jwt>",
    "expiry": "2024-01-16T00:00:00Z"
  }
}

4. Use SDK methods with the token

4. 使用令牌调用SDK方法

// Link a bank account
strongholdPay.addPaymentSource(customerToken, {
  onSuccess: (paymentSource) => {
    /* save paymentSource.id */
  },
  onExit: () => {
    /* user cancelled */
  },
  onError: (err) => {
    /* handle error */
  },
});

// Create a charge
strongholdPay.charge(customerToken, {
  charge: {
    amount: 4995, // $49.95 in cents
    currency: "usd",
    paymentSourceId: "payment_source_...",
    externalId: "order_123", // optional
  },
  authorizeOnly: false,
  onSuccess: (charge) => {
    /* charge.id */
  },
  onExit: () => {},
  onError: (err) => {},
});

// 关联银行账户
strongholdPay.addPaymentSource(customerToken, {
  onSuccess: (paymentSource) => {
    /* 保存paymentSource.id */
  },
  onExit: () => {
    /* 用户取消操作 */
  },
  onError: (err) => {
    /* 处理错误 */
  },
});

// 创建收费订单
strongholdPay.charge(customerToken, {
  charge: {
    amount: 4995, // 49.95美元，单位为美分
    currency: "usd",
    paymentSourceId: "payment_source_...",
    externalId: "order_123", // 可选
  },
  authorizeOnly: false,
  onSuccess: (charge) => {
    /* charge.id */
  },
  onExit: () => {},
  onError: (err) => {},
});

Environments

环境配置

Environment	Publishable Key	Secret Key	API Base
Sandbox	`pk_sandbox_...`	`sk_sandbox_...`	`https://api.strongholdpay.com`
Live	`pk_live_...`	`sk_live_...`	`https://api.strongholdpay.com`

Keys are found on the Developers page of the Stronghold Dashboard.

环境	可发布密钥	保密密钥	API基础地址
沙箱	`pk_sandbox_...`	`sk_sandbox_...`	`https://api.strongholdpay.com`
生产	`pk_live_...`	`sk_live_...`	`https://api.strongholdpay.com`

密钥可在Stronghold控制台的开发者页面获取。

Sandbox Testing

沙箱测试

Use fake bank accounts in sandbox. Test credentials for aggregators:

Aggregator	Username	Password
Plaid	`user_good`	`pass_good`
Yodlee	`YodTest.site16441.2`	`site16441.2`

Refer to Plaid sandbox docs for additional test credentials and institutions (e.g., First Platypus Bank).

在沙箱环境中可使用模拟银行账户。以下是各聚合器的测试凭据：

聚合器	用户名	密码
Plaid	`user_good`	`pass_good`
Yodlee	`YodTest.site16441.2`	`site16441.2`

更多测试凭据和机构信息（例如，First Platypus Bank）可参考Plaid沙箱文档。

Fraud Prevention

欺诈防控

Include the Stronghold.Pay.JS script on every page of the site (not just checkout) to enable real-time transaction intelligence for fraud detection and chargeback prevention.

为了实现实时交易智能以检测欺诈和防止拒付，请在网站的每一个页面上都引入Stronghold.Pay.JS脚本（而不仅仅是结账页面）。

Core Concepts

核心概念

Customer — End user making payments. Created via API, identified by
```
customer_id
```
Customer Token — JWT (12-hour TTL) authorizing frontend SDK calls for a specific customer
Payment Source — A linked bank account. Created via
```
addPaymentSource
```
or
```
bank_link
```
PayLink
Charge — A payment from customer to merchant. Amounts in cents (e.g.,
```
4995
```
= $49.95)
Tip — An additional payment associated with a charge
PayLink — A hosted URL for payment flows without frontend SDK integration
authorizeOnly — When
```
true
```
, charges/tips reach
```
authorized
```
state without immediate capture; use the Capture Charge API to capture later

客户 — 进行支付的终端用户。通过API创建，由
```
customer_id
```
标识
客户令牌 — JWT（有效期12小时），授权前端SDK为特定客户发起调用
支付源 — 关联的银行账户。通过
```
addPaymentSource
```
或
```
bank_link
```
PayLink创建
收费订单 — 客户向商家支付的款项。金额以美分为单位（例如，
```
4995
```
= 49.95美元）
小费 — 与收费订单相关的额外支付
PayLink — 无需集成前端SDK即可实现支付流程的托管URL
authorizeOnly — 设为
```
true
```
时，收费/小费将进入
```
authorized
```
状态但不会立即扣款；需使用Capture Charge API进行后续扣款

Detailed References

详细参考文档

JS SDK methods, callbacks, arguments: See references/sdk-reference.md
REST API v2 endpoints and authentication: See references/rest-api.md
PayLink hosted payment pages: See references/paylink.md
Error types and codes: See references/errors.md

JS SDK方法、回调函数、参数：请查看references/sdk-reference.md
REST API v2端点与认证：请查看references/rest-api.md
PayLink托管支付页面：请查看references/paylink.md
错误类型与代码：请查看references/errors.md

SHx Token (Stellar Blockchain)

SHx Token（Stellar区块链）

SHx is Stronghold's utility token on the Stellar blockchain. It connects to the payment ecosystem as a rewards mechanism — merchants and customers earn SHx through the Stronghold Rewards Program based on transaction volume processed through the payment network. SHx is also used for governance voting and merchant financing liquidity. There are no direct SDK/API methods for SHx interaction; it operates as a background incentive layer on top of the payment infrastructure.

SHx是Stronghold在Stellar区块链上的实用型代币。它作为奖励机制接入支付生态系统——商家和客户可根据通过该支付网络处理的交易交易量，通过Stronghold奖励计划赚取SHx。SHx还可用于治理投票和商家融资流动性。目前没有直接与SHx交互的SDK/API方法，它作为支付基础设施之上的后台激励层运行。