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"
}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.