POST /api/v1/payment/sessions

Creates a new payment session object.

application/json

Body

  • contractor string Required

    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 Required

    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 application/json

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

    Hide response attributes Show response attributes 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)

      Time at which the object was created. Measured in seconds since the Unix epoch.

    • 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

      Unique identifier for the object.

    • 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.

      Value is checkout.

    • 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.

      Values are pending, completed, cancelled, or expired.

    • 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.

POST /api/v1/payment/sessions 
curl \
 --request POST 'https://api.1099policy.com/api/v1/payment/sessions' \
 --header "Content-Type: application/json" \
 --data '{"contractor":"cn_AbCdEfGh12","return_url":"https://app.yourplatform.com/settings/billing/return"}'
Request example 
{
  "contractor": "cn_AbCdEfGh12",
  "return_url": "https://app.yourplatform.com/settings/billing/return"
}
Response examples (201) 
{
  "cancelled_at": 42,
  "completed_at": 1713369924,
  "contractor_id": "cn_Ehb3bYa",
  "created": 1646818364,
  "expires_at": 1713371724,
  "id": "string",
  "processor": "checkout",
  "return_url": "https://app.yourplatform.com/settings/billing/return",
  "status": "pending",
  "url": "https://my.1099policy.com/payment/setup/live_<token>"
}