Authentication

Overview

Authentication in the Lulipay API is performed using required headers on every request. There is no JWT login step in this version.

Required headers

Send the following headers in all API calls:

• x-api-token: {API_TOKEN}
• x-provider-id: {PROVIDER_ID}
• x-provider: {PROVIDER_NAME}
• x-country-code: {COUNTRY_CODE}

Header description

Header	Required	Description
x-api-token	Yes	Authentication token for your integration.
x-provider-id	Yes	Provider/partner identifier assigned by Lulipay.
x-provider	Yes	Provider name (for example, your company or partner name).
x-country-code	Yes	Country code for the operation (for example, BR).

Usage examples

cURL

curl --request POST "https://gateway.lulipay.com/v1/payin/payment/request" --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" --data '{
  "value": 150.00,
  "description": "Payment for invoice #1234",
  "receiver_pix_key": "john.doe@email.com",
  "receiver_name": "John Doe",
  "reference_id": "PAY1234"
}'

Python

import requests

url = "https://gateway.lulipay.com/v1/pix/payment/request"
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"
}

payload = {
"value": 150.00,
"description": "Payment for invoice #1234",
"receiver_pix_key": "john.doe@email.com",
"receiver_name": "John Doe",
"reference_id": "PAY1234"
}

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

Node.js

const axios = require("axios");
const url = "https://gateway.lulipay.com/v1/pix/payment/request";

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",
};

const payload = {
value: 150.0,
description: "Payment for invoice #1234",
receiver_pix_key: "john.doe@email.com",
receiver_name: "John Doe",
reference_id: "PAY1234",
};

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

PHP

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

$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",
];

$payload = [
"value" => 150.00,
"description" => "Payment for invoice #1234",
"receiver_pix_key" => "john.doe@email.com",
"receiver_name" => "John Doe",
"reference_id" => "PAY1234",
];

$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;

Java

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

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

      String jsonBody = """
          {
            "value": 150.00,
            "description": "Payment for invoice #1234",
            "receiver_pix_key": "john.doe@email.com",
            "receiver_name": "John Doe",
            "reference_id": "PAY1234"
          }
          """;

      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")
          .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
          .build();

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

}

---

Best practices

• Never expose x-api-token in frontend/mobile clients; use backend-to-backend integration.
• Rotate credentials periodically and revoke unused credentials.
• Add observability using reference_id in your logs.
• Trigger operational alerts for recurrent 401 and 403 responses.

Error handling

Error Code	Description	Action
401	Invalid authentication headers	Validate x-api-token, x-provider-id, x-provider, and x-country-code
403	Insufficient permissions	Verify credential scope with support
429	Too many requests	Apply retries with exponential backoff

Support

The following authentication values are provided by the Lulipay support team:

• x-api-token
• x-provider-id
• x-provider
• x-country-code

For authentication support:

• Email: contato@lulipay.com.br
• Support Hours: 24/7