Skip to main content
POST
Generate PIN Set Token

Overview

Generates a time-limited secure token that allows users to set or change their card PIN through a PCI-compliant hosted interface. The hosted page includes built-in validation and confirmation flows to ensure the PIN is set correctly and securely.
PCI ComplianceThis endpoint maintains PCI compliance by handling PIN creation entirely within secure hosted environments. Your application never handles or stores PIN values.

Authentication

This endpoint requires authentication via Bearer token:

Request

Headers

string
required
Your public API client key
boolean
default:false
Set to true to route requests to the US backend environment
string
required
Bearer token for authentication

Body

string
URL to redirect to after the user completes or cancels PIN setupOnly used when isEmbedded=falseExample: https://yourapp.com/dashboard
boolean
default:false
Controls the completion/dismissal behavior:
  • false - Redirects to redirectUrl when user completes or cancels
  • true - Fires a postMessage event with type abort for iframe integration
object
Customize the visual appearance of the hosted PIN setup page

Request Example

Response

Success Response

string
Secure, time-limited token (UUID format)Lifetime: ~10 minutesUsage: Single-use token that becomes invalid after access
string
Full URL to the hosted PIN setup pageUsage: Redirect users or embed in iframeFormat: <HOST>/pin-direct/set?token={token}

Error Responses

Hosted Page Features

The hosted PIN setup page includes:

PIN Entry

Secure input fields for entering 4-digit PIN

Confirmation

Two-step entry to prevent typos

Validation

Real-time validation of PIN format and strength

Masked Input

PIN digits are masked for privacy during entry

Integration Methods

Redirect the user to set their PIN on a dedicated page.
User Flow:
  1. User redirected to hosted page
  2. Enters new PIN twice for confirmation
  3. Submits PIN
  4. Redirected to redirectUrl on success

Use Case Examples

First-Time PIN Setup

Change Existing PIN

Customization Examples

Modern Dark Theme

Light Theme

Brand Colors

PIN Requirements

Standard PIN Format
  • Must be exactly 4 digits
  • Only numeric characters (0-9)
  • No letters or special characters
  • Cannot be all the same digit (e.g., 1111, 2222)
The hosted page enforces these requirements automatically with real-time validation.

Security Best Practices

Token Security
  • Tokens expire after ~10 minutes
  • Single-use tokens become invalid after first access
  • Generate new tokens for each PIN setup attempt
  • Never store, cache, or log tokens
PCI ComplianceUsing this endpoint ensures PCI compliance as PIN data is created and stored entirely within secure, PCI-compliant systems. Your application never handles PIN values.
Secure CommunicationAll communication with the hosted page occurs over HTTPS with strong encryption. The PIN is never exposed in logs, analytics, or network traffic accessible to your application.

Common Use Cases

Onboarding Flow

Security Settings

Error Handling

  • POST /v1/card/pin/token - Generate token to view current PIN
  • POST /v1/card/details/token - Generate token to view card details
  • GET /v1/card/status - Check card status before PIN setup
  • POST /v1/card/order - Order a new card