Skip to main content
POST
/
v0
/
payment-links
Create a payment link
curl --request POST \
  --url https://api.sumvin.com/v0/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-sumvin-pat: <api-key>' \
  --data '
{
  "accepted_chains": [
    1329
  ],
  "description": "Invoice #1234",
  "expires_at": 1735689600000,
  "max_uses": 1,
  "pint": {
    "expires_at": 1735689600,
    "max_amount": 100000000,
    "max_amount_token": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "nonce": 1,
    "resources": [],
    "scopes": [
      "sr:us:pint:spend:execute?max=100000000&asset=USDC@sei&chain_id=1329"
    ],
    "statement": "Settle my $100 invoice",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}
'
{
  "_links": {
    "pint": {
      "href": "/v0/pint/sr%3Aus%3Apint%3Aabc123"
    },
    "public": {
      "href": "/v0/payment-links/public/q79Rx34K..."
    },
    "self": {
      "href": "/v0/payment-links/q79Rx34K..."
    }
  },
  "payment_link": {
    "accepted_chains": [
      1329
    ],
    "amount": "100.00",
    "created_at": 1704067200000,
    "description": "Invoice #1234",
    "expires_at": 1704153600000,
    "max_uses": 1,
    "pay_to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "pint_uri": "sr:us:pint:abc123",
    "slug": "q79Rx34K...",
    "status": "pending",
    "usage_count": 0
  }
}

Authorizations

​
x-sumvin-pat
string
header
required

Personal access token issued to the Sumvin CLI. Send it in the x-sumvin-pat header to authenticate as the owning user.

Headers

​
x-juno-orgid
string | null

Tenant org ID for multi-tenant auth

​
x-sumvin-token
string | null
​
x-sumvin-pat
string | null
​
x-juno-jwt
string | null
​
X-Timestamp-Format
string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Body

application/json

Body for POST /v0/payment-links.

​
pint
PurchaseIntentPayload · object
required

EIP-712 PurchaseIntent payload that the requester signed.

​
signature
string
required

0x-prefixed hex ECDSA signature (130 hex chars) over the PurchaseIntent.

Pattern: ^0x[0-9a-fA-F]{130}$
​
accepted_chains
enum<integer>[]
required

Chain IDs on which the requester will accept settlement.

Minimum array length: 1

EVM-compatible blockchain networks the codebase knows about.

This is a vocabulary enum — the set of chain IDs the code can talk about for asset metadata, off-ramp routing (Meld), payment-link acceptance, and agent data lookups. It is NOT an acceptance enum: typing a request-model field as chain_id: KnownChains does NOT gate input to operational chains.

For write-boundary acceptance (onboarding, wallet creation, workflow contracts), use DeployableChain from sumvin/model/enums/chain.py.

Chain ID values follow the EIP-155 standard.

  • 1 - Ethereum Mainnet
  • 10 - Optimism
  • 137 - Polygon (formerly Matic)
  • 42161 - Arbitrum One
  • 8453 - Base
  • 43114 - Avalanche C-Chain
  • 56 - BNB Smart Chain (BSC)
  • 1328 - Sei Testnet
  • 1329 - Sei
Available options:
1,
10,
137,
42161,
8453,
43114,
56,
1328,
1329
​
expires_at
integer
required

Payment link expiry (epoch milliseconds). Must be in the future and within 90 days. Distinct from the nested pint.expires_at which is in seconds.

​
max_uses
integer | null

Maximum times this link can be settled. Null = unlimited.

Required range: x >= 1
​
fee_policy
Fee Policy · object

Opaque JSON object describing settlement fees. Shape is not yet stable — do not depend on specific keys.

​
description
string | null

Optional requester-supplied copy shown to the payer.

Maximum string length: 280

Response

Successful Response

Owner-view single payment link response.

​
_links
Links · object
required

HAL-style hypermedia links for navigation and available actions.

​
payment_link
PaymentLinkData · object
required

Payment link resource.

Example:
{
  "accepted_chains": [1329],
  "amount": "100.00",
  "asset": {
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": 6,
    "symbol": "USDC"
  },
  "created_at": 1704067200000,
  "description": "Invoice #1234",
  "expires_at": 1704153600000,
  "max_uses": 1,
  "pay_to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
  "pint_uri": "sr:us:pint:abc123",
  "slug": "q79Rx34K...",
  "status": "pending",
  "usage_count": 0
}