Skip to main content
POST
/
v1
/
payment_intents
Create payment intent
curl --request POST \
  --url https://api.kryptopay.xyz/v1/payment_intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount_units": 1500000,
  "chain": "base",
  "expires_in_minutes": 15,
  "lane": "sdk",
  "metadata": {
    "order_id": "ord_2026_1001"
  }
}
'
{
  "id": "<string>",
  "status": "requires_payment",
  "client_secret": "<string>",
  "mode": "testnet",
  "chain": "base",
  "chain_id": 123,
  "confirmations_required": 123,
  "amount_units": 123,
  "decimals": 6,
  "token_symbol": "USDC",
  "token_address": "<string>",
  "expected_wallet": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "expires_in_minutes": 123,
  "lane": "sdk",
  "metadata": {}
}
Creates a payment intent for the merchant identified by your API key.
  • Base URL: https://api.kryptopay.xyz
  • Auth: Authorization: Bearer <api_key>
  • Mode is inferred from your API key (testnet or mainnet)

​
Integration examples

​
cURL

curl -X POST "https://api.kryptopay.xyz/v1/payment_intents" \
  -H "Authorization: Bearer kp_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_units": 1500000,
    "chain": "base",
    "expires_in_minutes": 15,
    "lane": "sdk",
    "metadata": { "order_id": "ord_2026_1001" }
  }'

​
Node.js (server)

const response = await fetch("https://api.kryptopay.xyz/v1/payment_intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KRYPTOPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount_units: 1500000,
    chain: "base",
    expires_in_minutes: 15,
    lane: "sdk",
    metadata: { order_id: "ord_2026_1001" },
  }),
});

const intent = await response.json();

​
Python (coming soon)

Python examples and helpers are planned. Until then, use normal HTTP requests with the same payload and Bearer auth.

​
Field guide (plain language)

  • amount_units: integer amount in smallest unit (USDC usually 6 decimals)
  • chain: target chain (base or polygon)
  • wallet_address: optional payout wallet override (0x...)
  • expires_in_minutes: checkout expiry window (server clamps to 5..60)
  • lane: checkout lane (sdk or manual)
  • metadata: your internal identifiers (order_id, customer_id, etc)
  • token: currently USDC

​
What you should persist

Persist at minimum:
  • your internal order ID
  • payment intent ID
  • returned mode/chain
  • status transitions in your backend

​
Error handling checklist

  • Retry transient failures (500, network)
  • Do not retry auth failures (api_key_missing, api_key_invalid)
  • Fix request shape for invalid_body
  • Log full response body for debugging and support

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
amount_units
integer
required

Payment amount in smallest token units (USDC uses 6 decimals).

Required range: x >= 1
​
chain
enum<string>
Available options:
base,
polygon
​
wallet_address
string

Optional recipient wallet override.

​
expires_in_minutes
integer

Intent expiry in minutes. Server clamps to 5..60.

​
lane
enum<string>
Available options:
sdk,
manual
​
metadata
object
​
token
enum<string>

Optional token selector. Currently USDC only.

Available options:
USDC

Response

Payment intent created

​
id
string
required
​
status
string
required
Example:

"requires_payment"

​
client_secret
string
required
​
mode
enum<string>
required
Available options:
testnet,
mainnet
​
chain
enum<string>
required
Available options:
base,
polygon
​
chain_id
integer
required
​
confirmations_required
integer
required
​
amount_units
integer
required
​
decimals
integer
required
Example:

6

​
token_symbol
string
required
Example:

"USDC"

​
token_address
string
required
​
expected_wallet
string
required
​
expires_at
string<date-time>
required
​
expires_in_minutes
integer
required
​
lane
enum<string>
required
Available options:
sdk,
manual
​
metadata
object
required