Skip to main content
POST
/
v1
/
card
/
pin
/
token
{
  "token": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
  "imageUrl": "https://cards.baanx.com/details-image?token=100a99cf-f4d3-4fa1-9be9-2e9828b20ebb"
}

​
Overview

Generates a time-limited secure token that allows users to view their card PIN as a secure image. The PIN is never transmitted to or stored by your application, ensuring security and compliance.
PCI ComplianceThis endpoint maintains PCI compliance by delivering PIN data as a secure image. Your application never handles the actual PIN value.

​
Authentication

This endpoint requires authentication via Bearer token: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Request

​
Headers

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

​
Body

The request body is optional. If omitted, default styling will be applied to the PIN image.
​
customCss
object
Customize the visual appearance of the PIN image

​
Request Example

curl -X POST https://dev.api.baanx.com/v1/card/pin/token \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customCss": {
      "backgroundColor": "#EFEFEF",
      "textColor": "#000000"
    }
  }'

​
Response

​
Success Response

​
token
string
Secure, time-limited token (UUID format)Lifetime: ~10 minutesUsage: Single-use token that becomes invalid after the image is accessed
​
imageUrl
string
URL that renders PIN as a secure imageUsage: Display PIN by using this URL as the src attribute of an <img> tagFormat: <HOST>/details-image?token={token}Security: Treat this URL as highly sensitive. Do not log or store it.
{
  "token": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
  "imageUrl": "https://cards.baanx.com/details-image?token=100a99cf-f4d3-4fa1-9be9-2e9828b20ebb"
}

​
Error Responses

{
  "message": "Not authenticated"
}

​
Integration Method

Display PIN as a secure image without interactive elements.

​
Basic Implementation

const { imageUrl } = await generatePinToken({
  customCss: {
    backgroundColor: '#EFEFEF',
    textColor: '#000000'
  }
});

const img = document.createElement('img');
img.src = imageUrl;
img.alt = 'Card PIN';
img.style.maxWidth = '100%';
img.style.borderRadius = '8px';

document.getElementById('pin-image-container').appendChild(img);

​
React Component Example

import { useState } from 'react';

export function PinImageViewer() {
  const [imageUrl, setImageUrl] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleViewPin = async () => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch('https://dev.api.baanx.com/v1/card/pin/token', {
        method: 'POST',
        headers: {
          'x-client-key': 'YOUR_CLIENT_KEY',
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          customCss: {
            backgroundColor: '#EFEFEF',
            textColor: '#000000'
          }
        })
      });

      if (!response.ok) {
        throw new Error('Failed to generate PIN token');
      }

      const data = await response.json();
      setImageUrl(data.imageUrl);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'An error occurred');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handleViewPin} disabled={loading}>
        {loading ? 'Loading...' : 'View PIN'}
      </button>

      {error && <div className="error">{error}</div>}

      {imageUrl && (
        <div className="pin-image-container">
          <img
            src={imageUrl}
            alt="Card PIN"
            style={{ maxWidth: '100%', borderRadius: '8px' }}
          />
          <button onClick={() => setImageUrl(null)}>Close</button>
        </div>
      )}
    </div>
  );
}
Security NoteImage URLs contain sensitive PIN information. Always:
  • Use HTTPS only
  • Never log or store the imageUrl
  • Display in secure contexts only
  • Clear the image from DOM when user is done viewing

​
Customization Examples

​
Dark Theme

{
  "customCss": {
    "backgroundColor": "#1F2937",
    "textColor": "#F9FAFB"
  }
}

​
Light Theme

{
  "customCss": {
    "backgroundColor": "#FFFFFF",
    "textColor": "#111827"
  }
}

​
Brand Colors

{
  "customCss": {
    "backgroundColor": "#F0F9FF",
    "textColor": "#0C4A6E"
  }
}

​
Security Best Practices

Token Security
  • Tokens expire after ~10 minutes
  • Single-use tokens become invalid after first access
  • Generate new tokens for each PIN view request
  • Never store, cache, or log tokens
PCI ComplianceUsing this endpoint ensures PCI compliance as PIN data is delivered as a secure image. Your application never handles the actual PIN value.
URL HandlingTreat imageUrl as highly sensitive. Use HTTPS only, never log these URLs, and display only in authenticated, secure contexts.

​
Best Practices

​
Error Handling

async function showPIN() {
  try {
    const { imageUrl } = await generatePinToken({
      customCss: {
        backgroundColor: '#EFEFEF',
        textColor: '#000000'
      }
    });

    const img = document.createElement('img');
    img.src = imageUrl;
    img.alt = 'Card PIN';
    img.style.maxWidth = '100%';
    document.getElementById('pin-container').appendChild(img);

  } catch (error) {
    if (error.response?.status === 404) {
      alert('No card found. Please order a card first.');
    } else if (error.response?.status === 401) {
      alert('Session expired. Please log in again.');
    } else if (error.response?.status === 422) {
      alert('Invalid styling parameters. Please check your customCss values.');
    } else {
      alert('Failed to load PIN. Please try again.');
    }
  }
}

​
Cleanup After Viewing

function createPINViewer() {
  let currentImage: HTMLImageElement | null = null;

  async function showPIN() {
    const { imageUrl } = await generatePinToken();

    currentImage = document.createElement('img');
    currentImage.src = imageUrl;
    currentImage.alt = 'Card PIN';
    document.getElementById('pin-container').appendChild(currentImage);
  }

  function hidePIN() {
    if (currentImage) {
      currentImage.remove();
      currentImage = null;
    }
  }

  return { showPIN, hidePIN };
}

const pinViewer = createPINViewer();
  • POST /v1/card/set-pin/token - Generate token to set or change card PIN
  • POST /v1/card/details/token - Generate token to view card details
  • GET /v1/card/status - Check card status before viewing PIN