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


[Powered by Bump.sh](https://bump.sh)