Get a PIN-entry URL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "iframeUrl": "https://embed.example.com/pin?session=eyJhbGciOiJIUzI1NiJ9...",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-05-08T14:16:00Z",
  "environment": "SANDBOX"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Cards

Get a PIN-entry URL

Get a temporary URL for a secure PIN-entry iframe. The cardholder chooses a four-digit PIN inside the iframe, without the plaintext PIN crossing your servers or Grid’s. Grid supports online PINs only.

Configure cardConfigs.pinTargetOrigin through PATCH /config before requesting a URL. It is the canonical HTTPS origin of the page that hosts the iframe. The iframe is restricted to that origin; this endpoint takes no request body or origin parameter.

Each call creates a fresh, temporary PIN-entry session. Request a URL immediately before displaying the form. Fetching the URL does not set or change the PIN. Set your iframe’s src to the returned iframeUrl without modifying it. Follow the Card PIN guide to submit the form and confirm the result. Never store, cache, or log the URL or token. The session expires at expiresAt and permits one successful PIN submission. Responses include Cache-Control: no-store.

Use the iframe’s submission result to confirm completion, and GET /cards/{id} to read pinStatus. OK alone cannot confirm a change to an already configured PIN.

If you operate your own PIN-entry UI, use POST /cards/{id}/set-pin with a client-encrypted payload instead.

Requires permission to manage cards. Every successful URL request is audit-logged with the requesting actor.

GET

cards

{id}

pin-entry-url

Get a PIN-entry URL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/cards/{id}/pin-entry-url")
  .get()
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

{
  "iframeUrl": "https://embed.example.com/pin?session=eyJhbGciOiJIUzI1NiJ9...",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-05-08T14:16:00Z",
  "environment": "SANDBOX"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Path Parameters

string

required

System-generated unique card identifier

Response

A fresh PIN-entry URL and its expiration.

A temporary PIN-entry iframe URL, its credential, and expiration.

iframeUrl

string<uri>

required

Ready-to-use URL for the secure PIN-entry iframe. Set this as your iframe's src without modifying it. The cardholder enters their PIN inside the iframe, so the plaintext PIN never reaches your servers or Grid's. Use the message flow in the Card PIN guide to submit and confirm the result.

The URL contains a temporary credential. Never store, cache, or log it. It expires at expiresAt and permits one successful PIN submission.

Example:

"https://embed.example.com/pin?session=eyJhbGciOiJIUzI1NiJ9..."

sessionToken

string

required

Temporary credential authorizing one successful PIN submission. It is already included in iframeUrl; use that URL to load the form. Never store, cache, or log the token. Use the iframe's submission result to confirm a change; status OK alone cannot prove that an existing PIN was changed. Read GET /cards/{id} for its pinStatus.

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

expiresAt

string<date-time>

required

When the URL stops working. Request a new URL rather than reusing an expired URL or token.

Example:

"2026-05-08T14:16:00Z"

environment

enum<string>

required

Session environment. The iframeUrl already selects the matching environment.

Available options:

SANDBOX,

PRODUCTION

Example:

"SANDBOX"

Using the API

API documentation

Get a PIN-entry URL

Authorizations

Path Parameters

Response