Generate QR Code

Generating PIX Charge

This endpoint creates a PIX charge and returns the QR Code that your customer will use to pay.

Create PIX Charge

Two versions are available (same payload, different error format).

POST /payins

Headers

Name	Type	Description
x-api-token *	string	Authentication token for your integration.
x-provider-id *	string	Provider/partner identifier assigned by Lulipay.
x-provider *	string	Provider name (company/partner name).
x-country-code *	string	Country code for the operation (for example, BR).
x-idempotency-key *	string	Unique key per logical operation attempt to prevent duplication.

How to use `x-idempotency-key` correctly

This header protects your integration from duplicate processing during retries (timeouts, network instability, etc.).

Recommended rules:

Generate a unique key per business operation (for example, UUID v4).
Reuse the same key only when retrying the same operation.
Never reuse the same key for different operations.
Persist the key in your system for traceability and reconciliation.

Example:

x-idempotency-key: 6f5d8f77-2f5c-4219-a5c8-4d7742fcb3c5

Request Body

Name	Type	Required	Description
value	number	Yes	PIX charge amount
description	string	No	Charge description (up to 140 chars)
buyer_cpf	string	Yes	CPF of the payer (only digits, length 11)
buyer_name	string	Yes	Payer name
buyer_email	string	Yes	Payer e-mail
webhook_url	string	Yes	URL that will be triggered when the charge is paid
generate_qrcode	boolean	No	When `true`, the response includes `qr_code_base64`; when `false`, `qr_code_base64` is not returned.
expiration	int	No	Time in seconds before the QR Code expires (20 – 172800). Default 240 s

Successful response (200)

{
  "id": "bac1b8d7-24ce-4b53-b6d9-babd3aa60968",
  "pix_id": "61c21aet-3452-8644v-3vvb2-234886cc",
  "acquirer_id": "LPAYTESTPIXQRCODE154",
  "qr_code": "00000000000000000000br.gov.bcb.pix012...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAAA..."
}

qr_code_base64 is returned only when generate_qrcode is true.

Error response example (Validation)

{
  "message": "Erro na validação",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "message": "Insira um email válido",
      "code": "INVALID_VALUE",
      "field": "email"
    }
  ]
}

Error Codes

Code	Description
VALIDATION_ERROR	Errors found in request payload
INVALID_VALUE	Invalid field value
NOT_PROCESSABLE	Valid payload but cannot be processed
NO_ACTIVE_CREDENTIAL	No active credential configured
EXTERNAL_ERROR	Error in partner system
DUPLICATED_VALUE	Resource with given value already exists
REQUIRED_VALUE	A required field was not sent
EMPTY_VALUE	Field sent empty

Examples

cURL
Python
Node.js
PHP
Java

curl --request POST "https://gateway.lulipay.com/v1/payins" --header "Content-Type: application/json" --header "x-api-token: YOUR_API_TOKEN" --header "x-provider-id: YOUR_PROVIDER_ID" --header "x-provider: YOUR_PROVIDER_NAME" --header "x-country-code: BR" --header "x-idempotency-key: 6f5d8f77-2f5c-4219-a5c8-4d7742fcb3c5" --data '{
  "value": 1,
  "description": "",
  "buyer_cpf": "",
  "buyer_name": "",
  "buyer_email": "",
  "webhook_url": "",
  "generate_qrcode": true,
  "expiration": 172800
}'

import requests
import uuid

url = "https://gateway.lulipay.com/v1/payins"

payload = {
"value": 1,
"description": "",
"buyer_cpf": "",
"buyer_name": "",
"buyer_email": "",
"webhook_url": "",
"generate_qrcode": True,
"expiration": 172800
}

headers = {
"Content-Type": "application/json",
"x-api-token": "YOUR_API_TOKEN",
"x-provider-id": "YOUR_PROVIDER_ID",
"x-provider": "YOUR_PROVIDER_NAME",
"x-country-code": "BR",
"x-idempotency-key": str(uuid.uuid4())
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

const axios = require("axios");
const { randomUUID } = require("crypto");

const url = "https://gateway.lulipay.com/v1/payins";

const headers = {
"Content-Type": "application/json",
"x-api-token": "YOUR_API_TOKEN",
"x-provider-id": "YOUR_PROVIDER_ID",
"x-provider": "YOUR_PROVIDER_NAME",
"x-country-code": "BR",
"x-idempotency-key": randomUUID(),
};

const payload = {
value: 1,
description: "",
buyer_cpf: "",
buyer_name: "",
buyer_email: "",
webhook_url: "",
generate_qrcode: true,
expiration: 172800,
};

axios
.post(url, payload, { headers })
.then((response) => console.log(response.data))
.catch((error) => console.error(error.response?.data || error.message));

<?php
$url = "https://gateway.lulipay.com/v1/payins";

$headers = [
"Content-Type: application/json",
"x-api-token: YOUR_API_TOKEN",
"x-provider-id: YOUR_PROVIDER_ID",
"x-provider: YOUR_PROVIDER_NAME",
"x-country-code: BR",
"x-idempotency-key: " . bin2hex(random_bytes(16)),
];

$payload = [
"value" => 1,
"description" => "",
"buyer_cpf" => "",
"buyer_name" => "",
"buyer_email" => "",
"webhook_url" => "",
"generate_qrcode" => true,
"expiration" => 172800,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class CreatePixChargeExample {
public static void main(String[] args) throws Exception {
String url = "https://gateway.lulipay.com/v1/payins";

      String jsonBody = """
          {
            "value": 1,
            "description": "",
            "buyer_cpf": "",
            "buyer_name": "",
            "buyer_email": "",
            "webhook_url": "",
            "generate_qrcode": true,
            "expiration": 172800
          }
          """;

      HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create(url))
          .header("Content-Type", "application/json")
          .header("x-api-token", "YOUR_API_TOKEN")
          .header("x-provider-id", "YOUR_PROVIDER_ID")
          .header("x-provider", "YOUR_PROVIDER_NAME")
          .header("x-country-code", "BR")
          .header("x-idempotency-key", UUID.randomUUID().toString())
          .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
          .build();

      HttpClient client = HttpClient.newHttpClient();
      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println(response.body());
  }

}

Generating PIX Charge​

Create PIX Charge​

Headers​

How to use x-idempotency-key correctly​

Request Body​

Successful response (200)​

Error response example (Validation)​

Error Codes​

Examples​