Request PIX Payment

Create a PIX payout (withdrawal/payment) to a recipient.

Endpoint

POST /payouts

---

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:

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

Example:

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

---

Request Body

Field	Type	Required	Description
value	number	Yes	PIX payment amount
description	string	No	Description (max 140 characters)
receiver_cpf	string	Yes	Recipient CPF (11 digits)
receiver_name	string	Yes	Recipient name
receiver_email	string	Yes	Recipient email
webhook_url	string	Yes	URL triggered when the payment is completed or canceled
pix_key	string	Yes	PIX key
pix_key_type	string	Yes	Key type: cpf, email, phone, or evp

Example (JSON)

{
  "value": 1,
  "description": "",
  "receiver_cpf": "",
  "receiver_name": "",
  "receiver_email": "",
  "webhook_url": "",
  "pix_key": "",
  "pix_key_type": "cpf"
}

---

pix_key validation rules

pix_key_type	Validation (pix_key field)	Example	Size
cpf	11 numeric digits	14785236987	11
phone	13 chars: + + country code + area code + 9-digit num	+5500999999999	13
email	Valid e-mail address	user@domain.com	—
evp	36-char UUID	123e4567-e89b-12d3-a456-426614174000	36

---

Success response (200)

{
  "id": "1c389fa9-1cb5-40ac-a0ae-1e5bc1cdf3d8",
  "status": "waiting"
}

Error response example

{
  "message": "Validation error",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "message": "Invalid PIX key.",
      "code": "INVALID_VALUE",
      "field": "pix_key"
    }
  ]
}

Error Codes

Code	Description
VALIDATION_ERROR	Validation errors in 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

---

Request examples

cURL

curl --request POST "https://gateway.lulipay.com/v1/payouts" --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": "",
  "receiver_cpf": "",
  "receiver_name": "",
  "receiver_email": "",
  "webhook_url": "",
  "pix_key": "",
  "pix_key_type": "cpf",
}'

Python

import requests
import uuid

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

payload = {
"value": 1,
"description": "",
"receiver_cpf": "",
"receiver_name": "",
"receiver_email": "",
"webhook_url": "",
"pix_key": "",
"pix_key_type": "cpf"
}

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)

Node.js

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

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

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: "",
receiver_cpf: "",
receiver_name: "",
receiver_email: "",
webhook_url: "",
pix_key: "",
pix_key_type: "cpf"
};

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/payouts";

$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" => "",
"receiver_cpf" => "",
"receiver_name" => "",
"receiver_email" => "",
"webhook_url" => "",
"pix_key" => "",
"pix_key_type" => "cpf"
];

$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;
import java.util.UUID;

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

      String jsonBody = """
          {
            "value": 1,
            "description": "",
            "receiver_cpf": "",
            "receiver_name": "",
            "receiver_email": "",
            "webhook_url": "",
            "pix_key": "",
            "pix_key_type": "cpf"
          }
          """;

      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());
  }

}

---

Notes

• Only one withdrawal can be in progress per recipient; simultaneous requests may be canceled.
• In the staging environment you can force the transaction status to completed or canceled (see test payment endpoint).