Setting a Card PIN

curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/customers/yativo_card_customer_8f9a..._1769031332068/cards/afeb85fe-02f8-48da-b61e-84ad02704167/view-token' \
  -H 'Authorization: Bearer YOUR_ISSUER_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled_views": ["pin-set"],
    "theme": {
      "accent_color": "#6366f1",
      "background_color": "#f5f5f5",
      "logo_url": "https://yourapp.com/logo.png",
      "border_radius": 16
    }
  }'

const response = await fetch(
  `https://crypto-api.yativo.com/api/v1/yativo-card/customers/${yativoCardId}/cards/${cardId}/view-token`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${issuerAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      enabled_views: ['pin-set'],
      theme: {
        accent_color: '#6366f1',
        logo_url: 'https://yourapp.com/logo.png',
      },
    }),
  }
);

const { data } = await response.json();
// Pass data.secure_view_url to your frontend

{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "expires_at": "2026-05-18T12:05:00.000Z",
    "last_four": "4291",
    "card_type": "virtual",
    "holder_name": "Jane Doe",
    "pin_set": false,
    "enabled_views": ["pin-set"],
    "requires_access_code": false
  }
}

{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "expires_at": "2026-05-18T12:05:00.000Z",
    "last_four": "4291",
    "card_type": "virtual",
    "holder_name": "Jane Doe",
    "pin_set": true,
    "enabled_views": ["pin-set"],
    "requires_access_code": false
  }
}

Every card — virtual and physical — starts with pin_set: false. Cardholders must set their PIN before card details (card number, CVV) can be viewed, and before chip-and-PIN or ATM transactions will work. To let a cardholder set their PIN, call the view-token endpoint with enabled_views: ["pin-set"]. The API always returns 200 OK with a secure_view_url for PIN setup — regardless of whether pin_set is true or false. Open that URL in an iframe or WebView and the cardholder can set (or change) their PIN directly.

The 422 PIN_NOT_SET error only occurs when you request card data or PIN reveal (enabled_views: ["data"], ["pin-view"]) while pin_set is still false. It does not occur when requesting ["pin-set"] to set the PIN.

Card PINs are set and changed through Yativo’s hosted secure page, powered by the card network’s Partner Secure Elements (PSE) service. The cardholder types their PIN directly inside a sandboxed iframe hosted by Yativo. The PIN never passes through your backend.

How it works

Your backend requests a PIN view token

Call POST /v1/yativo-card/customers/{yativoCardId}/cards/{cardId}/view-token with enabled_views: ["pin-set"] for initial setup or PIN change, or ["pin-view"] to reveal the current PIN. Pass your brand theme to customise the page.

You receive a secure_view_url

The API returns 200 OK with a short-lived secure_view_url and the current pin_set status. This always succeeds for ["pin-set"] requests — even when pin_set is false.

Show the hosted page to the cardholder

Open the URL in an <iframe>, mobile WebView, or a new browser tab in your app. The cardholder enters and confirms their 4-digit PIN inside the hosted page.

Card network confirms via webhook

Once saved, the card network fires physical.card.pin.changed. Yativo receives it and flips pin_set to true on the card record.

The same flow handles both initial PIN setup and PIN changes — use enabled_views: ["pin-set"] in both cases.

Request a PIN view token

Call this from your backend using your issuer access token.

POST /v1/yativo-card/customers/{yativoCardId}/cards/{cardId}/view-token

yativoCardId

string

required

The customer’s yativo_card_id.

cardId

string

required

The card ID — works for both virtual and physical cards.

enabled_views

array

required

Controls which tabs appear on the hosted page. Accepted values:

Value	Tab shown
`"pin-set"`	Set or change PIN
`"pin-view"`	Reveal current PIN (requires `pin_set: true`)
`"data"`	Card number, CVV, expiry (requires `pin_set: true`)

Pass ["pin-set"] for initial setup or PIN change. Pass ["data", "pin-view", "pin-set"] to show all three tabs at once. The legacy value "pin" is accepted as an alias for "pin-set".

theme

object

Brand the hosted page with your colours and logo. All fields optional.

Field	Type	Description
`accent_color`	string	Hex colour for buttons and highlights
`background_color`	string	Page background
`panel_color`	string	Card panel background
`text_color`	string	Primary text
`logo_url`	string	Your logo at the top of the page
`border_radius`	number	Corner radius in px (8–36)
`font_family`	string	CSS font-family string

curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/customers/yativo_card_customer_8f9a..._1769031332068/cards/afeb85fe-02f8-48da-b61e-84ad02704167/view-token' \
  -H 'Authorization: Bearer YOUR_ISSUER_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled_views": ["pin-set"],
    "theme": {
      "accent_color": "#6366f1",
      "background_color": "#f5f5f5",
      "logo_url": "https://yourapp.com/logo.png",
      "border_radius": 16
    }
  }'

const response = await fetch(
  `https://crypto-api.yativo.com/api/v1/yativo-card/customers/${yativoCardId}/cards/${cardId}/view-token`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${issuerAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      enabled_views: ['pin-set'],
      theme: {
        accent_color: '#6366f1',
        logo_url: 'https://yourapp.com/logo.png',
      },
    }),
  }
);

const { data } = await response.json();
// Pass data.secure_view_url to your frontend

{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "expires_at": "2026-05-18T12:05:00.000Z",
    "last_four": "4291",
    "card_type": "virtual",
    "holder_name": "Jane Doe",
    "pin_set": false,
    "enabled_views": ["pin-set"],
    "requires_access_code": false
  }
}

{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "expires_at": "2026-05-18T12:05:00.000Z",
    "last_four": "4291",
    "card_type": "virtual",
    "holder_name": "Jane Doe",
    "pin_set": true,
    "enabled_views": ["pin-set"],
    "requires_access_code": false
  }
}

Embed the hosted PIN page

Pass secure_view_url directly as the src of an iframe. No SDK or client-side JavaScript required.

<iframe
  src="https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci..."
  title="Set Card PIN"
  width="420"
  height="520"
  style="border: 0; border-radius: 16px;"
  allow="clipboard-read; clipboard-write"
></iframe>

Recommended iframe dimensions: 420 × 520px for PIN-only. Use 420 × 740px if showing card details and PIN together.

Checking PIN status

pin_set is updated when Yativo receives the physical.card.pin.changed webhook from the card network. It is not sourced from a direct API lookup — treat it as the last known state. You can read it from: Per-card, in GET /v1/card-issuer/customers/{customerId}:

{
  "card_id": "afeb85fe-02f8-48da-b61e-84ad02704167",
  "card_type": "virtual",
  "status": "active",
  "pin_set": false
}

Per-customer top-level (true only when every card has a PIN):

{
  "cards_count": 2,
  "pin_set": false,
  "next_action": "Card is active — customer must set card PIN before in-store (PSE) payments will work"
}

On the view-token response — data.pin_set is returned every time you call the view-token endpoint. To list all customers who still need to set a PIN:

GET /v1/card-issuer/customers?status=card_created

Then filter the results by pin_set: false.

pin_set reflects the last state received via webhook and may lag if a webhook was delayed. If a cardholder reports unexpected PIN_NOT_SET errors after completing PIN setup, they can retry — the server will re-evaluate when the webhook catches up.

Webhook confirmation

Subscribe to physical.card.pin.changed on your webhook endpoint. Yativo updates pin_set: true automatically when this event arrives — no polling needed.

Payload example

{
  "event": "physical.card.pin.changed",
  "data": {
    "cardToken": "afeb85fe-02f8-48da-b61e-84ad02704167",
    "yativo_card_id": "yativo_card_customer_8f9a..._1769031332068"
  }
}

Notes

Detail	Value
Works for	Virtual and physical cards
PIN format	Exactly 4 digits (`0000`–`9999`)
Initial setup & change	Same `enabled_views: ["pin-set"]` flow for both
PIN never touches your server	Entered directly in the Yativo-hosted iframe
Brand customisation	Pass `theme` in the token request — applies to the hosted PIN page
Confirmation	`physical.card.pin.changed` webhook → `pin_set: true`
`pin_set` source	Webhook only — not from a direct card network API lookup
Online vs chip PIN	PSE updates the online PIN. The chip syncs on first ATM use (physical cards)

Card Issuer Program Payment Gateway

Overview

Wallets & Assets

Transactions

Yativo Card

Payment Gateway

Agentic Wallets

IBAN

Automation

Compliance

B2B

Developer Tools

Tutorials

SDKs

Browser Extensions (Coming Soon)

Sandbox

Setting a Card PIN

How it works

Request a PIN view token

Embed the hosted PIN page

Checking PIN status

Webhook confirmation

Notes

​How it works

​Request a PIN view token

​Embed the hosted PIN page

​Checking PIN status

​Webhook confirmation

​Notes

How it works

Request a PIN view token

Embed the hosted PIN page

Checking PIN status

Webhook confirmation

Notes