Create a payment session

POST /api/v1/payment/sessions

Creates a new payment session object.

Servers

• Production server: https://api.1099policy.com (Production server)

Parameters

Body: application/json (object)

• contractor (string)
  The public ID of the contractor (e.g., cn_AbCdEfGh12). Must belong to your tenant. A contractor ID that does not belong to your tenant returns 404 to avoid leaking existence.

• return_url (string)
  HTTPS URL the contractor will be redirected to when the flow terminates. The host must be in your organization's configured hosted_flow_allowed_redirect_hosts allowlist. Exact-match only; no wildcards, no suffix matching. URLs with credentials (user:pass@) or fragments are rejected.

Responses

201

Session created. The url field is shown exactly once and contains the single-use token the contractor must land on.

Body: application/json (object)

• cancelled_at (integer(int64) | null)
  Time at which the session was cancelled by you or by the contractor. Null unless status is cancelled. Measured in seconds since the Unix epoch.

• completed_at (integer(int64) | null)
  Time at which the session reached completed. Null unless the contractor successfully saved a card. Measured in seconds since the Unix epoch.

• contractor_id (string)
  Public ID of the contractor the session is scoped to.

• created (integer(int64))

• expires_at (integer(int64))
  Time at which a pending session expires and becomes unusable. Measured in seconds since the Unix epoch. Default lifetime is 30 minutes from creation.

• id (string)

• processor (string)
  Identifier for the payment provider backing this session. checkout is the default and currently the only supported value. Reserved so future providers can be added without a breaking schema change.

• return_url (string)
  HTTPS URL the contractor is redirected to when the flow terminates. The host must be in your organization's configured hosted_flow_allowed_redirect_hosts allowlist; exact host match only, no wildcards. URLs with credentials (user:pass@) or fragments are rejected at creation time.

• status (string)
  Current status of the session. pending is the only state in which the URL can be used; the other three are terminal.

• url (string)
  The single-use URL to redirect the contractor to. Shown exactly once, at session creation. The token embedded in this URL is a secret — do not log it, do not persist it, do not share it beyond the contractor's browser.

400

Invalid input. invalid_return_url when the return URL fails scheme / host / allowlist validation. Ensure your organization has hosted_flow_allowed_redirect_hosts configured.

403

Missing or invalid API key.

404

Contractor not found. Returned when the contractor does not exist under your tenant.