Initialize a New Session

The first step in the tokenization workflow is to initialize a payment session via the PayNetWorx API.

Overview

Use your server to initialize a session by making a secure API call to PayNetWorx. This involves making a POST request using secure credentials, including your API Key.

API Endpoint

https://{{PNX_HOSTED_PAYMENTS_URL}}/v1/payments/sessions/create

Environment URLs

Replace PNX_HOSTED_PAYMENTS_URL with the appropriate environment URL.

See QA Environment or PROD Environment for specific URLs.

Request Type

interface PaymentsSessionsCreate {
  payment_session: {
    /** Used for tracking payment session end-to-end. Ignored if max_uses_count != 1 or undefined. Preferred format: KSUID */
    payment_session_request_id?: string
    /** How the payment session is used */
    payment_session_use: 'TOKENIZE_CARD'
    /** Payment session metadata tied to /payments/* calls */
    payment_session_metadata?: PaymentSessionMetadata
    /** When to the payment_session will expire */
    payment_session_expire?: PaymentSessionExpire
  }
  page_style?: {
    /** ID of a preconfigured page style via portal */
    page_style_id?: string
    /** Name of a preconfigured page style via portal */
    page_style_name?: string
  }
  /** Metadata associated with request in JSON format */
  metadata?: any
}

// Supporting types

interface PaymentSessionMetadata {
  merchant_detail?: {
    /** key/value */
    merchant_data?: any
  }
  source_detail?: {
    /** Name of device calling api */
    device?: string
    device_version?: string
    /** Name of application calling api */
    application?: string
    application_version?: string
    timestamp?: string
  }
  payment_session_defaults?: PaymentSessionDefaults
}

interface PaymentSessionDefaults {
  tokenize_data?: {
    card?: {
      cardholder_name?: DefaultValueType
      billing_address?: {
        line_1?: DefaultValueType
        line_2?: DefaultValueType
        city?: DefaultValueType
        state?: DefaultValueType
        postal_code?: DefaultValueType
        country?: DefaultValueType
      }
    }
  }
}

interface DefaultValueType {
  value?: string
  hidden?: boolean
  read_only?: boolean
  required?: boolean
  label?: string
  placeholder?: string
  hint?: string
}

interface PaymentSessionExpire {
  /** When the payment session will expire at. Format: UTC ISO datetime. If null, never expire. Ex: "2026-06-15T21:58:55.551Z". Default: 10 minutes */
  expires_at?: string | null
  /** Max amount of times the payment session can be used. If null, unlimited uses. Default: 1  */
  max_uses_count?: string | null
}

Request Example (Basic)

// Make the api request to initialize the Payment Session
async function initializePaymentSession() {
  const headers = new Headers();
  headers.append("Content-Type", "application/json");
  headers.append("Authorization", "{{ YOUR_API_KEY }}"); // Include your provided PNX Api key in the Authorization Header

  const api_response = await fetch(
    `https://{{PNX_HOSTED_PAYMENTS_URL}}/v1/payments/sessions/create`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        payment_session: {
          payment_session_use: "TOKENIZE_CARD",
        },
      }),
    }
  );
  return await api_response.json();
}

Response Type

interface PaymentsSessionsCreate {
  /** The request_type or request_name of the route associated with the response */
  request_type: string
  /** Uuid created by the api associated with the api request */
  request_id: string
  /** Payment session data */
  payment_session: {
    payment_session_id: string
    /** Url pointed to payment iframe with payment_session details */
    payment_session_url: string
    /** Present if max_uses_count = 1 Format: KSUID */
    payment_session_request_id?: string
    /** Format: YYYY-MM-DDTHH:MI:SS.FFFZ UTC */
    expires_at: string | null
    /** Max amount of times the payment session can be used */
    max_uses_count: string | null
  }
}

IMPORTANT

Save the payment_session_url from the response - you'll need this in the next step to embed the payment form iframe.

Next Step

Once you have the payment session initialized, proceed to embed the iFrame in your application.