Create a Session
POST /sessions
Before you integrate
Create sessions on your backend. Authentication is supplied inside the request body even though this operation declares no OpenAPI security scheme. Choose the gateway or merchant-central credentials described in the session guide. Gateway keys must start with v4_secret_; explicitly set gateway.environment to sandbox for sandbox work because the documented default is production. The source narrative selects one credential family while its schema uses anyOf; do not interpret that as a requirement to send both. Create an embedded reporting session
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.nmi.com/api/v5/embedded-reporting
Session lifecycle
Create the session on your backend, then pass only its short-lived token to the authorized browser. The default lifetime is 15 minutes; renew through your backend before expiry when needed. This flow is for session-authenticated embedded components, not the Payment Component. Backend → Reporting API: create a session using server credentials. Reporting API → Backend → Client: return the session token. Client → Embedded component: initialize with the token. Embedded component ↔ Reporting API: authenticate data requests with the token. Before expiry → Backend: request a replacement session. Client Your backend Reporting API Component 1 2 Create session with API key 2 1 Return session token 1 0 Pass token to client 0 3 Initialize component 3 2 Request data with token 2 3 Return component data
Request examples
Choose your server language. These equivalent Gateway sandbox examples are adapted for this portal, not executed account tests. Set NMI_API_KEY and NMI_MERCHANT_ID on your server; replace the Shell placeholders. Merchant Central uses the alternative body documented below. curl --request POST 'https://sandbox.nmi.com/api/v5/embedded-reporting/sessions' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "gateway": { "api_key": "<v4_secret_api_key>", "merchant_id": "<merchant_id>", "environment": "sandbox" } }' // Run on your server. Load secrets from your environment. const response = await fetch('https://sandbox.nmi.com/api/v5/embedded-reporting/sessions', { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify({ gateway: { api_key: process.env.NMI_API_KEY, merchant_id: process.env.NMI_MERCHANT_ID, environment: 'sandbox' } }) }); if (!response.ok) throw new Error(`Session request failed: ${response.status}`); const session = await response.json(); // Return the session token to your authorized client, never the API key. import json, os from urllib.request import Request, urlopen payload = {'gateway': { 'api_key': os.environ['NMI_API_KEY'], 'merchant_id': os.environ['NMI_MERCHANT_ID'], 'environment': 'sandbox' }} request = Request('https://sandbox.nmi.com/api/v5/embedded-reporting/sessions', data=json.dumps(payload).encode(), method='POST', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}) # Non-success responses raise HTTPError; handle them in your application. with urlopen(request, timeout=30) as response: session = json.load(response) # Pass the session token to your authorized client; keep credentials private. require 'uri' require 'net/http' require 'json' uri = URI('https://sandbox.nmi.com/api/v5/embedded-reporting/sessions') request = Net::HTTP::Post.new(uri) request['Accept'] = 'application/json' request['Content-Type'] = 'application/json' request.body = { gateway: { api_key: ENV.fetch('NMI_API_KEY'), merchant_id: ENV.fetch('NMI_MERCHANT_ID'), environment: 'sandbox' } }.to_json response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 30) do |http| http.request(request) end raise "Session request failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess) session = JSON.parse(response.body) # Pass the session token to your authorized client, never the API key. <?php $payload = ['gateway' => [ 'api_key' => getenv('NMI_API_KEY'), 'merchant_id' => getenv('NMI_MERCHANT_ID'), 'environment' => 'sandbox' ]]; $curl = curl_init('https://sandbox.nmi.com/api/v5/embedded-reporting/sessions'); curl_setopt_array($curl, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Accept: application/json', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR) ]); $result = curl_exec($curl); $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); if ($result === false || $status < 200 || $status >= 300) { throw new RuntimeException('Session request failed'); } curl_close($curl); $session = json_decode($result, true, 512, JSON_THROW_ON_ERROR); // Return the session token to your authorized client, never the API key.
Request route
This endpoint creates a short-lived session token that your embedded components can use to authenticate and fetch data. You must call this endpoint from your backend server to avoid exposing your API key. POST /sessions Security scheme Type Credential location Scopes None declared Verify account setup Not inferred Not inferred
Path and query parameters
Required flags apply to the parameter itself. Additional limits and enum values appear in the contract below. Parameter Location Required Type Description accept header true string application/json content-type header true string application/json [ { "in": "header", "name": "accept", "schema": { "type": "string", "default": "" }, "description": "application/json", "required": true }, { "in": "header", "name": "content-type", "schema": { "type": "string", "default": "" }, "description": "application/json", "required": true } ] true
Request body
Use the declared media type: application/json. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints [Gateway].gateway object yes Credentials and options required to create a session for Gateway components. [Gateway].gateway.api_key string yes The api key to retrieve the session token. MUST start with `v4_secret_`. Maximum 255 characters. [Gateway].gateway.merchant_id string yes The specific merchant ID to scope the session to. Maximum 20 digits. [Gateway].gateway.environment string no Specifies the gateway environment. enum: ["production", "sandbox"]; default: "production" [Merchant Central].merchant-central object yes Credentials and options required to create a session for Merchant Central components. [Merchant Central].merchant-central.api_key string yes Merchant Central API key. Maximum 255 characters. [Merchant Central].merchant-central.tenant_id string yes Your Merchant Central subdomain, e.g., "XXX" for XXX.iriscrm.com. Maximum 200 characters. [Merchant Central].merchant-central.merchant_id string yes The specific merchant ID to scope the session to. Maximum 20 digits. { "description": "An optional request body to specify constraints for the session.", "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "title": "Gateway", "properties": { "gateway": { "type": "object", "description": "Credentials and options required to create a session for Gateway components.", "properties": { "api_key": { "type": "string", "description": "The api key to retrieve the session token. MUST start with `v4_secret_`. Maximum 255 characters.", "example": "51123456" }, "merchant_id": { "type": "string", "description": "The specific merchant ID to scope the session to. Maximum 20 digits." }, "environment": { "type": "string", "enum": [ "production", "sandbox" ], "default": "production", "description": "Specifies the gateway environment." } }, "required": [ "merchant_id", "api_key" ] } }, "required": [ "gateway" ] }, { "type": "object", "title": "Merchant Central", "properties": { "merchant-central": { "type": "object", "description": "Credentials and options required to create a session for Merchant Central components.", "properties": { "api_key": { "type": "string", "description": "Merchant Central API key. Maximum 255 characters." }, "tenant_id": { "type": "string", "description": "Your Merchant Central subdomain, e.g., \"XXX\" for XXX.iriscrm.com. Maximum 200 characters." }, "merchant_id": { "type": "string", "description": "The specific merchant ID to scope the session to. Maximum 20 digits." } }, "required": [ "api_key", "tenant_id", "merchant_id" ] } }, "required": [ "merchant-central" ] } ] }, "examples": { "Gateway": { "summary": "Gateway", "value": { "gateway": { "api_key": "CORRECT_API_KEY", "merchant_id": "12345", "environment": "sandbox" } } }, "Merchant Central": { "summary": "Merchant Central", "value": { "merchant-central": { "api_key": "CORRECT_API_KEY", "tenant_id": "mycentral", "merchant_id": "123456789" } } } } } } } true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json Session created successfully. 401 application/json Unauthorized 422 application/json Unprocessable Entity { "200": { "description": "Session created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string", "example": "8910cbad-eed7-ad6c-572b2be67201.69613616.ZrEjQlHsm-uj9Iy5DTfK5KqaKrtVWeNk4LrfcTVFXQ4ESLCkOi0zHwHVu_Bv8H_j" }, "expires_at": { "type": "string", "example": "2025-12-20T17:13:38+00:00" } } }, "examples": { "OK": { "summary": "OK", "value": { "session_token": "8910cbad-eed7-ad6c-572b2be67201.69613616.ZrEjQlHsm-uj9Iy5DTfK5KqaKrtVWeNk4LrfcTVFXQ4ESLCkOi0zHwHVu_Bv8H_j", "expires_at": "2025-12-20T17:13:38+00:00" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Missing/Invalid Authentication" } } }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "message": "Missing/Invalid Authentication" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "The gateway.merchant_id field must be a numeric string" }, "errors": { "type": "object", "properties": { "gateway.merchant_id": { "type": "array", "items": { "type": "string", "example": "The gateway.merchant_id field must be a numeric string" } } } } } }, "examples": { "Unprocessable Entity": { "summary": "Unprocessable Entity", "value": { "message": "The gateway.merchant_id field must be a numeric string", "errors": { "gateway.merchant_id": [ "The gateway.merchant_id field must be a numeric string" ] } } } } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints session_token string no expires_at string no
Response fields · 401 · application/json
Field Type Required Description Constraints message string no
Response fields · 422 · application/json
Field Type Required Description Constraints message string no errors object no errors.gateway.merchant_id array no
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. {} true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.