REST + JSON over HTTPS. Bearer-token authentication. One POST creates a payment link valid across USDC and USDT on Ethereum, Base, Polygon, Arbitrum, and BNB Chain.
POST /v1/payments returns a paymentUrl. You can share it directly (payment-link pattern) or redirect / iframe it into your checkout (hosted-checkout pattern). The customer-facing flow is identical either way: only your distribution changes. There's no separate /checkout or /payment-links endpoint to wire up.
Integration is a single POST. GET and DELETE are auxiliary, used to retrieve current payment state or cancel an open one.
Create a payment. Returns a paymentUrl your customer can pay at, valid across the chains and tokens you accept.
Retrieve a payment. Returns current state plus on-chain data once paid.
Cancel an ACTIVE payment. The customer-facing paymentUrl stops accepting transactions.
Beyond the payment lifecycle, the same Bearer key drives webhook configuration, API-key management, analytics, and the transaction ledger.
acceptedChains and acceptedTokens enforce exactly which networks and stablecoins the customer can pay with, so wrong-chain payments are impossible by construction. sellers[] splits the payment across up to 5 wallets in the same on-chain transaction, with the 1% fee deducted proportionally from every recipient. The basic create is on the quickstart; this is the version marketplaces ship.
// Enforced payment with a marketplace split: the customer
// can ONLY pay USDC on Arbitrum or Base, and one on-chain
// transaction pays all three wallets atomically.
const res = await fetch('https://api.pymstr.com/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.PYMSTR_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '250.00',
currency: 'USD',
title: 'Premium Plan',
externalId: 'sub-456', // your reference. Unique while active
acceptedChains: [42161, 8453], // Arbitrum + Base only
acceptedTokens: ['USDC'],
merchantAmount: '180.00',
sellers: [
{ address: '0x1234...abcd', amount: '60.00' },
{ address: '0x5678...efgh', amount: '10.00' },
],
}),
});
const payment = await res.json();
// payment.paymentUrl -> share it, redirect to it, or iframe it{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "ACTIVE",
"paymentUrl": "https://pay.pymstr.com/p/01234567-...",
"pymstrFee": "2.50",
"merchantFee": "178.20",
"sellers": [
{ "address": "0x1234...abcd", "amount": "59.40" },
{ "address": "0x5678...efgh", "amount": "9.90" }
],
"expiresAt": "2026-03-01T00:00:00.000Z",
"createdAt": "2026-02-24T10:00:00.000Z"
}Native USDC lives on four of the five supported networks: Ethereum (1), Arbitrum One (42161), Base (8453) and Polygon (137). BNB Smart Chain (56) carries USDT only. To accept USDC everywhere it exists, list those four chain IDs in acceptedChains and USDC in acceptedTokens. The hosted checkout only offers those combinations, so a wrong-network payment cannot happen, and the customer pays the gas, so the network they choose only changes their cost (per-network gas and speed are in Chains + tokens below).
After the payment confirms, GET /v1/payments/{id} carries the singular chainId and token the customer actually used, plus txHash and amountToken. Reconcile per network on chainId; the plural acceptedChains stays exactly what you sent.
// Accept USDC on every network that carries it natively:
// Ethereum (1), Arbitrum One (42161), Base (8453), Polygon (137).
// BNB Smart Chain (56) is USDT-only, so it is left out.
const res = await fetch('https://api.pymstr.com/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.PYMSTR_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '99.00',
currency: 'USD',
title: 'Order 8841',
externalId: 'order-8841',
acceptedChains: [1, 42161, 8453, 137],
acceptedTokens: ['USDC'],
}),
});
const payment = await res.json();
// payment.paymentUrl -> the customer picks the network at checkout{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "SUCCESSFUL",
"amount": "99.00",
"currency": "USD",
"title": "Order 8841",
"externalId": "order-8841",
"acceptedChains": [1, 42161, 8453, 137],
"acceptedTokens": ["USDC"],
"chainId": 137,
"token": "USDC",
"exchangeRate": "1.001500",
"amountToken": "99.148500",
"pymstrFee": "0.99",
"merchantFee": "98.01",
"txHash": "0x...",
"paymentUrl": "https://pay.pymstr.com/p/01234567-...",
"paidAt": "2026-08-30T10:05:00.000Z",
"createdAt": "2026-08-30T10:00:00.000Z"
}Every API call carries an Authorization header with your secret API key. Keys are created in the PYMSTR dashboard and prefixed with pk_.
Use pk_ keys server-side only. Never ship a key in a browser bundle. See docs.pymstr.com for full authentication details, including session-token usage and security features.
Authorization: Bearer pk_live_abc123...xyz
# Test the connection:
curl https://api.pymstr.com/v1/payments \
-H "Authorization: Bearer pk_live_..." \
-X GETPass your own reference (an order ID, a subscription ID) as externalId. It must be unique per merchant while a payment is active or successful, so a retried create call can never mint a second live payment: the API answers 409 Conflict instead. Once a payment fails, expires, or is cancelled, the externalId becomes reusable.
List endpoints paginate with a cursor: pass the last item's id as cursor and read nextCursor + hasMore from the response (limit defaults to 20, max 100). Validation failures return a structured errors array, so a 400 tells you exactly which field to fix.
// Duplicate externalId while a payment is live:
HTTP/1.1 409 Conflict
{
"statusCode": 409,
"message": "externalId already in use",
"error": "Conflict"
}
// Validation failure shape:
HTTP/1.1 400 Bad Request
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request",
"errors": [
{ "path": ["amount"], "message": "Invalid amount format" }
]
}Every response includes rate-limit headers. When you exceed the limit, the API returns 429 Too Many Requests.
X-RateLimit-LimitMaximum requests allowed in the windowX-RateLimit-RemainingRequests remaining in the current windowX-RateLimit-ResetUnix timestamp when the window resetsCurrent limits per endpoint are documented at docs.pymstr.com.
id=1USDC, USDTid=42161USDC, USDTid=8453USDCid=137USDC, USDTid=56USDT14 fiat currencies for the amount field: USD · EUR · GBP · AED · ARS · BRL · IDR · ILS · JPY · MXN · NGN · PHP · THB · VND.