Payments API

Create payment links, retrieve payment details, and cancel active payments.

Endpoint	Description
POST`/v1/payments`	Create a payment link
GET`/v1/payments/:id`	Retrieve payment details
DELETE`/v1/payments/:id`	Cancel an active payment

For marketplace payment splitting, see Split Payments.

Create Payment#

POST/v1/payments

Create a payment link for your customer. The response includes a paymentUrl — share it with your customer to complete the payment.

cURL

curl -X POST https://api.pymstr.com/v1/payments \
  -H "Authorization: Bearer pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "currency": "USD",
    "title": "Premium Plan",
    "externalId": "sub-456",
    "acceptedChains": [
      42161,
      8453
    ],
    "acceptedTokens": [
      "USDC"
    ],
    "expiresAt": "2026-03-01T00:00:00Z",
    "merchantAmount": "30.00"
  }'

Request Body

Parameter	Type	Required	Description
`amount`	string	Required	Fiat amount as a string with 0–2 decimal places (e.g., "100", "100.5", "100.00"). Per-currency minimum (see Currencies & Chains), max 1,000,000,000,000. Zero-decimal currencies (JPY, IDR, VND) reject fractional amounts.
`currency`	string	Required	Fiat currency code. `AEDARSBRLEURGBPIDRILSJPYMXNNGNPHPTHBUSDVND`
`title`	string	Optional	Payment title (max 255 chars).
`externalId`	string	Optional	Your reference ID (max 36 chars, alphanumeric/hyphens/underscores/dots). Must be unique per merchant while a payment is ACTIVE, PROCESSING, or SUCCESSFUL. Reusable after FAILED, EXPIRED, or CANCELLED.
`acceptedChains`	number[]	Optional	Allowed chain IDs (default: all supported). `1 (Ethereum)42161 (Arbitrum One)8453 (Base)137 (Polygon)56 (BNB Smart Chain)`
`acceptedTokens`	string[]	Optional	Allowed token symbols (default: all). `USDCUSDT`
`expiresAt`	datetime	Optional	Expiration time (15 min to 30 days from now, default: 1 hour).
`sellers`	array	Optional	Split payment recipients (marketplace). Max 5 sellers.
`merchantAmount`	string	Optional	Your cut before Pymstr's fee (0–2 decimal places). merchantAmount + sum(sellers) = amount. If omitted, you get the remainder after sellers.

amount

stringRequired

Fiat amount as a string with 0–2 decimal places (e.g., "100", "100.5", "100.00"). Per-currency minimum (see Currencies & Chains), max 1,000,000,000,000. Zero-decimal currencies (JPY, IDR, VND) reject fractional amounts.

currency

stringRequired

Fiat currency code.

AEDARSBRLEURGBPIDRILSJPYMXNNGNPHPTHBUSDVND

title

stringOptional

Payment title (max 255 chars).

externalId

stringOptional

Your reference ID (max 36 chars, alphanumeric/hyphens/underscores/dots). Must be unique per merchant while a payment is ACTIVE, PROCESSING, or SUCCESSFUL. Reusable after FAILED, EXPIRED, or CANCELLED.

acceptedChains

number[]Optional

Allowed chain IDs (default: all supported).

1 (Ethereum)42161 (Arbitrum One)8453 (Base)137 (Polygon)56 (BNB Smart Chain)

acceptedTokens

string[]Optional

Allowed token symbols (default: all).

USDCUSDT

expiresAt

datetimeOptional

Expiration time (15 min to 30 days from now, default: 1 hour).

sellers

arrayOptional

Split payment recipients (marketplace). Max 5 sellers.

merchantAmount

stringOptional

Your cut before Pymstr's fee (0–2 decimal places). merchantAmount + sum(sellers) = amount. If omitted, you get the remainder after sellers.

Response `201 Created`

JSON

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "ACTIVE",
  "amount": "250.00",
  "currency": "USD",
  "title": "Premium Plan",
  "externalId": "sub-456",
  "acceptedChains": [
    42161,
    8453
  ],
  "acceptedTokens": [
    "USDC"
  ],
  "pymstrFee": "2.50",
  "merchantFee": "247.50",
  "sellers": null,
  "paymentUrl": "https://pay.pymstr.com/p/01234567-89ab-cdef-0123-456789abcdef",
  "expiresAt": "2026-03-01T00:00:00.000Z",
  "createdAt": "2026-02-24T10:00:00.000Z"
}

Response Fields

Parameter	Type	Required	Description
`id`	string	Required	Payment UUID
`status`	string	Required	Always "ACTIVE" for new payments
`amount`	string	Required	Original fiat amount
`currency`	string	Required	Original fiat currency
`title`	string?	Optional	Payment title
`externalId`	string?	Optional	Your reference ID
`acceptedChains`	number[]	Required	Allowed chain IDs
`acceptedTokens`	string[]	Required	Allowed token symbols
`pymstrFee`	string	Required	Pymstr's 1% fee in fiat
`merchantFee`	string	Required	Merchant's net amount in fiat
`sellers`	array?	Optional	Seller splits (null if no splits)
`paymentUrl`	string	Required	Share this URL with your customer
`expiresAt`	datetime	Required	Expiration time
`createdAt`	datetime	Required	When payment was created

id

stringRequired

Payment UUID

status

stringRequired

Always "ACTIVE" for new payments

amount

stringRequired

Original fiat amount

currency

stringRequired

Original fiat currency

title

string?Optional

Payment title

externalId

string?Optional

Your reference ID

acceptedChains

number[]Required

Allowed chain IDs

acceptedTokens

string[]Required

Allowed token symbols

pymstrFee

stringRequired

Pymstr's 1% fee in fiat

merchantFee

stringRequired

Merchant's net amount in fiat

sellers

array?Optional

Seller splits (null if no splits)

paymentUrl

stringRequired

Share this URL with your customer

expiresAt

datetimeRequired

Expiration time

createdAt

datetimeRequired

When payment was created

Error Responses

400Validation failed

401Unauthorized

409Conflict — externalId in use by an ACTIVE/PROCESSING/SUCCESSFUL payment, or API key limit reached

429Rate limit exceeded

Get Payment#

GET/v1/payments/:id

Retrieve payment details. Returns full information when authenticated as the merchant, including on-chain transaction data for completed payments.

cURL

curl -X GET https://api.pymstr.com/v1/payments/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer pk_your_api_key"

Path Parameters

Parameter	Type	Required	Description
`id`	string	Required	Payment UUID

id

stringRequired

Payment UUID

Response `200 OK`

JSON

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "SUCCESSFUL",
  "amount": "250.00",
  "currency": "USD",
  "title": "Premium Plan",
  "externalId": "sub-456",
  "acceptedChains": [
    42161,
    8453
  ],
  "acceptedTokens": [
    "USDC"
  ],
  "pymstrFee": "2.50",
  "merchantFee": "247.50",
  "sellers": null,
  "paymentUrl": "https://pay.pymstr.com/p/01234567-89ab-cdef-0123-456789abcdef",
  "chainId": 42161,
  "token": "USDC",
  "exchangeRate": "1.001500",
  "amountToken": "250.375000",
  "pymstrFeeToken": "2.503750",
  "merchantFeeToken": "247.871250",
  "gasActual": "0.001200",
  "txHash": "0x...",
  "error": null,
  "expiresAt": "2026-03-01T00:00:00.000Z",
  "paidAt": "2026-02-24T10:05:00.000Z",
  "createdAt": "2026-02-24T10:00:00.000Z",
  "updatedAt": "2026-02-24T10:05:00.000Z"
}

Response Fields

Parameter	Type	Required	Description
`id`	string	Required	Payment UUID
`status`	string	Required	Current state: ACTIVE, PROCESSING, SUCCESSFUL, FAILED, EXPIRED, CANCELLED
`amount`	string	Required	Original fiat amount
`currency`	string	Required	Original fiat currency
`title`	string?	Optional	Payment title
`externalId`	string?	Optional	Your reference ID
`acceptedChains`	number[]	Required	Allowed chain IDs
`acceptedTokens`	string[]	Required	Allowed token symbols
`pymstrFee`	string	Required	Pymstr's fee in fiat
`merchantFee`	string	Required	Your fee in fiat
`sellers`	array?	Optional	Seller splits
`paymentUrl`	string	Required	Shareable payment link
`chainId`	number?	Optional	Blockchain used (set at initiation)
`token`	string?	Optional	Token used (set at initiation)
`exchangeRate`	string?	Optional	Locked fiat-to-token rate
`amountToken`	string?	Optional	Total amount in token units
`pymstrFeeToken`	string?	Optional	Pymstr fee in token units
`merchantFeeToken`	string?	Optional	Merchant fee in token units
`gasActual`	string?	Optional	Actual gas fee paid in the selected token (set after on-chain confirmation)
`txHash`	string?	Optional	On-chain transaction hash
`error`	object?	Optional	Failure details { code, source, message } when status is FAILED; otherwise null
`expiresAt`	datetime	Required	Expiration time
`paidAt`	datetime?	Optional	When payment completed
`createdAt`	datetime	Required	When payment was created
`updatedAt`	datetime	Required	Last update time

id

stringRequired

Payment UUID

status

stringRequired

Current state: ACTIVE, PROCESSING, SUCCESSFUL, FAILED, EXPIRED, CANCELLED

amount

stringRequired

Original fiat amount

currency

stringRequired

Original fiat currency

title

string?Optional

Payment title

externalId

string?Optional

Your reference ID

acceptedChains

number[]Required

Allowed chain IDs

acceptedTokens

string[]Required

Allowed token symbols

pymstrFee

stringRequired

Pymstr's fee in fiat

merchantFee

stringRequired

Your fee in fiat

sellers

array?Optional

Seller splits

paymentUrl

stringRequired

Shareable payment link

chainId

number?Optional

Blockchain used (set at initiation)

token

string?Optional

Token used (set at initiation)

exchangeRate

string?Optional

Locked fiat-to-token rate

amountToken

string?Optional

Total amount in token units

pymstrFeeToken

string?Optional

Pymstr fee in token units

merchantFeeToken

string?Optional

Merchant fee in token units

gasActual

string?Optional

Actual gas fee paid in the selected token (set after on-chain confirmation)

txHash

string?Optional

On-chain transaction hash

error

object?Optional

Failure details { code, source, message } when status is FAILED; otherwise null

expiresAt

datetimeRequired

Expiration time

paidAt

datetime?Optional

When payment completed

createdAt

datetimeRequired

When payment was created

updatedAt

datetimeRequired

Last update time

Error Responses

401Unauthorized

404Not found

429Rate limit exceeded

Cancel Payment#

DELETE/v1/payments/:id

Cancel an active payment. Only payments with status ACTIVE can be cancelled.

cURL

curl -X DELETE https://api.pymstr.com/v1/payments/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer pk_your_api_key"

Path Parameters

Parameter	Type	Required	Description
`id`	string	Required	Payment UUID

id

stringRequired

Payment UUID

Error Responses

400Payment is not in ACTIVE status

401Unauthorized

404Not found

429Rate limit exceeded

Payments API

Create Payment#

Request Body

Response 201 Created

Response Fields

Error Responses

Get Payment#

Path Parameters

Response 200 OK

Response Fields

Error Responses

Cancel Payment#

Path Parameters

Error Responses

Response `201 Created`

Response `200 OK`