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
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
Quick Start
- Include the SDK
<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>
- Initialize the client
const strongholdPay = Stronghold.Pay({ publishableKey: "pk_sandbox_...", environment: "sandbox", // 'sandbox' or 'live' integrationId: "integration_...", });
- Generate a customer token (server-side)
curl --request GET
--url https://api.strongholdpay.com/v2/customers/{customer_id}/token
--header 'SH-SECRET-KEY: sk_sandbox_...'
--header 'Accept: application/json'
Response:
{ "response_id": "resp_...", "time": "2024-01-15T12:00:00Z", "status_code": 200, "result": { "token": "<jwt>", "expiry": "2024-01-16T00:00:00Z" } }
- Use SDK methods with the token
// 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) => {}, });
Environments
Environment Publishable Key Secret Key API Base
Sandbox pk_sandbox_...
sk_sandbox_...
Live pk_live_...
sk_live_...
Keys are found on the Developers page of the Stronghold Dashboard.
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).
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.
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
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
SHx Token (Stellar Blockchain)
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.
Key Links
-
Stronghold Developer Docs
-
SDK Tutorials
-
PayLink Tutorials
-
Use Case Demo
-
API Reference v2
-
Stronghold Dashboard