Authentication

All TransactCore ecommerce endpoints require OAuth 2.0 Bearer token authentication. Tokens are obtained from the Identity API using the Client Credentials flow.

Obtaining a Token

curl -X POST https://identity.retailsuccessplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=transactcore:payment-intents.read transactcore:payment-intents.create"

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIs..."
}

Using the Token

Include the token in the Authorization header of every request:

curl https://api.transactcore.retailsuccessplatform.com/api/v1/ecommerce/config/stripe \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Available Scopes

Scope	Grants Access To
transactcore:payment-intents.read	GET /ecommerce/config/stripe — Stripe config
	GET /ecommerce/payment-intents/{intent} — Payment intent status
transactcore:payment-intents.create	POST /ecommerce/payment-intents — Create payment intent
	POST /ecommerce/payment-intents/{intent}/cancel — Cancel payment intent
transactcore:connected-accounts.read	GET /ecommerce/connected-account — Look up connected account by organization

Request both scopes for full checkout functionality.

Rate Limits

All ecommerce endpoints share a rate limit of 100 requests per minute per IP address.

Rate limit headers are included in every response:

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

429 Too Many Requests

{
  "error": "Too many requests",
  "retry_after": 42
}

Token Management Best Practices

1. Cache tokens — Tokens are valid for the expires_in duration (typically 1 hour). Cache and reuse them.
2. Refresh before expiry — Request a new token before the current one expires to avoid interrupting checkout flows.
3. Server-side only — Never expose your access token to the browser. All TransactCore API calls should be made from your backend.
4. Minimal scopes — Request only the scopes you need. For read-only operations (e.g., checking payment status), use only transactcore:payment-intents.read.

Organization Context

TransactCore resolves the payment destination based on either:

• organization_id — Your organization's hashkey. TransactCore looks up the connected Stripe account for this organization.
• connected_account_id — A specific connected account hashkey, if you already know which account to use.

You must provide one of these when creating a payment intent. For the config endpoint, pass connected_account_id as a query parameter to retrieve the Stripe account ID for Connect mode.

Error Responses

Status	Description
401 Unauthorized	Missing or invalid access token
403 Forbidden	Token does not have the required scope
429 Too Many Requests	Rate limit exceeded

{
  "error": "Unauthenticated."
}

---

Changelog

Date	Change
2026-03-19	Added connected account lookup endpoint and fixed scope format.
2026-03-19	Initial publication.