Skip to main content
Card PINs are set — and changed — through Yativo’s hosted secure page, powered by the Gnosis Pay Partner Secure Elements (PSE) service. The cardholder types their PIN directly inside a sandboxed iframe. Your backend never receives or processes the PIN value.
First-time PIN setup and PIN changes use different response shapes.
  • First-time setup (pin_set: false): any call to view-token returns 422 PIN_NOT_SET. The response body includes data.pin_setup_url — open that URL for PIN setup. You do not need to pass enabled_views: ["pin"]; the API auto-selects the PIN-setup view.
  • PIN change (pin_set: true): call view-token with enabled_views: ["pin"]. You get 200 with data.secure_view_url — open that for PIN change.
pin_set is informational, not a hard gate. Yativo tracks pin_set from the physical.card.pin.changed webhook — Gnosis Pay does not expose this value via their API. The flag may lag behind reality if the webhook was missed or the cardholder set their PIN through another path. Use it as a UI hint (e.g. show a “Set PIN” prompt) rather than blocking access server-side.

​
How it works

​
First-time PIN setup (pin_set: false)

1

Call view-token (any enabled_views)

Call POST /v1/yativo-card/{yativoCardId}/cards/{cardId}/view-token. You do not need to pass enabled_views: ["pin"] — the API detects that the PIN is not set and overrides the view automatically.
2

You receive 422 PIN_NOT_SET with pin_setup_url

The API returns HTTP 422 with error_code: "PIN_NOT_SET". The response body includes data.pin_setup_url — a short-lived URL pre-configured for PIN setup.
3

Open pin_setup_url in an iframe or WebView

Pass data.pin_setup_url to your frontend. The cardholder enters and confirms their 4-digit PIN directly in the hosted page. The PIN never leaves the iframe.
4

Gnosis Pay fires a webhook

Once saved, Gnosis Pay sends a physical.card.pin.changed event. Yativo updates pin_set: true on the card record automatically.

​
PIN change (pin_set: true)

1

Call view-token with enabled_views: ["pin"]

Call POST /v1/yativo-card/{yativoCardId}/cards/{cardId}/view-token with enabled_views: ["pin"].
2

You receive 200 with secure_view_url

The API returns HTTP 200 with data.secure_view_url — open that in an iframe or WebView for the PIN change form.

​
Step 1 — Request a PIN view token

POST /v1/yativo-card/{yativoCardId}/cards/{cardId}/view-token
​
yativoCardId
string
required
The Yativo Card account ID (yativo_card_id).
​
cardId
string
required
The card ID to set the PIN for.
​
enabled_views
array
required
Pass ["pin"] to open the PIN-setting form. Pass ["data", "pin"] to show both card details and PIN (only works after PIN is already set).
​
theme
object
Optional brand customization — accent_color, logo_url, background_color, etc. See Secure Card Display for all options.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yativo_card_0xAbCd1234_1769031332068/cards/afeb85fe-02f8-48da-b61e-84ad02704167/view-token' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled_views": ["pin"],
    "theme": {
      "accent_color": "#6366f1",
      "logo_url": "https://yourapp.com/logo.png"
    }
  }'

{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "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": "physical",
    "holder_name": "Jane Doe",
    "pin_set": false,
    "enabled_views": ["pin"],
    "requires_access_code": false
  }
}

​
Step 2 — Embed the hosted PIN page

Pass secure_view_url 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 dimensions for PIN-only view: 420 × 520px. For combined card details + PIN view: 420 × 740px.

​
Theme customization

Pass a theme object in the view-token request to brand the hosted PIN page. All theme fields are optional. 
curl -X POST '.../view-token' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled_views": ["pin"],
    "theme": {
      "accent_color": "#6366f1",
      "background_color": "#f5f1ea",
      "logo_url": "https://yourapp.com/logo.png",
      "border_radius": 16,
      "font_family": "Inter, sans-serif"
    }
  }'
Theme fields: accent_color, background_color, panel_color, text_color, muted_color, border_radius, font_family, logo_url. See Secure Card Display for the full reference.

​
Checking pin_set status

After the PIN is set, the Gnosis Pay physical.card.pin.changed webhook fires and Yativo updates pin_set: true on the card record. You can read this via:
  • Card issuers — GET /v1/card-issuer/customers/{customerId} → data.cards[n].pin_set
  • End users — GET /v1/yativo-card/my-account → data.account.cards[n].pin_set
  • View-token response — data.pin_set is returned on every POST .../view-token call
The next_action field on the issuer customer record will read:
"Card is active — customer must set card PIN before in-store (PSE) payments will work"
until pin_set becomes true.
pin_set reflects the last known state from the webhook. Gnosis Pay does not expose this flag via their partner API, so if the webhook was missed or the PIN was set through another path, the value may be stale. Treat it as a UI hint — not an authoritative server-side gate.

​
Notes

DetailValue
PIN inputCardholder types directly into the hosted iframe — PIN never reaches your server
PIN format4 digits (0000–9999)
Initial set & changeSame enabled_views: ["pin"] view handles both
Confirmationphysical.card.pin.changed webhook → pin_set: true in DB
pin_set reliabilityInformational — sourced from webhook only, not Gnosis API
Issuer themePass theme in the view-token request — applies to the hosted PIN page
Online vs chip PINPSE updates the online PIN. The chip PIN syncs automatically on first ATM use
Works forVirtual and physical cards