A wallet PIN is a security credential used to authorize sensitive wallet operations.

The PIN provides an additional layer of protection by requiring the User to confirm certain actions before they can be completed.

A User must meet the applicable KYC requirements before setting up a wallet PIN. For example, Tier 1 KYC allows a User to create a wallet PIN.

Why a PIN is Required

A PIN helps protect a User's wallet from unauthorized transactions and other sensitive operations.

For operations that require PIN authorization, the User must provide the correct PIN before the transaction can proceed.

The PIN therefore acts as an authorization factor in addition to the authentication credentials used by the merchant's application when communicating with LedgerBlock.

Authentication vs PIN Authorization

These serve different purposes:

Security Layer	Purpose
API Authentication	Authenticates the merchant/application making the API request
Wallet PIN	Authorizes the User's wallet operation

Your backend authenticates with LedgerBlock, while the wallet PIN provides authorization for the User's applicable wallet action.

Setting Up a PIN

A User must first satisfy the required KYC level before a wallet PIN can be created.

The general setup flow is:

Create User
     ↓
Complete Required KYC
     ↓
KYC Approved
     ↓
Create Wallet
     ↓
Set Wallet PIN
     ↓
PIN Ready for Authorization

Once the User has met the applicable requirements, your application can initiate the PIN setup process using the relevant PIN API.

Set PIN API → Finalize PIN Creation

The exact request parameters and requirements are documented in the API Reference.

PIN Security

The wallet PIN should be treated as sensitive authentication information.

Your application should:

Never store the PIN in plaintext.
Never log the PIN.
Never include the PIN in application logs or analytics.
Never expose the PIN in URLs.
Transmit PIN-related requests only over HTTPS.
Avoid displaying the PIN after it has been submitted.
Apply appropriate access controls to systems handling PIN-related operations.

Authorizing Transactions With a PIN

Certain wallet operations require the User to authorize the action using their wallet PIN.

The general authorization flow is:

User Initiates Operation
        ↓
Operation Requires PIN
        ↓
User Provides PIN
        ↓
PIN Authorization
        ↓
Transaction Processed

The PIN should be collected securely by your application and supplied only to the LedgerBlock endpoint that requires PIN authorization.

Your application should not attempt to validate or compare the User's PIN locally.

For operations that require PIN authorization, refer to the corresponding API documentation.

Transaction Authorization API → Authorize PIN (Security for Payout)

Incorrect PIN

If a User provides an incorrect PIN, the operation should not be treated as authorized.

Your application should display an appropriate error message to the User and follow the response provided by LedgerBlock.

Do not repeatedly retry PIN authorization automatically.

Resetting a PIN

A User may need to reset their wallet PIN if they have forgotten it or if the PIN needs to be replaced.

PIN reset is a separate operation from setting the PIN for the first time.

PIN Reset Flow

User Requests PIN Reset
        ↓
Identity / Security Verification
        ↓
Reset PIN
        ↓
New PIN Set
        ↓
New PIN Used for Future Authorization

The reset process should only be initiated after the required verification or authorization conditions have been satisfied.

Use the Reset PIN API to initiate a PIN reset.

Reset PIN API → Reset PIN

The exact reset requirements, request parameters, and response structure are available in the API Reference.

PIN Lifecycle

The complete PIN lifecycle can be represented as:

       User Created
            ↓
       KYC Completed
            ↓
        Wallet Created
            ↓
        Set PIN
            ↓
    ┌───────┴────────┐
    ↓                ↓
Authorize        Forgot PIN
    ↓                ↓
Transaction       Reset PIN
                     ↓
                  New PIN
                     ↓
                Authorization

Important Considerations

A User must satisfy the applicable KYC requirement before setting up a PIN.
A wallet PIN is different from the merchant's API authentication credentials.
PINs must be handled as sensitive information.
Do not store or log plaintext PINs.
Use the relevant LedgerBlock APIs for PIN setup, authorization, and reset.
Always handle failed authorization responses appropriately.