Schemas

Response Envelope

TransactCore uses two response formats depending on the endpoint:

Success (with data wrapper)

Used by GET /payment-intents/{id}:

{
  "data": {
    "payment_intent_id": "pi_3abc123",
    "amount": 3420,
    "currency": "usd",
    "status": "succeeded"
  }
}

Success (flat)

Used by POST /payment-intents and GET /config/stripe:

{
  "client_secret": "pi_3abc123_secret_xyz789",
  "payment_intent_id": "pi_3abc123",
  "publishable_key": "pk_live_xxxxx",
  "amount": 3420,
  "currency": "usd"
}

Error

{
  "error": "Error message describing what went wrong",
  "message": "Additional details (optional)"
}

Validation Error

{
  "message": "The amount field must be at least 50.",
  "errors": {
    "amount": ["The amount field must be at least 50."]
  }
}

---

Common Error Codes

HTTP Status	Error	Description
400	Payment account cannot accept payments	Connected account has incomplete onboarding or is restricted
401	Unauthenticated	Missing or invalid Bearer token
403	Forbidden	Token does not have the required scope
404	Payment intent not found	No payment intent exists with the given ID
404	No payment account configured	Organization has no connected Stripe account
422	Validation error	Request body failed validation (see errors object)
422	Unable to cancel payment intent	Payment intent is in a non-cancelable state
429	Too many requests	Rate limit exceeded
500	Failed to create payment intent	Stripe API error or internal server error

---

Currency

All amounts are in the smallest currency unit (cents for USD).

Amount	Meaning
50	$0.50 (minimum)
3420	$34.20
100000	$1,000.00

The currency field accepts ISO 4217 three-letter codes. Default: usd.

---

Rate Limit Headers

All responses include rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
Retry-After	Seconds until reset (only on 429 responses)

All ecommerce endpoints: 100 requests per minute per IP address.

---

Hashkeys

TransactCore uses hashkeys as external identifiers for resources. Hashkeys are prefixed strings that encode internal IDs:

Resource	Prefix	Example
Connected Account	cct_	cct_00000k1L2m3N4o5
Organization	org_	org_00000k1L2m3N4o5

Payment intents use Stripe's native IDs (e.g., pi_3abc123) rather than hashkeys.

---

Changelog

Date	Change
2026-03-19	Initial publication.