API reference

A curated reference for the merchant-facing REST API. All endpoints live under https://api.faststarpay.com/api/v1 and return the standard { success, message, data } envelope.

Authentication & conventions

Create an API key in the merchant dashboard and send it on every request as the X-API-Key header. Keep it server-side only.
Request and response bodies are JSON (Content-Type: application/json).
All amounts are integers in the smallest currency unit (e.g. 999 = $9.99 USD).
Successful responses look like { "success": true, "message": "...", "data": { ... } }; failures carry "success": false and an explanatory message.

curl https://api.faststarpay.com/api/v1/public/checkout/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Checkout Sessions

Endpoint	Method	Description
`/public/checkout/sessions`	POST	Create a session (`payment` \| `subscription` \| `setup`); returns the hosted checkout `url`
`/public/checkout/sessions/:id`	GET	Retrieve a session (status, amounts)

curl https://api.faststarpay.com/api/v1/public/checkout/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "presentation": "iframe",
    "line_items": [{ "price_id": "price_xxx", "quantity": 1 }],
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  }'

Full field documentation and the response shape live in the Checkout Sessions guide. Note: MoR merchants must reference catalog price_id/product_id in every line item.

Products & Prices (catalog)

Endpoint	Method	Description
`/merchant/catalog/products`	POST	Create a product (`name` required; optional `description`, `tax_category`, `images`, `metadata`)
`/merchant/catalog/products`	GET	List products
`/merchant/catalog/prices`	POST	Create a price for a product
`/merchant/catalog/prices`	GET	List prices

Price fields: product_id, currency and unit_amount (smallest currency unit) are required; type is one_time or recurring, and recurring prices take a recurring_interval (plus optional recurring_interval_count and trial_period_days).

curl https://api.faststarpay.com/api/v1/merchant/catalog/prices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "currency": "USD",
    "unit_amount": 1900,
    "type": "recurring",
    "recurring_interval": "month"
  }'

Customers & payment methods

Endpoint	Method	Description
`/public/customers`	POST	Create a customer (`email` required)
`/public/customers`	GET	List customers
`/public/customers/:id`	GET	Retrieve a customer
`/public/customers/:id/setup-intent`	POST	Create a SetupIntent for saving a card → `{ client_secret, publishable_key, setup_intent_id }`
`/public/customers/:id/payment-methods`	POST	Attach the card from a completed SetupIntent (`{ setup_intent_id }`) → masked card `{ id: "pm_…", brand, last4, exp_month, exp_year }`
`/public/customers/:id/payment-methods`	GET	List a customer's saved cards (masked)
`/public/customers/:id/charge`	POST	Charge a saved card off-session; returns HTTP 402 when SCA is required
`/public/payment-methods/:id/default`	POST	Make a saved card the customer's default
`/public/payment-methods/:id`	DELETE	Detach a saved card

curl -X POST https://api.faststarpay.com/api/v1/public/customers/cus_xxx/charge \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_id": "pm_xxx", "amount": 1999, "currency": "USD", "off_session": true }'

See the saved cards guide for the end-to-end flow.

Tax

Endpoint	Method	Description
`/public/tax/calculate`	POST	Quote tax for an amount and buyer location (MoR)

curl https://api.faststarpay.com/api/v1/public/tax/calculate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "country": "DE" }'

Response data:

{
  "country": "DE",
  "tax_type": "vat",
  "rate_percent": 19,
  "inclusive": true,
  "tax_amount": 160,
  "net_amount": 840,
  "gross_amount": 1000
}

Webhook signature verification

Endpoint	Method	Description
`/public/verify-signature`	POST	Verify a webhook signature (`{ provider_name, payload, signature }` → `{ valid }`)

Verifying merchant webhook signatures locally with HMAC is recommended — see the webhooks guide.

Errors

Errors use conventional HTTP status codes plus the response envelope ("success": false with a human-readable message):

Status	Meaning	Typical cause
`400`	Bad request	Missing or invalid fields (e.g. missing `line_items`, MoR line item without a catalog reference)
`401`	Unauthorized	Missing or invalid `X-API-Key`
`402`	Payment required	Off-session charge needs Strong Customer Authentication — re-run on-session
`404`	Not found	Unknown id (customer, session, price, …)
`5xx`	Server error	Transient failure — retry with backoff

{ "success": false, "message": "Payment requires additional authentication" }