PIX Key Validation Documentation

Overview

This document outlines the validation process and response formats for PIX key transactions in the Brazilian instant payment system. PIX Key Validation allows you to verify the owner of a PIX key before making a payment, ensuring you are sending money to the correct recipient.

What are PIX Keys?

PIX Keys are aliases or IDs used by the PIX system to route payments to the appropriate bank account. They can take several forms:

CPF or CNPJ: Brazilian personal or company IDs (use only numbers without special symbols)
Email address: Standard email format
Phone number: Include with country code (e.g., +55 for Brazil)
Random key: Alphanumeric string

By validating a PIX key through this endpoint, you'll receive the name of the bank account owner for verification before proceeding with the payment.

Validating a Pix key before making a payment helps ensure that funds are sent to the intended recipient and reduces the risk of errors.

Query Parameters

Name	Type	Description
pix_key	string	Required. The Pix key to validate (CPF/CNPJ, email, phone, or random key)

Example Request

const pix_key = "mati@kamipay.io";

const url = `${baseURL}/v1/payments/pixKeyValidation?pix_key=${pix_key}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

import requests

pix_key = "mati@kamipay.io"
url = f"{base_url}/v1/payments/pixKeyValidation?pix_key={pix_key}"

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

func main() {
    pix_key := "mati@kamipay.io"
    accessToken := "YOUR_ACCESS_TOKEN" // Replace with your actual token
    baseURL := "https://your-api-base-url.com" // Replace with your actual base URL

    // Create URL with query parameters
    reqURL, _ := url.Parse(fmt.Sprintf("%s/v1/payments/pixKeyValidation", baseURL))
    params := url.Values{}
    params.Add("pix_key", pix_key)
    reqURL.RawQuery = params.Encode()

    // Create request
    req, _ := http.NewRequest("GET", reqURL.String(), nil)
    req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", accessToken))
    req.Header.Add("Content-Type", "application/json")

    // Make the request
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer resp.Body.Close()

    // Read the response body
    body, _ := ioutil.ReadAll(resp.Body)

    // Print response status and body
    fmt.Println("Response Status:", resp.Status)
    fmt.Println("Response Body:", string(body))
}

Response Formats

Responses indicate the validity and details of the PIX key.

Successful Responses

Description: A standard PIX key response (like email, CPF, phone) without expiration or fixed amount.

{
  "msg": "valid pixkey",
  "reformated_key": "mati@kamipay.io",
  "name": "LARISSA DA SILVA DIAS",
  "amount": "",
  "timeout": "0"
}

Empty, zero, or null values for amount and timeout indicate no specific amount or expiration is assigned.

Description: Response when processing a static QR code (typically without a predefined amount).

{
  "msg": "valid pixkey",
  "reformated_key": "00020126680014br.gov.bcb.pix0115***02275204000053039865802BR5925KAMIPAY LTDA6009SAO PAULO622905256673568298KP19478949731630470C8",
  "name": "KAMIPAY LTDA",
  "amount": "",
  "timeout": "0"
}

Characteristics: No predefined amount or timeout. User can pay any amount. amount and timeout fields are empty, zero, or null. Note the structure includes detail.

Description: Response when processing a dynamic QR code (typically with a fixed amount and expiration).

{
  "msg": "valid pixkey",
  "reformated_key": "00020126820014br.gov.bcb.pix25601da4ebd2-7fbb-4933-a6f7-7d392BR5925KAMIPAY_LTDA6009SAO_PAULO62070503***6304CFAB",
  "name": "KAMIPAY LTDA",
  "amount": "10.00",
  "timeout": "1744116044"
}

Characteristics: Fixed amount must be paid. timeout contains an epoch timestamp for expiration.

Error Responses

Common errors encountered during validation.

Description: Specific error when a QR code payload is invalid or expired. Often returned with HTTP 200 OK but indicates a validation failure in the data.

{
  "detail": {
    "msg": "Expired or Invalid QR code",
    "reformated_key": null,
    "name": null
  }
}

Check the msg field within detail to identify this specific validation error.

Description: Bad Request - The request parameters are invalid or missing.

{
  "detail": "detailed error will be provided here (e.g., missing pix_key)"
}

Description: Unauthorized - Incorrect API credentials provided.

{
  "detail": "Incorrect Credentials"
}

Description: Internal Server Error - An unexpected error occurred on the server.

{
  "detail": "an unexpected error occurred"
}

Description: Service Unavailable - The service is temporarily unavailable (e.g., due to maintenance).

{
  "detail": "Service is temporarily unavailable due to maintenance"
}

Field Descriptions

Field	Description
`msg`	Status message indicating validity of the PIX key (can be top-level or within `detail`)
`reformated_key`	The validated, formatted PIX key or the raw encoded QR data
`name`	Name of the account holder associated with the PIX key (null if invalid)
`amount`	Payment amount specified by the key/QR (empty, "0", or null when no amount is defined)
`timeout`	Expiration timestamp in epoch format for dynamic QRs; "0" or null indicates no expiration
`status_code`	HTTP status code of the response (sometimes included within the JSON body, e.g., for Static QR)
`detail`	Object containing detailed response/error information for certain cases (e.g., Static QR, Invalid QR, HTTP errors)

Implementation Notes

Always check the HTTP status code first (e.g., 200, 400, 401).
If the status is 200 OK, inspect the msg field (potentially within detail) to confirm PIX key validity (e.g., "valid pixkey" vs "Expired or Invalid QR code").
For dynamic QR codes (timeout > 0), verify that the current time is before the timeout value.
When processing payments for dynamic QR codes, use the exact amount returned.
For static QR codes or standard PIX keys (where amount is "0", empty, or null), the payment amount must be collected from the user.

Pix Key Validation