Paysettly API / v1

Your application.
Our checkout.

Create a payment, receive a Paysettly-hosted URL and redirect your customer to it. All payment processing is currently sandbox-only.

Create a payment

POST https://paysettly.com/v1/payments
x-api-key: YOUR_API_KEY
Idempotency-Key: order-123
content-type: application/json

{
  "amount": "48.00",
  "currency": "USDC",
  "network": "base",
  "customer_reference": "order_1001",
  "description": "Studio plan",
  "expiry": 30,
  "return_url": "https://merchant.example/order/1001"
}

Response

{
  "id": "pay_...",
  "url": "https://paysettly.com/p/pay_...",
  "status": "waiting",
  "demo": true,
  "fee_charged_to_customer": "0.00",
  "fee_policy": "Paysettly fee is taken from the merchant at settlement, not added to the quote.",
  "message": "Chain engine is not live. This payment is demo-only and cannot be paid."
}

Use a unique Idempotency-Key for each order. Retrying the same validated payment fields with the same key returns the original payment, including concurrent retries. Reusing it with different fields returns HTTP 409. Keys are scoped to your merchant account and accept 1 to 128 letters, digits or _.:-.

Read payment status

GET https://paysettly.com/v1/payments/pay_...
x-api-key: YOUR_API_KEY

GET https://paysettly.com/v1/payments?limit=50&offset=0
x-api-key: YOUR_API_KEY

These endpoints return only your own payments. List results use payments, limit and offset; the limit must be 1 to 200. A checkout link is public, while merchant API records require authentication.

Validation & errors

CSS, HTML, fonts, checkout domains, iframe domains and trust-mark controls are not accepted. Unavailable combinations are rejected; the API does not silently change the requested currency.

{
  "error": {"code": 401, "message": "Invalid API key"},
  "detail": "Invalid API key"
}

Verify a webhook

Configure a public HTTPS endpoint. Requests include a Paysettly-Signature header in the form t=timestamp,v1=digest. Calculate HMAC-SHA256 over the exact bytes of timestamp.raw_body with your webhook secret, then compare the digest in constant time.

import hashlib, hmac, time

parts = dict(item.split("=", 1) for item in header.split(","))
timestamp = parts["t"]
if abs(time.time() - int(timestamp)) > 300:
    raise ValueError("Signature timestamp expired")
signed = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts["v1"]):
    raise ValueError("Invalid signature")

Deduplicate using the Idempotency-Key header and acknowledge with a 2xx response. Delivery stops after three attempts. The merchant console shows attempts and the last result. Sandbox checkout creation does not automatically emit a paid event. Use the merchant-owned simulation endpoint or payment detail view to exercise test events. Never fulfil real orders when live_payments is false.

Sandbox events

POST /v1/payments/pay_.../simulate
x-api-key: YOUR_API_KEY
content-type: application/json

{"event":"paid"}

Events: confirming, paid, underpaid, overpaid, wrong_asset, wrong_network, expired, cancelled, review, preparing and failed. Wrong amount and asset/network outcomes never credit. Simulation cannot change testnet payments or showcase examples.

Payment statuses

waiting, confirming, paid, partial, over, expired and cancelled. A sandbox payment is never a receipt for real funds.