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

# Decode QR Code

> Decode third-parties PIX QR codes to make them payable at the create payment endpoint

# Decode QR Code

Decode third-parties PIX QR codes to make them payable at the create payment endpoint.

## Request Body

<ParamField body="emv" type="string" required>
  EMV from the QR Code.

  Example: `00020126580014BR.GOV.BCB.PIX...`
</ParamField>

<ParamField body="app" type="string">
  Data of payment - optional parameter, should be used with QR Codes that have discount or fines.

  Format: `<date>`
</ParamField>

<ParamField body="city_code" type="string">
  City code.
</ParamField>

## Response

<ResponseField name="end_to_end_id" type="string">
  End to end ID - can be used for 30d after generation.
</ResponseField>

<ResponseField name="credit_party" type="object">
  Beneficiary data.

  <Expandable title="Credit Party">
    <ResponseField name="name" type="string">
      PIX name of the beneficiary.
    </ResponseField>

    <ResponseField name="key_type" type="string">
      PIX key type of the beneficiary.
    </ResponseField>

    <ResponseField name="key" type="string">
      PIX key of the beneficiary.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="amount" type="number">
  Amount of the QR code.
</ResponseField>

<ResponseField name="is_amount_changeable" type="boolean">
  If true, the amount can be changed at payment endpoint.
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123' \
    --header 'Content-Type: application/json' \
    --data '{
      "emv": "00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D",
      "app": "2023-08-24",
      "city_code": "string"
    }'
  ```

  ```javascript JavaScript theme={null}
  async function decodeQRCode(emv, app = null, cityCode = null) {
    const body = { emv };
    
    if (app) body.app = app;
    if (cityCode) body.city_code = cityCode;
    
    const response = await fetch(
      'https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode',
      {
        method: 'POST',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(body)
      }
    );
    
    return await response.json();
  }

  // Usage
  const qrData = await decodeQRCode(
    '00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D'
  );

  console.log('QR Code decoded:', qrData);
  console.log('Beneficiary:', qrData.credit_party.name);
  console.log('Amount:', qrData.amount);
  console.log('Can change amount:', qrData.is_amount_changeable);
  ```

  ```python Python theme={null}
  import requests

  def decode_qr_code(emv, app=None, city_code=None):
      url = 'https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123',
          'Content-Type': 'application/json'
      }
      
      data = {'emv': emv}
      
      if app:
          data['app'] = app
      if city_code:
          data['city_code'] = city_code
      
      response = requests.post(url, headers=headers, json=data)
      return response.json()

  # Usage
  qr_data = decode_qr_code(
      '00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D'
  )

  print(f"QR Code decoded: {qr_data}")
  print(f"Beneficiary: {qr_data['credit_party']['name']}")
  print(f"Amount: {qr_data['amount']}")
  print(f"Can change amount: {qr_data['is_amount_changeable']}")
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "end_to_end_id": "string",
    "credit_party": {
      "name": "string",
      "key_type": "string",
      "key": "string"
    },
    "amount": 0,
    "is_amount_changeable": true
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Invalid QR Code format"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Failed to decode QR Code"
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Pay Third-Party PIX QR Code">
    Decode and pay a PIX QR Code from another institution:

    ```javascript theme={null}
    async function payThirdPartyQRCode(qrCodeEmv) {
      // Step 1: Decode the QR Code
      const qrData = await decodeQRCode(qrCodeEmv);
      
      console.log(`Paying to: ${qrData.credit_party.name}`);
      console.log(`Amount: R$ ${qrData.amount}`);
      
      // Step 2: Create payment using decoded data
      const payment = await createPayment({
        amount: qrData.amount * 100, // Convert to cents
        currency: 'BRL',
        country: 'BR',
        description: `Payment to ${qrData.credit_party.name}`,
        recipient: {
          name: qrData.credit_party.name,
          pix_key: qrData.credit_party.key,
          pix_key_type: qrData.credit_party.key_type
        },
        end_to_end_id: qrData.end_to_end_id
      });
      
      return payment;
    }
    ```
  </Accordion>

  <Accordion title="Validate QR Code Before Payment">
    Validate QR Code and show details to user before confirming:

    ```javascript theme={null}
    async function validateAndShowQRCode(qrCodeEmv) {
      try {
        const qrData = await decodeQRCode(qrCodeEmv);
        
        // Show details to user for confirmation
        const confirmation = {
          beneficiary: qrData.credit_party.name,
          pixKey: qrData.credit_party.key,
          keyType: qrData.credit_party.key_type,
          amount: qrData.amount,
          canChangeAmount: qrData.is_amount_changeable,
          valid: true
        };
        
        return confirmation;
      } catch (error) {
        return {
          valid: false,
          error: 'Invalid QR Code'
        };
      }
    }

    // Usage
    const validation = await validateAndShowQRCode(qrCodeEmv);

    if (validation.valid) {
      console.log('QR Code is valid');
      console.log(`Pay R$ ${validation.amount} to ${validation.beneficiary}`);
      
      // Show confirmation dialog to user
      const confirmed = await showConfirmationDialog(validation);
      
      if (confirmed) {
        await payThirdPartyQRCode(qrCodeEmv);
      }
    } else {
      console.error('Invalid QR Code');
    }
    ```
  </Accordion>

  <Accordion title="Handle Dynamic Amount QR Codes">
    Handle QR Codes where amount can be changed:

    ```javascript theme={null}
    async function payDynamicAmountQRCode(qrCodeEmv, customAmount = null) {
      const qrData = await decodeQRCode(qrCodeEmv);
      
      let finalAmount = qrData.amount;
      
      if (qrData.is_amount_changeable && customAmount) {
        finalAmount = customAmount;
        console.log(`Amount changed from R$ ${qrData.amount} to R$ ${customAmount}`);
      } else if (!qrData.is_amount_changeable && customAmount) {
        console.warn('Cannot change amount for this QR Code');
      }
      
      const payment = await createPayment({
        amount: finalAmount * 100,
        currency: 'BRL',
        country: 'BR',
        description: `Payment to ${qrData.credit_party.name}`,
        recipient: {
          name: qrData.credit_party.name,
          pix_key: qrData.credit_party.key,
          pix_key_type: qrData.credit_party.key_type
        },
        end_to_end_id: qrData.end_to_end_id
      });
      
      return payment;
    }
    ```
  </Accordion>

  <Accordion title="Bulk QR Code Processing">
    Process multiple QR Codes in batch:

    ```javascript theme={null}
    async function processBulkQRCodes(qrCodes) {
      const results = [];
      
      for (const qr of qrCodes) {
        try {
          const qrData = await decodeQRCode(qr.emv);
          
          results.push({
            id: qr.id,
            success: true,
            beneficiary: qrData.credit_party.name,
            amount: qrData.amount,
            data: qrData
          });
        } catch (error) {
          results.push({
            id: qr.id,
            success: false,
            error: error.message
          });
        }
      }
      
      return results;
    }

    // Usage
    const qrCodes = [
      { id: 'QR1', emv: 'emv-string-1' },
      { id: 'QR2', emv: 'emv-string-2' }
    ];

    const results = await processBulkQRCodes(qrCodes);
    console.log('Processed QR Codes:', results);
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Note>
  **End-to-End ID Validity**: The `end_to_end_id` can be used for 30 days after generation. Store it if you need to make the payment later.
</Note>

<Warning>
  **Amount Validation**: Always check `is_amount_changeable` before allowing users to modify the payment amount.
</Warning>

<Tip>
  **Error Handling**: Implement proper error handling for invalid QR Codes. Not all QR Codes are valid PIX codes.
</Tip>

<Note>
  **QR Code Format**: The EMV string should be the complete PIX QR Code string starting with "00020126...".
</Note>

## PIX Key Types

Common PIX key types you might encounter:

| Key Type | Description       | Example                                     |
| -------- | ----------------- | ------------------------------------------- |
| CPF      | Individual tax ID | 12345678900                                 |
| CNPJ     | Company tax ID    | 12345678000190                              |
| EMAIL    | Email address     | [user@example.com](mailto:user@example.com) |
| PHONE    | Phone number      | +5511999999999                              |
| EVP      | Random key        | 123e4567-e89b-12d3-a456-426614174000        |

## Integration Flow

```mermaid theme={null}
graph TD
    A[User scans QR Code] --> B[Get EMV string]
    B --> C[Call Decode QR Code API]
    C --> D{Valid QR Code?}
    D -->|Yes| E[Show payment details]
    D -->|No| F[Show error message]
    E --> G[User confirms]
    G --> H[Create Payment]
    H --> I[Payment processed]
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Payment" icon="money-bill-transfer" href="/api-reference/cash-out/payout/create-payment">
    Create payment after decoding QR Code
  </Card>

  <Card title="Callback Payment" icon="webhook" href="/api-reference/cash-out/payout/callback-payment">
    Receive payment notifications
  </Card>
</CardGroup>