Interface: CreateBusinessTransactionOptions

Constructs a fully-formed, internally-consistent BusinessTransaction from the fields a caller actually decides, deriving every field the server’s own BusinessTransactionValidator checks for cross-consistency (packages/runtime/src/validators/BusinessTransactionValidator.ts) so a caller can never build a request that fails one of those checks by mistake:

• metadata.businessTransactionId always equals businessTransactionId
• authorization.authorityId always equals authority.authorityId
• intent.authorizationId always equals authorization.authorizationId

Hand-building a BusinessTransaction by writing out all five nested objects and keeping three id pairs in sync by hand is exactly the class of mistake that produced every “X must match Y” 400 response documented in docs/site/guides/end-to-end-paytm-flow.mdx. This function exists so that mistake cannot arise when going through the SDK, not merely documented as something to be careful about. businessTransactionId defaults to a fresh crypto.randomUUID() if omitted. A caller providing one explicitly is responsible for it being unique per attempt, since it doubles as the server’s own idempotency key (see docs/site/guides/end-to-end-paytm-flow.mdx, “businessTransactionId is an idempotency key”).

​

Properties

​

businessTransactionId?

readonly optional businessTransactionId?: string

Defaults to a fresh crypto.randomUUID() if omitted.

---

​

authorityType?

readonly optional authorityType?: "USER" | "ROLE" | "SERVICE" | "ORGANIZATION"

Defaults to “SERVICE”, the correct value for an autonomous agent. Never “AGENT”; that value does not exist server-side.

---

​

principalId

readonly principalId: string

The identity this transaction is submitted as. Must match one of the caller API key’s own allowedPrincipalIds server-side, or the request is rejected before policy ever runs. See GET /callers/me.

---

​

displayName?

readonly optional displayName?: string

---

​

purpose

readonly purpose: string

Human-readable reason for authorization.purpose.

---

​

action

readonly action: string

The capability being invoked, e.g. “paytm:refund”.

---

​

target

readonly target: string

---

​

parameters

readonly parameters: Record<string, unknown>

---

​

policy

readonly policy: PolicyReference

---

​

signals

readonly signals: Record<string, unknown>

Facts the named policy evaluates. Every fact a policy rule references must appear here, and every boundSignals entry the policy declares is cross-checked against the matching intent field (see the policy’s own boundSignals) before evaluation runs at all. A mismatch is rejected as a binding-tamper attempt, not silently ignored.

---

​

correlationId?

readonly optional correlationId?: string

---

​

tenantId?

readonly optional tenantId?: string

---

​

sourceSystem?

readonly optional sourceSystem?: string

---

​

submittedBy?

readonly optional submittedBy?: string