### Install pix-utils Package

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Installs the pix-utils package using Yarn. This is the first step to integrate Pix functionalities into your project.

```sh
yarn add pix-utils
```

--------------------------------

### Generate and Verify Pix Payments with TypeScript

Source: https://context7.com/thalesog/pix-utils/llms.txt

This TypeScript example illustrates a complete Pix payment flow. It shows how to generate static and dynamic Pix QR codes for e-commerce checkouts, and how to parse and verify these codes. It utilizes functions like createStaticPix, createDynamicPix, parsePix, and verification helpers from the pix-utils library.

```typescript
import {
  createStaticPix,
  createDynamicPix,
  parsePix,
  hasError,
  isStaticPix,
  isDynamicPix
} from 'pix-utils';

// E-commerce checkout flow
class PixPaymentService {
  async generatePaymentQRCode(orderId: string, amount: number, customerEmail: string) {
    // Create static Pix for immediate payment
    const pix = createStaticPix({
      merchantName: 'My Online Store',
      merchantCity: 'Sao Paulo',
      pixKey: 'payments@mystore.com',
      transactionAmount: amount,
      infoAdicional: `Order ${orderId}`,
      txid: orderId.substring(0, 25),
    }).throwIfError();

    const brCode = pix.toBRCode();
    const qrCodeImage = await pix.toImage();

    return {
      brCode,
      qrCodeImage,
      merchantName: pix.merchantName,
      amount: pix.transactionAmount,
    };
  }

  async generateDynamicPayment(orderId: string) {
    // Create dynamic Pix where amount can change until payment
    const pix = createDynamicPix({
      merchantName: 'My Online Store',
      merchantCity: 'Sao Paulo',
      url: `payments.mystore.com/api/pix/${orderId}`,
      oneTime: true,
    }).throwIfError();

    return {
      brCode: pix.toBRCode(),
      qrCodeImage: await pix.toImage(),
      paymentUrl: pix.url,
    };
  }

  async verifyPayment(brCode: string) {
    const pix = parsePix(brCode);

    if (hasError(pix)) {
      throw new Error(`Invalid BR Code: ${pix.message}`);
    }

    if (isStaticPix(pix)) {
      return {
        type: 'static',
        pixKey: pix.pixKey,
        amount: pix.transactionAmount,
        merchantName: pix.merchantName,
        txid: pix.txid,
        info: pix.infoAdicional,
      };
    }

    if (isDynamicPix(pix)) {
      // Fetch actual payment data from PSP
      const paymentData = await pix.fetchPayload({
        DPP: new Date().toISOString().substring(0, 10),
        codMun: 5300108,
      });

      if (hasError(paymentData)) {
        throw new Error(`Failed to fetch payment: ${paymentData.message}`);
      }

      return {
        type: 'dynamic',
        url: pix.url,
        amount: paymentData.payload.valor.original,
        pixKey: paymentData.payload.chave,
        txid: paymentData.payload.txid,
        status: paymentData.payload.status,
        expiresIn: paymentData.payload.calendario.expiracao,
      };
    }

    throw new Error('Unsupported Pix type');
  }
}

// Usage
const service = new PixPaymentService();

// Generate payment for checkout
const payment = await service.generatePaymentQRCode('ORDER-12345', 299.90, 'customer@email.com');
console.log('Show QR Code to customer:', payment.qrCodeImage);
console.log('Or copy BR Code:', payment.brCode);

// Later, verify the payment code
const verification = await service.verifyPayment(payment.brCode);
console.log('Payment verified:', verification);

// Generate dynamic payment
const dynamicPayment = await service.generateDynamicPayment('ORDER-67890');
console.log('Dynamic QR Code:', dynamicPayment.qrCodeImage);

```

--------------------------------

### Parse Pix BR Code (TypeScript)

Source: https://context7.com/thalesog/pix-utils/llms.txt

Parses an existing Pix BR Code string to extract all payment information. The `parsePix` function returns typed objects (PixStaticObject, PixDynamicObject, or PixRecurrenceObject) with payment details and utility methods. It includes type checking and examples for regenerating the BR Code.

```typescript
import { parsePix, hasError, isStaticPix, isDynamicPix, isRecurrencePix } from 'pix-utils';

const brCode = '00020126650014br.gov.bcb.pix0119nubank@thalesog.com0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6009Sao Paulo62070503***6304059A';

const pix = parsePix(brCode);

if (!hasError(pix)) {
  // Type checking and narrowing
  if (isStaticPix(pix)) {
    console.log('Static Pix Details:', {
      type: pix.type, // 'STATIC'
      merchantName: pix.merchantName,
      merchantCity: pix.merchantCity,
      pixKey: pix.pixKey,
      amount: pix.transactionAmount,
      additionalInfo: pix.infoAdicional,
      txid: pix.txid,
      categoryCode: pix.merchantCategoryCode,
      currency: pix.transactionCurrency, // '986' (BRL)
      country: pix.countryCode, // 'BR'
    });

    // Generate QR code from parsed data
    const qrCode = await pix.toImage();
    console.log('Regenerated QR Code:', qrCode.substring(0, 50) + '...');
  }

  if (isDynamicPix(pix)) {
    console.log('Dynamic Pix Details:', {
      type: pix.type, // 'DYNAMIC'
      url: pix.url,
      merchantName: pix.merchantName,
      merchantCity: pix.merchantCity,
    });

    // Fetch dynamic payment information
    const data = await pix.fetchPayload({
      DPP: new Date().toISOString().substring(0, 10),
      codMun: 5300108,
    });

    if (!hasError(data)) {
      console.log('Fetched payment value:', data.payload.valor.original);
    }
  }

  if (isRecurrencePix(pix)) {
    console.log('Recurrence Pix Details:', {
      type: pix.type, // 'RECURRENCE'
      recurrenceUrl: pix.urlRec,
      merchantName: pix.merchantName,
    });
  }

  // Regenerate BR Code from parsed data
  const regeneratedBrCode = pix.toBRCode();
  console.log('Original matches regenerated:', brCode === regeneratedBrCode);
} else {
  console.error('Parse error:', pix.message);
  // Possible errors: 'invalid emv code', 'invalid crc', 'invalid pix'
}
```

--------------------------------

### Create Static Pix Payment

Source: https://context7.com/thalesog/pix-utils/llms.txt

Generates a static Pix payment object with a fixed amount and Pix key. It provides methods to create the BR Code string and a QR code image. This function handles input normalization and CRC-16 validation. An optional transaction ID can be provided for unique transactions.

```typescript
import { createStaticPix, hasError } from 'pix-utils';

const pix = createStaticPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  pixKey: 'nubank@thalesog.com',
  infoAdicional: 'Order #12345',
  transactionAmount: 150.50,
  txid: 'ORDER12345', // Optional, max 25 chars
  isTransactionUnique: false,
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  console.log('BR Code:', brCode);

  const qrCodeBase64 = await pix.toImage();
  console.log('QR Code:', qrCodeBase64.substring(0, 50) + '...');
} else {
  console.error('Error:', pix.message);
}

// Create a static Pix without fixed amount (user defines amount at payment)
const flexiblePix = createStaticPix({
  merchantName: 'Coffee Shop',
  merchantCity: 'Rio de Janeiro',
  pixKey: 'coffee@shop.com',
  transactionAmount: 0, // No fixed amount
});

if (!hasError(flexiblePix)) {
  console.log('Flexible BR Code:', flexiblePix.toBRCode());
}
```

--------------------------------

### Synchronous Error Handling with throwIfError (TypeScript)

Source: https://context7.com/thalesog/pix-utils/llms.txt

Illustrates using the throwIfError method for concise, synchronous error handling with Pix objects. This approach throws an exception if an error occurs, simplifying code flow compared to checking hasError manually.

```typescript
import { createStaticPix, createDynamicPix, parsePix } from 'pix-utils';

// Approach 1: Using hasError (returns PixError)
try {
  const pix1 = createStaticPix({
    merchantName: 'X'.repeat(30), // Invalid: too long
    merchantCity: 'City',
    pixKey: 'key@email.com',
    transactionAmount: 100,
  });

  // Need to check with hasError
  if (hasError(pix1)) {
    throw new Error(pix1.message);
  }

  console.log(pix1.toBRCode());
} catch (error) {
  console.error('Approach 1 error:', error.message);
}

// Approach 2: Using throwIfError (throws exception)
try {
  const pix2 = createStaticPix({
    merchantName: 'X'.repeat(30), // Invalid: too long
    merchantCity: 'City',
    pixKey: 'key@email.com',
    transactionAmount: 100,
  }).throwIfError(); // Throws if error occurred

  // No need to check hasError - exception is thrown automatically
  console.log(pix2.toBRCode());
} catch (error) {
  console.error('Approach 2 error:', error.message);
}

// Approach 2 is cleaner for synchronous flows
function generatePixCode(name: string, city: string, key: string, amount: number): string {
  return createStaticPix({
    merchantName: name,
    merchantCity: city,
    pixKey: key,
    transactionAmount: amount,
  }).throwIfError().toBRCode(); // Chain calls safely
}

try {
  const brCode = generatePixCode('Store', 'Sao Paulo', 'store@pix.com', 50);
  console.log('Generated:', brCode);
} catch (error) {
  console.error('Generation failed:', error.message);
}

// Works with all Pix types
const dynamicPix = createDynamicPix({
  merchantName: 'Service',
  merchantCity: 'Rio',
  url: 'pix.service.com/payment/123',
}).throwIfError();

const parsedPix = parsePix('00020126...').throwIfError();

```

--------------------------------

### Create Dynamic Pix Payment

Source: https://context7.com/thalesog/pix-utils/llms.txt

Creates a dynamic Pix payment object by fetching payment details from a specified URL. This is suitable for variable amounts and situations where payment information is managed externally by a PSP. It supports single-use QR codes and recurrence URLs. The function can also fetch payment data and recurrence details from the PSP endpoint.

```typescript
import { createDynamicPix, hasError } from 'pix-utils';

const pix = createDynamicPix({
  merchantName: 'Online Store',
  merchantCity: 'Brasilia',
  url: 'pix.mystore.com/payment/abc123def456',
  oneTime: true, // Optional: single-use QR code
  urlRec: 'pix.mystore.com/rec/subscription789', // Optional: recurrence URL
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  console.log('Dynamic BR Code:', brCode);

  // Fetch the actual payment data from the PSP
  const paymentData = await pix.fetchPayload({
    DPP: '2025-12-20', // Payment presentation date
    codMun: 5300108, // Municipality code (default: Brasilia)
  });

  if (!hasError(paymentData)) {
    console.log('Payment Info:', {
      amount: paymentData.payload.valor.original,
      txid: paymentData.payload.txid,
      status: paymentData.payload.status,
      pixKey: paymentData.payload.chave,
    });
    console.log('JWS Header:', paymentData.header);
    console.log('JWS String:', paymentData.jwsString);
  }

  // Fetch recurrence payment data if configured
  if (pix.fetchRecPayload) {
    const recData = await pix.fetchRecPayload();
    if (!hasError(recData)) {
      console.log('Recurrence ID:', recData.payload.idRec);
      console.log('Periodicity:', recData.payload.calendario.periodicidade);
    }
  }
} else {
  console.error('Creation error:', pix.message);
}
```

--------------------------------

### Create Static Pix Code (TypeScript)

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Generates a static Pix code using the `createStaticPix` function. Requires merchant details, Pix key, and transaction amount. The generated Pix object can then be converted to a BR Code string.

```ts
import { createStaticPix, hasError } from 'pix-utils';

const pix = createStaticPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  pixKey: 'nubank@thalesog.com',
  infoAdicional: 'Gerado por Pix-Utils',
  transactionAmount: 1,
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  // 00020126650014br.gov.bcb.pix0119nubank@thalesog.com0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6009Sao Paulo62070503***63046069
}
```

--------------------------------

### Create Recurring Pix Payment (TypeScript)

Source: https://context7.com/thalesog/pix-utils/llms.txt

Generates a Pix payment specifically for recurring transactions. It utilizes the `createRecurrencePix` function from the 'pix-utils' library and returns a BR Code. It also demonstrates fetching recurrence details asynchronously.

```typescript
import { createRecurrencePix, hasError } from 'pix-utils';

const pix = createRecurrencePix({
  merchantName: 'Streaming Service',
  merchantCity: 'Sao Paulo',
  urlRec: 'payments.streamingservice.com/rec/user12345monthly',
  oneTime: false,
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  console.log('Recurrence BR Code:', brCode);

  // Fetch recurrence details
  const recData = await pix.fetchRecPayload();

  if (!hasError(recData)) {
    const payload = recData.payload;
    console.log('Recurrence Details:', {
      id: payload.idRec,
      debtor: payload.vinculo.devedor,
      contract: payload.vinculo.contrato,
      startDate: payload.calendario.dataInicial,
      endDate: payload.calendario.dataFinal,
      frequency: payload.calendario.periodicidade,
      value: payload.valor?.valorRec,
      receiver: payload.recebedor.nome,
      retryPolicy: payload.politicaRetentativa,
      status: payload.atualizacao[0].status,
    });
  }
}
```

--------------------------------

### Enable Error Throwing for Pix Creation (JavaScript)

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Configures the Pix object to throw errors if any issues are detected during creation or processing, using the `throwIfError` method. This enhances robustness by immediately signaling problems.

```js
import { createDynamicPix } from 'pix-utils';

const pix = createDynamicPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  url: 'https://pix.thalesogliari.com.br',
}).throwIfError();

const brCode = pix.toBRCode();
// 00020126540014br.gov.bcb.pix2532https://pix.thalesogliari.com.br5204000053039865802BR5914Thales Ogliari6009SAO PAULO62070503***63043FD3
```

--------------------------------

### Create Dynamic Pix Code (TypeScript)

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Generates a dynamic Pix code using the `createDynamicPix` function. This method is suitable for scenarios where a direct Pix key is not used, often involving a URL for payment processing. The generated Pix object can be converted to a BR Code string.

```ts
import { createDynamicPix, hasError } from 'pix-utils';

const pix = createDynamicPix({
  merchantName: 'Thales Ogliari',
  merchantCity: 'Sao Paulo',
  url: 'https://pix.thalesogliari.com.br',
});

if (!hasError(pix)) {
  const brCode = pix.toBRCode();
  // 00020126540014br.gov.bcb.pix2532https://pix.thalesogliari.com.br5204000053039865802BR5914Thales Ogliari6009SAO PAULO62070503***63043FD3
}
```

--------------------------------

### Type Guard Functions for Pix Objects (TypeScript)

Source: https://context7.com/thalesog/pix-utils/llms.txt

Demonstrates how to use isStaticPix, isDynamicPix, and isRecurrencePix to narrow down the type of a parsed Pix object. This is crucial for safely accessing properties specific to each Pix type in TypeScript.

```typescript
import {
  parsePix,
  isStaticPix,
  isDynamicPix,
  isRecurrencePix,
  PixStaticObject,
  PixDynamicObject,
  PixRecurrenceObject
} from 'pix-utils';

function handlePix(brCode: string) {
  const pix = parsePix(brCode);

  if (hasError(pix)) {
    console.error('Invalid Pix code');
    return;
  }

  // Type narrowing with guards
  if (isStaticPix(pix)) {
    // pix is now typed as PixStaticObject
    console.log('Processing static payment');
    console.log('Pix Key:', pix.pixKey);
    console.log('Amount:', pix.transactionAmount);
    console.log('Additional Info:', pix.infoAdicional);
    console.log('TXID:', pix.txid);

    if (pix.urlRec) {
      console.log('Has recurrence URL:', pix.urlRec);
    }

    return {
      type: 'static',
      key: pix.pixKey,
      amount: pix.transactionAmount,
    };
  }

  if (isDynamicPix(pix)) {
    // pix is now typed as PixDynamicObject
    console.log('Processing dynamic payment');
    console.log('Payload URL:', pix.url);

    // Fetch payment data asynchronously
    pix.fetchPayload({
      DPP: new Date().toISOString().substring(0, 10),
      codMun: 5300108,
    }).then(data => {
      if (!hasError(data)) {
        console.log('Dynamic amount:', data.payload.valor.original);
      }
    });

    return {
      type: 'dynamic',
      url: pix.url,
    };
  }

  if (isRecurrencePix(pix)) {
    // pix is now typed as PixRecurrenceObject
    console.log('Processing recurrence payment');
    console.log('Recurrence URL:', pix.urlRec);

    // Fetch recurrence data
    pix.fetchRecPayload().then(data => {
      if (!hasError(data)) {
        console.log('Frequency:', data.payload.calendario.periodicidade);
        console.log('Debtor:', data.payload.vinculo.devedor);
      }
    });

    return {
      type: 'recurrence',
      urlRec: pix.urlRec,
    };
  }
}

// Usage examples
const staticBrCode = '00020126650014br.gov.bcb.pix0119key@example.com52040000530398654041.005802BR5914Merchant Name6009City Name62070503***6304XXXX';
handlePix(staticBrCode);

const dynamicBrCode = '00020126580014br.gov.bcb.pix0134pix.provider.com/payment/abc12352040000530398655802BR5914Merchant Name6009City Name6304XXXX';
handlePix(dynamicBrCode);

```

--------------------------------

### Pix Error Handling with `hasError` (TypeScript)

Source: https://context7.com/thalesog/pix-utils/llms.txt

Demonstrates how to use the `hasError` type guard function from 'pix-utils' to check if a Pix operation resulted in an error. This function provides type narrowing for TypeScript, allowing safe access to error messages or successful payment data.

```typescript
import { createStaticPix, hasError, PixError, PixStaticObject } from 'pix-utils';

function processPix(pixKey: string, amount: number) {
  const result = createStaticPix({
    merchantName: 'Store',
    merchantCity: 'City',
    pixKey: pixKey,
    transactionAmount: amount,
  });

  // Type guard narrows type from (PixStaticObject | PixError) to PixStaticObject or PixError
  if (hasError(result)) {
    // result is PixError
    console.error('Error occurred:', result.message);
    console.error('Error flag:', result.error); // true
    return null;
  }

  // result is PixStaticObject
  console.log('Success! Merchant:', result.merchantName);
  return result.toBRCode();
}

// Test with valid data
processPix('valid@email.com', 100);

// Test with invalid data (merchantName too long)
processPix('x'.repeat(30), 100);
// Output: Error occurred: merchantName character limit exceeded (> 25)

// Alternative: throw errors instead of returning PixError
const pix = createStaticPix({
  merchantName: 'X'.repeat(30), // Too long
  merchantCity: 'City',
  pixKey: 'key@email.com',
  transactionAmount: 100,
}).throwIfError(); // Throws exception if error occurred
```

--------------------------------

### Export Pix Data to Base64 Image (JavaScript)

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Converts a parsed Pix object into a Base64 encoded PNG image string using the `toImage` method. This is useful for displaying Pix payment requests visually, such as generating QR codes.

```js
const pix = parsePix(
  '00020126650014br.gov.bcb.pix0119nubank@thalesog.com0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6015SAO MIGUEL DO O62070503***6304059A'
);

pix.toImage();
// data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAAAklEQVR4AewaftIAAAwHSURBVO3BQW4sy7LgQDKh/W...
```

--------------------------------

### Parse BRCode String (JavaScript)

Source: https://github.com/thalesog/pix-utils/blob/master/README.md

Parses a given BR Code string into a Pix object using the `parsePix` function. This function decodes the Pix data, making it accessible for further processing or display. The resulting object includes details like transaction type, merchant information, and Pix key.

```js
const pix = parsePix(
  '00020126650014br.gov.bcb.pix0119nubank@thalesog.com0220Gerado por Pix-Utils52040000530398654041.005802BR5914Thales Ogliari6015SAO MIGUEL DO O62070503***6304059A'
);

// {
//   type: 'STATIC',
//   merchantCategoryCode: '0000',
//   transactionCurrency: '986',
//   countryCode: 'BR',
//   merchantName: 'Thales Ogliari',
//   merchantCity: 'SAO MIGUEL DO O',
//   pixKey: 'nubank@thalesog.com',
//   transactionAmount: 1,
//   infoAdicional: 'Gerado por Pix-Utils',
//   txid: '***',
//   toBRCode: [Function: toBRCode],
//   toImage: [Function: toImage]
// }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.