Skip to main content
POST
/
v1
/
payment-intents
curl -X POST https://api.stablegenius.co/v1/payment-intents \
  -H "Authorization: Bearer sk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4.50,
    "currency": "usd",
    "merchant_id": "mer_abc123",
    "metadata": {
      "order_id": "order_456",
      "terminal_id": "pos_01"
    }
  }'

const response = await fetch('https://api.stablegenius.co/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4.50,
    currency: 'usd',
    merchant_id: 'mer_abc123',
    metadata: {
      order_id: 'order_456',
      terminal_id: 'pos_01',
    },
  }),
});

const paymentIntent = await response.json();

import requests

response = requests.post(
    'https://api.stablegenius.co/v1/payment-intents',
    headers={
        'Authorization': 'Bearer sk_test_abc123',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 4.50,
        'currency': 'usd',
        'merchant_id': 'mer_abc123',
        'metadata': {
            'order_id': 'order_456',
            'terminal_id': 'pos_01',
        },
    },
)

payment_intent = response.json()

{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  "currency": "usd",
  "merchant_id": "mer_abc123",
  "payment_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
  "chain": "base",
  "token": "USDC",
  "qr_payload": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x1a2b3c4d5e6f7890abcdef1234567890abcdef12&uint256=4500000",
  "qr_image_url": "https://api.stablegenius.co/v1/qr/pi_xyz789.png",
  "expires_at": "2026-04-01T20:05:00Z",
  "metadata": {
    "order_id": "order_456",
    "terminal_id": "pos_01"
  },
  "created_at": "2026-04-01T20:00:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Amount must be between 0.01 and 10000",
    "param": "amount",
    "code": "amount_out_of_range"
  }
}

​
Create Payment Intent

Creates a payment intent and returns the payment address and QR code for the customer to scan.

​
Request

​
amount
number
required
Payment amount in USD. Minimum: 0.01. Maximum: 10000.
​
currency
string
required
Currency code. Currently only "usd" is supported.
​
merchant_id
string
required
The merchant’s Stable Genius ID (format: mer_*).
​
metadata
object
Arbitrary key-value pairs to attach to the payment intent. Max 10 keys, 500 characters per value. Returned in webhooks.
​
ttl
integer
Time-to-live in seconds. Default: 300 (5 minutes). Min: 60. Max: 3600.
​
idempotency_key
string
Unique key for idempotent requests. If the same key is sent within 24 hours, the existing payment intent is returned.

​
Response

​
id
string
Unique payment intent ID (format: pi_*).
​
object
string
Always "payment_intent".
​
status
string
"awaiting_payment" on creation.
​
amount
number
Payment amount in USD.
​
currency
string
Currency code ("usd").
​
merchant_id
string
The merchant receiving the payment.
​
payment_address
string
On-chain address for the customer to send USDC to.
​
chain
string
Blockchain network (e.g., "base").
​
token
string
Token symbol (e.g., "USDC").
​
qr_payload
string
EIP-681 formatted URI for QR code rendering. Compatible with Coinbase Wallet, MetaMask, and other EIP-681 wallets.
​
qr_image_url
string
URL to a hosted PNG image of the QR code (400x400px).
​
expires_at
string
ISO 8601 timestamp when the payment intent expires.
​
metadata
object
Your attached metadata.
​
created_at
string
ISO 8601 timestamp.
curl -X POST https://api.stablegenius.co/v1/payment-intents \
  -H "Authorization: Bearer sk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4.50,
    "currency": "usd",
    "merchant_id": "mer_abc123",
    "metadata": {
      "order_id": "order_456",
      "terminal_id": "pos_01"
    }
  }'

const response = await fetch('https://api.stablegenius.co/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_abc123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4.50,
    currency: 'usd',
    merchant_id: 'mer_abc123',
    metadata: {
      order_id: 'order_456',
      terminal_id: 'pos_01',
    },
  }),
});

const paymentIntent = await response.json();

import requests

response = requests.post(
    'https://api.stablegenius.co/v1/payment-intents',
    headers={
        'Authorization': 'Bearer sk_test_abc123',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 4.50,
        'currency': 'usd',
        'merchant_id': 'mer_abc123',
        'metadata': {
            'order_id': 'order_456',
            'terminal_id': 'pos_01',
        },
    },
)

payment_intent = response.json()

{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  "currency": "usd",
  "merchant_id": "mer_abc123",
  "payment_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
  "chain": "base",
  "token": "USDC",
  "qr_payload": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x1a2b3c4d5e6f7890abcdef1234567890abcdef12&uint256=4500000",
  "qr_image_url": "https://api.stablegenius.co/v1/qr/pi_xyz789.png",
  "expires_at": "2026-04-01T20:05:00Z",
  "metadata": {
    "order_id": "order_456",
    "terminal_id": "pos_01"
  },
  "created_at": "2026-04-01T20:00:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Amount must be between 0.01 and 10000",
    "param": "amount",
    "code": "amount_out_of_range"
  }
}