PYMSTR
Home/Developers/API Reference
DevelopersAPI Reference

Stablecoin Payment API. One endpoint. Five chains.

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.

//The modelone create, two patterns01/06

One create endpoint. Two integration patterns.

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.

//Endpointsone to create · two auxiliary02/06

Integration is a single POST. GET and DELETE are auxiliary — use them to retrieve current payment state or cancel an open one.

POST

/v1/payments

Create a payment. Returns a paymentUrl your customer can pay at, valid across the chains and tokens you accept.

Body
Required: amount (fiat string), currency (one of 14 fiat codes).
Returns
Optional: title, externalId, acceptedChains, acceptedTokens, expiresAt (15 min to 30 days, default 1 hour), sellers (for marketplace splits).
Notes
Returns: id, status=ACTIVE, paymentUrl, pymstrFee (1%), merchantFee, expiresAt, createdAt.
GET

/v1/payments/{id}

Retrieve a payment. Returns current state plus on-chain data once paid.

Body
Returns the merchant view: status, chainId, token, exchangeRate, amountToken, txHash, paidAt.
Returns
Use to poll for completion if you choose not to consume webhooks.
DELETE

/v1/payments/{id}

Cancel an ACTIVE payment. The customer-facing paymentUrl stops accepting transactions.

Body
Only valid when status is ACTIVE.
Returns
Returns the updated payment with status=CANCELLED.
//AuthenticationBearer token · pk_ prefix03/06

One header. Bearer token.

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 headerexample
Authorization: Bearer pk_live_abc123...xyz

# Test the connection:
curl https://api.pymstr.com/v1/payments \
  -H "Authorization: Bearer pk_live_..." \
  -X GET
//Payment states6 possible values04/06

Six states. One forward direction.

ACTIVEPayment created, waiting for the customer
PROCESSINGCustomer selected a chain/token and submitted the transaction
SUCCESSFULOn-chain transaction confirmed
FAILEDTransaction reverted or bundler error
EXPIREDPayment reached its expiresAt without completing
CANCELLEDMerchant cancelled the payment via DELETE /v1/payments/{id}
//Limits + coveragerate · chains · currencies05/06

Rate limits

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 window
  • X-RateLimit-RemainingRequests remaining in the current window
  • X-RateLimit-ResetUnix timestamp when the window resets

Current limits per endpoint are documented at docs.pymstr.com.

Chains + tokens

  • Ethereum id=1USDC, USDT
  • Arbitrum One id=42161USDC, USDT
  • Base id=8453USDC
  • Polygon id=137USDC, USDT
  • BNB Smart Chain id=56USDT

14 fiat currencies for the amount field: USD · EUR · GBP · AED · ARS · BRL · IDR · ILS · JPY · MXN · NGN · PHP · THB · VND.

Continue

Build with the stablecoin rail.