> ## Documentation Index
> Fetch the complete documentation index at: https://laas.mippo.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: your first Pix to stablecoin transaction

> Set up API keys, submit KYC for a test client, and process your first Pix to stablecoin transaction with the Supercosmos for Platforms API in under 5 minutes.

## Prerequisites

* An approved Supercosmos for Platforms developer account ([apply here](https://partners.mippo.io/apply))
* A sandbox API key from your [developer dashboard](https://partners.mippo.io/partner/api-keys)

## 1. Install the SDK

```bash npm theme={null}
npm install @mippo/laas-sdk
```

```bash yarn theme={null}
yarn add @mippo/laas-sdk
```

```bash bun theme={null}
bun add @mippo/laas-sdk
```

## 2. Initialise the client

```typescript theme={null}
import { MippoLaas } from '@mippo/laas-sdk';

const mippo = new MippoLaas({
  apiKey: process.env.MIPPO_API_KEY,  // sk_test_... for sandbox
  environment: 'sandbox',
});
```

> [!WARNING]
>
> Never initialise the SDK client-side. Your API key must stay on your backend server.

## 3. Submit KYC

```typescript theme={null}
const client = await mippo.kyc.submit({
  cpf: '123.456.789-09',
  biometricHash: 'sha256:your_biometric_hash',
  personType: 'PF',
});

// client.token → pass to transactions
// client.riskTier → 'STANDARD' | 'HIGH' | 'PEP'
```

> [!NOTE]
>
> In sandbox, any valid CPF format passes KYC and returns `riskTier: 'STANDARD'`. To test the `HIGH` risk path, use CPF `000.000.001-91`.

## 4. Initiate a transaction

```typescript theme={null}
const tx = await mippo.transactions.initiate({
  kycToken: client.token,
  amountBrl: 500,
  asset: 'USDT',
  walletAddress: '0xYourUserWalletAddress',
});
```

## 5. Handle the auth challenge

Every transaction returns an auth challenge before a Pix QR code is issued.

> [tab] Standard Risk (TOTP MFA)
>
> ```typescript theme={null}
> if (tx.authChallenge?.type === 'MFA_TOTP') {
>   // Show your user a prompt to enter their TOTP code
>   const totpCode = await promptUserForTotp();
>
>   const confirmed = await mippo.transactions.confirmMfa({
>     transactionId: tx.transactionId,
>     totpCode,
>   });
>
>   // confirmed.pixPayload → render as QR code for the user
>   console.log(confirmed.pixPayload);
> }
> ```

> [tab] High Risk / PEP (Liveness)
>
> ```typescript theme={null}
> if (tx.authChallenge?.type === 'LIVENESS') {
>   // Redirect user to the liveness URL or embed it in a WebView
>   const livenessUrl = tx.authChallenge.livenessUrl;
>   window.location.href = livenessUrl;
>   // Supercosmos fires a webhook when liveness passes → pixPayload sent via webhook
> }
> ```

## 6. Listen for completion

After the user pays via Pix, Supercosmos fires a `transaction.completed` webhook to your endpoint. See the [Webhooks guide](https://laas.mippo.io/docs/guides/webhooks.md) for verification.

```typescript theme={null}
// transaction.completed payload
{
  "event": "transaction.completed",
  "data": {
    "transactionId": "tx_1719000000_xyz",
    "txHash": "0xabc123...",
    "asset": "USDT",
    "amount": "90.25",  // after Supercosmos fee
    "walletAddress": "0xYourUserWalletAddress"
  }
}
```

> [!TIP]
>
> That's it. The stablecoin is now in your user's wallet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.