← Back

API Reference

Complete reference for the PYMSTR API. All API requests must be authenticated and made over HTTPS.

Base URL: https://api.pymstr.com/v1

Rate Limit: 100 requests per minute

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

🔑 Getting Your API Key:

Log into your PYMSTR dashboard
Navigate to Team → API Keys
Click "Generate New API Key"
Copy and securely store your key

Create Payment Link

Creates a new single-use payment link for accepting cryptocurrency payments.

POST /payment-links

Request Body

Parameter	Type	Required	Description
`price`	number	Yes	Payment price in the specified currency
`currency`	string	Yes	Stablecoin type: USDC, USDT, or EURC
`chain`	string	Yes	Blockchain network: Ethereum, Polygon, Arbitrum, Optimism, or Base
`description`	string	No	Payment description
`metadata`	object	No	Custom key-value pairs for your reference

Example Request

POST /v1/payment-links
Content-Type: application/json
Authorization: Bearer sk_live_abc123...

{
  "price": 99.99,
  "currency": "USDC",
  "chain": "Polygon",
  "description": "Premium Subscription - Annual",
  "metadata": {
    "userId": "user_123",
    "planId": "premium_annual"
  }
}

Example Response

{
  "linkId": "PL_xK9mP2nQ4r",
  "url": "https://pymstr-staging.figma.site/#/pay/PL_xK9mP2nQ4r",
  "status": "active",
  "price": 99.99,
  "currency": "USDC",
  "chain": "Polygon",
  "description": "Premium Subscription - Annual",
  "metadata": {
    "userId": "user_123",
    "planId": "premium_annual"
  },
  "createdAt": "2025-11-03T14:22:00Z",
  "expiresAt": "2025-11-10T14:22:00Z"
}

Get Payment Link

Retrieves details of a specific payment link, including its current status and transaction hash if completed.

GET /payment-links/:linkId

Example Request

GET /v1/payment-links/PL_xK9mP2nQ4r
Authorization: Bearer sk_live_abc123...

Example Response (Active)

{
  "linkId": "PL_xK9mP2nQ4r",
  "url": "https://pymstr-staging.figma.site/#/pay/PL_xK9mP2nQ4r",
  "status": "active",
  "price": 99.99,
  "currency": "USDC",
  "chain": "Polygon",
  "createdAt": "2025-11-03T14:22:00Z",
  "expiresAt": "2025-11-10T14:22:00Z"
}

Example Response (Completed)

{
  "linkId": "PL_xK9mP2nQ4r",
  "url": "https://pymstr-staging.figma.site/#/pay/PL_xK9mP2nQ4r",
  "status": "completed",
  "price": 99.99,
  "currency": "USDC",
  "chain": "Polygon",
  "txHash": "0x1234567890abcdef...",
  "completedAt": "2025-11-03T14:30:15Z",
  "createdAt": "2025-11-03T14:22:00Z"
}

List Payment Links

Returns a list of all payment links for your merchant account.

GET /payment-links

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: active, completed, expired
`source`	string	Filter by source: manual, api
`limit`	number	Number of results (default: 50, max: 100)
`offset`	number	Pagination offset (default: 0)

Example Request

GET /v1/payment-links?status=completed&limit=20
Authorization: Bearer sk_live_abc123...

Webhooks

PYMSTR sends webhook events to notify your application when payment links are completed or expire.

Setting Up Webhooks

Log into your PYMSTR dashboard
Navigate to Team → Webhooks
Add your webhook endpoint URL
Select which events you want to receive

Webhook Events

Event	Description
`payment.completed`	Payment link was successfully paid
`payment.expired`	Payment link expired without payment

Webhook Payload Example

{
  "event": "payment.completed",
  "linkId": "PL_xK9mP2nQ4r",
  "price": 99.99,
  "currency": "USDC",
  "chain": "Polygon",
  "txHash": "0x1234567890abcdef...",
  "metadata": {
    "userId": "user_123",
    "planId": "premium_annual"
  },
  "timestamp": "2025-11-03T14:30:15Z"
}

Error Codes

The PYMSTR API uses standard HTTP status codes to indicate success or failure.

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'currency' field must be one of: USDC, USDT, EURC",
    "param": "currency"
  }
}