# Create a payment session

Creates a payment session — a configurable workflow that wraps a payment journey with pre-steps and/or post-steps such as identity verification, compliance checks, or data collection. The exact step sequence is determined by the `session_type` configured for your business.
**Example:** The `kyc_lrs` session type adds a KYC verification step before the LRS remittance checkout, ensuring the customer is verified before funds are transferred.
The `token` returned in the response should be passed to the Glomo Web SDK to launch the guided UI for the customer.
Optionally associate the session with an existing customer via `customer_id`, or pre-populate customer details using `email`. Both fields are optional and mutually exclusive — passing both returns a 400 error. Omitting both creates an anonymous session.
**Prefilling steps:** Pass prefill data to pre-populate steps in the flow so the customer skips re-entering known values. Include only the data relevant to your `session_type`.
- **KYC prefill** — identity details (`pan`, `phone`, `country`, `dob`) used to prefill
the KYC step. Two request shapes are supported: **v1** places the `kyc` object at the
top level; **v2** nests it under `data.kyc` (recommended, and the shape used alongside
other `data` groups). Provide only one shape — supplying `kyc` at both the top level and
under `data` returns a 400 error. When any of `pan`, `phone`, or `dob` is supplied, pair
it with `email`; these fields cannot be combined with `customer_id` (which is
authoritative), and supplying them without any identifier returns a 400 error. When
`phone` is supplied, `country` (ISO 3166-1 alpha-3) is required and is used to validate
the phone number format.
- **Scheme prefill** (`data.scheme`) — investment scheme details (`plan`, `amount`,
`currency`, `distributor_arn`) used to prefill the scheme plan and amount step. `amount`
and `currency` must be supplied together.

**Sessions for a named scheme:** pass `data.scheme.scheme_code` to open the session for one scheme. A distributor must send it; see [Open payment sessions as a distributor](/capital-markets/distributor/set-up). A fund can name one of its own schemes.
Contact support if you receive a 403 error — payment sessions must be enabled for your business.

Endpoint: POST /payment-sessions
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `customer_id` (string)
    The unique identifier of an existing customer (`cust_` prefix). Mutually exclusive with `email`.
    Example: cust_abc123XYZ

  - `email` (string)
    Email address to pre-populate customer details in the session flow. Mutually exclusive with `customer_id`.
    Example: john.doe@example.com

  - `kyc` (object)
    KYC prefill (v1) — identity details used to prefill the KYC step. Equivalent to `data.kyc` (v2, recommended); provide one shape or the other, not both. Only accepted when `customer_id` or `email` is also provided at the top level.

  - `kyc.pan` (string)
    Indian Permanent Account Number. Format: 10 characters, e.g. `ABCPE1234F`.
    Example: ABCPE1234F

  - `kyc.phone` (string)
    Customer phone number, validated against `country`. Must be supplied together with `country` — phone without country is rejected.
    Example: 9876543210

  - `kyc.country` (string)
    ISO 3166-1 alpha-3 country code used to validate `phone` (e.g. `IND`, `USA`, `GBR`).
    Example: IND

  - `kyc.dob` (string)
    Date of birth in ISO 8601 format (`YYYY-MM-DD`).
    Example: 1990-05-12

  - `data` (object)
    Optional container for prefill data. Include only the groups relevant to your `session_type`; unknown groups are ignored. When present it must be a JSON object; an array, string, number or boolean returns a 400 error.

  - `data.kyc` (object)
    KYC prefill (v2, recommended) — identity details used to prefill the KYC step. Same fields as the top-level `kyc` (v1); the two shapes cannot be combined.

  - `data.kyc.pan` (string)
    Indian Permanent Account Number. Format: 10 characters, e.g. `ABCPE1234F`.
    Example: ABCPE1234F

  - `data.kyc.phone` (string)
    Customer phone number, validated against `country`. Must be supplied together with `country` — phone without country is rejected.
    Example: 9876543210

  - `data.kyc.country` (string)
    ISO 3166-1 alpha-3 country code used to validate `phone` (e.g. `IND`, `USA`, `GBR`).
    Example: IND

  - `data.kyc.dob` (string)
    Date of birth in ISO 8601 format (`YYYY-MM-DD`).
    Example: 1990-05-12

  - `data.scheme` (object)
    Investment scheme details used to prefill the scheme plan and amount step. Include `scheme_code` to open the session for a named scheme.

  - `data.scheme.scheme_code` (string)
    Code of the AMC scheme the session is for. Case-insensitive. Required for a distributor.
    Example: SCH001

  - `data.scheme.plan` (string)
    AMC scheme plan. Ignored for a distributor. With `scheme_code`, it must match the scheme's plan.
    Enum: "regular", "direct"

  - `data.scheme.amount` (integer)
    Investment amount in the smallest currency unit (e.g. cents for USD, so `500000` is $5,000.00). Must be a positive integer and supplied together with `currency`. Send a multiple of `100` (whole dollars): the checkout form accepts only whole-dollar amounts, so a prefill with cents, such as `500050`, is shown to the customer as invalid until they change it.
    Example: 500000

  - `data.scheme.currency` (string)
    Currency of `amount`. Only `USD` is supported. Supplied together with `amount`.
    Enum: "USD"

  - `data.scheme.distributor_arn` (string)
    AMC distributor ARN. Must start with your configured distributor-code prefix, if one is set for your business. Ignored for a distributor.
    Example: ARN12345

## Request examples:

  - `Anonymous session` (unknown)

  - `With customer email` (unknown)

  - `With existing customer ID` (unknown)

  - `Prefill KYC — top-level kyc object (v1)` (unknown)

  - `Prefill KYC — nested under data (v2, recommended)` (unknown)

  - `Prefill scheme plan and amount` (unknown)

  - `Session for a named scheme (scheme_code)` (unknown)

## Response 201:

  - `201` (unknown)
    Payment session created successfully.

## Response 201 fields (application/json):

  - `id` (string)
    Unique identifier for the payment session, prefixed with `psess_`.
    Example: psess_6819d8046mpKt

  - `status` (string)
    Current status of the payment session.
- `active` — the customer can go through the session.
- `completed` — the customer finished every step. Terminal.
- `failed` — the session ended without finishing. Terminal.
- `expired` — the session passed `expires_at` before it finished. Terminal.
    Enum: "active", "completed", "failed", "expired"

  - `session_type` (string)
    The workflow type configured for this session, which determines the pre-steps and/or
post-steps in the payment journey. The value is configured per business by Glomo; you do not
choose it per request.
- `kyc_lrs` — KYC, then an LRS remittance checkout.
- `kyc_lrs_folio` — mutual fund investment from India under LRS: folio and scheme selection, KYC,
then an LRS remittance checkout.
- `kyc_nri_individual_verification` — onboarding of an individual NRI investor, ending when KYC
(including video KYC) completes.
- `kyc_nri_joint_verification` — NRI investor verification that collects folio and scheme selection
before KYC.
- `kyc_inbound_folio` — mutual fund investment by an NRI investor: folio and scheme selection, NRI
KYC, folio creation, then an inbound checkout.
    Enum: "kyc_lrs", "kyc_lrs_folio", "kyc_nri_individual_verification", "kyc_nri_joint_verification", "kyc_inbound_folio"

  - `token` (string)
    Short-lived JWT token to be passed to the Glomo Web SDK to launch the session UI for the customer.
    Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

  - `expires_at` (string)
    ISO 8601 timestamp when the session expires.
    Example: 2026-05-07T10:30:00Z

## Response 400:

  - `400` (unknown)
    Bad request — validation error, including an invalid format for `email`, `customer_id`, `pan`, `phone`, `country`, or `dob`, or `phone` supplied without `country`; mutually exclusive fields provided; prefill fields supplied without an identifier; KYC prefill supplied both at the top level (v1) and under `data` (v2); `data` that is not an object; or a blank or missing `scheme_code` (required for distributors). Validation errors carry a `Validation failed: ` prefix in `message`.

## Response 400 fields (application/json):

  - `error` (string)
    Example: Bad Request

  - `message` (string)
    Example: customer_id or email is required when pan, phone, or dob is supplied

## Response 401:

  - `401` (unknown)
    Unauthorized — missing or invalid JWT token.

## Response 401 fields (application/json):

  - `error` (string)
    Example: Unauthorized

  - `message` (string)
    Example: Invalid or missing authentication token

## Response 403:

  - `403` (unknown)
    Forbidden — payment sessions are not enabled for this business. For a distributor, also:
- `No active relationship with this fund` - `Scheme not enabled for this relationship`

## Response 403 fields (application/json):

  - `error` (string)
    Example: Forbidden

  - `message` (string)
    Example: Payment session is not enabled for this business

## Response 404:

  - `404` (unknown)
    Not found — `scheme_code` does not match an active scheme you can use.

## Response 404 fields (application/json):

  - `error` (string)
    Example: Not Found

  - `message` (string)
    Example: Scheme not found

## Response 409:

  - `409` (unknown)
    Conflict — the `pan` supplied is already registered under a different email, on an existing customer or an in-progress KYC.

## Response 409 fields (application/json):

  - `error` (string)
    Example: Conflict

  - `message` (string)
    Example: PAN is already registered with a different email

## Response 422:

  - `422` (unknown)
    Unprocessable entity — with `scheme_code`:
- `plan must match the scheme` - `Scheme is not available for distribution` (a direct plan, for a distributor) - `Fund is not configured for scheme sessions` - `Distributor ARN is not configured for this fund` - `customer_id is not supported for relationship-originated sessions`

## Response 422 fields (application/json):

  - `error` (string)
    Example: Unprocessable Entity

  - `message` (string)
    Example: Scheme is not available for distribution