PIN Management

PINs are numeric codes used at POS and for certain sensitive operations. Migo stores them irreversibly — not even Migo can reveal an existing PIN; PINs can only be set/changed, never read.

Change a PIN

The PIN endpoint accepts only the new PIN value (CardPinDto). For sensitive operations the cardholder first proves ownership via OTP to obtain an elevated session, then sets the PIN:

# 1. Request an OTP
POST /users/auth/otp
{ "email": "user@example.com", "purpose": "pin_change" }

# 2. Verify the OTP (returns an elevated session)
PUT /users/auth/otp
{ "email": "user@example.com", "otp": "987654", "purpose": "pin_change" }

# 3. Set the new PIN
POST /cards/{cardId}/pin
Authorization: Bearer <elevated-token>
{ "pin": "5678" }

See Authentication → OTP for the full OTP elevation flow.

note

The POST /cards/{cardId}/pin endpoint itself accepts any valid session and only validates the pin field. The OTP elevation above is enforced by the wallet app's authentication flow, not by the PIN endpoint.

Admin PIN change (shared-card scenarios)

When a card has multiple users (e.g. a family shared card), an admin can set a per-user PIN. The body is the same { pin }:

POST /cards/{cardId}/users/{authUserId}/pin
Authorization: Bearer <admin-token>
{ "pin": "4321" }

The admin PIN overrides the previous PIN for that user only. Other users of the same card retain their own PIN.

PIN reset (forgotten PIN)

Treat a forgotten PIN as a change-PIN flow starting from OTP:

1. Cardholder confirms identity via OTP (POST then PUT /users/auth/otp).
2. POST /cards/{cardId}/pin sets a new PIN with { pin }.

There is no endpoint to reveal an existing PIN — by design.

Errors

PIN operations surface errors from the Cards range (7200–7299). For example:

Code	Name	Meaning
7205	INCORRECT_PIN	Wrong PIN entered
7210	CARD_NOT_UPDATED	The card (incl. PIN) could not be updated
7213	INVALID_STATUS_CARD	Card is in a state that does not allow the operation

See the full Error Catalog for the complete list.