curl --request POST \
--url https://api.liquerapay.com/transparents/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"method": "PIX",
"amount": 5000,
"description": "Pedido",
"customerId": "cust_018f3a2b7c4d7c40a1b2",
"expiresIn": 1800,
"clientCallbackUrl": "https://meusite.com/webhooks/liquerapay",
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 12.5
}
]
}
'import requests
url = "https://api.liquerapay.com/transparents/create"
payload = {
"method": "PIX",
"amount": 5000,
"description": "Pedido",
"customerId": "cust_018f3a2b7c4d7c40a1b2",
"expiresIn": 1800,
"clientCallbackUrl": "https://meusite.com/webhooks/liquerapay",
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 12.5
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
method: 'PIX',
amount: 5000,
description: 'Pedido',
customerId: 'cust_018f3a2b7c4d7c40a1b2',
expiresIn: 1800,
clientCallbackUrl: 'https://meusite.com/webhooks/liquerapay',
split: [{merchantId: 'clq9a1b2c3d4e5f6g7h8i9j0k1', mode: 'PERCENT', value: 12.5}]
})
};
fetch('https://api.liquerapay.com/transparents/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.liquerapay.com/transparents/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'method' => 'PIX',
'amount' => 5000,
'description' => 'Pedido',
'customerId' => 'cust_018f3a2b7c4d7c40a1b2',
'expiresIn' => 1800,
'clientCallbackUrl' => 'https://meusite.com/webhooks/liquerapay',
'split' => [
[
'merchantId' => 'clq9a1b2c3d4e5f6g7h8i9j0k1',
'mode' => 'PERCENT',
'value' => 12.5
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.liquerapay.com/transparents/create"
payload := strings.NewReader("{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.liquerapay.com/transparents/create")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.liquerapay.com/transparents/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "chg_018f8e2d9a5f7b10c3d4",
"amount": 5000,
"status": "PAID",
"txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f",
"brCode": "00020126580014BR.GOV.BCB.PIX0136abc...6304ABCD",
"imageBase64": "data:image/png;base64,iVBORw0KGgoAAAA...",
"netAmount": 4920,
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 1250,
"amount": 12500
}
],
"createdAt": "2026-04-19T18:32:11.420Z",
"expiresAt": "2026-04-19T19:02:11.420Z",
"customer": {
"id": "cust_018f3a2b7c4d7c40a1b2",
"name": "João Silva",
"taxId": "12345678900",
"email": "joao@exemplo.com",
"phone": "+5511999999999"
}
},
"error": null,
"success": true
}Criar Cobrança PIX
Cria uma cobrança PIX e retorna o QR Code (em texto copia-e-cola e em imagem base64) para o seu cliente pagar.
- O valor é em centavos (
amount) methodhoje só aceita"PIX"- O
expiresIncontrola por quanto tempo o QR Code é válido, em segundos (60 a 2.592.000) - Você pode anexar um cliente cadastrado via
customerId - O merchant precisa ter cobranças habilitadas e uma chave PIX ativa
- Opcionalmente,
split[]divide a cobrança com outras contas Liquera (liquidado no pagamento) clientCallbackUrldefine o callback específico desta cobrança no merchant autenticado; a API cria ou atualiza internamente o endpoint paraCHARGE_CREATEDeCHARGE_PAID
curl --request POST \
--url https://api.liquerapay.com/transparents/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"method": "PIX",
"amount": 5000,
"description": "Pedido",
"customerId": "cust_018f3a2b7c4d7c40a1b2",
"expiresIn": 1800,
"clientCallbackUrl": "https://meusite.com/webhooks/liquerapay",
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 12.5
}
]
}
'import requests
url = "https://api.liquerapay.com/transparents/create"
payload = {
"method": "PIX",
"amount": 5000,
"description": "Pedido",
"customerId": "cust_018f3a2b7c4d7c40a1b2",
"expiresIn": 1800,
"clientCallbackUrl": "https://meusite.com/webhooks/liquerapay",
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 12.5
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
method: 'PIX',
amount: 5000,
description: 'Pedido',
customerId: 'cust_018f3a2b7c4d7c40a1b2',
expiresIn: 1800,
clientCallbackUrl: 'https://meusite.com/webhooks/liquerapay',
split: [{merchantId: 'clq9a1b2c3d4e5f6g7h8i9j0k1', mode: 'PERCENT', value: 12.5}]
})
};
fetch('https://api.liquerapay.com/transparents/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.liquerapay.com/transparents/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'method' => 'PIX',
'amount' => 5000,
'description' => 'Pedido',
'customerId' => 'cust_018f3a2b7c4d7c40a1b2',
'expiresIn' => 1800,
'clientCallbackUrl' => 'https://meusite.com/webhooks/liquerapay',
'split' => [
[
'merchantId' => 'clq9a1b2c3d4e5f6g7h8i9j0k1',
'mode' => 'PERCENT',
'value' => 12.5
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.liquerapay.com/transparents/create"
payload := strings.NewReader("{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.liquerapay.com/transparents/create")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.liquerapay.com/transparents/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"method\": \"PIX\",\n \"amount\": 5000,\n \"description\": \"Pedido\",\n \"customerId\": \"cust_018f3a2b7c4d7c40a1b2\",\n \"expiresIn\": 1800,\n \"clientCallbackUrl\": \"https://meusite.com/webhooks/liquerapay\",\n \"split\": [\n {\n \"merchantId\": \"clq9a1b2c3d4e5f6g7h8i9j0k1\",\n \"mode\": \"PERCENT\",\n \"value\": 12.5\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "chg_018f8e2d9a5f7b10c3d4",
"amount": 5000,
"status": "PAID",
"txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f",
"brCode": "00020126580014BR.GOV.BCB.PIX0136abc...6304ABCD",
"imageBase64": "data:image/png;base64,iVBORw0KGgoAAAA...",
"netAmount": 4920,
"split": [
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 1250,
"amount": 12500
}
],
"createdAt": "2026-04-19T18:32:11.420Z",
"expiresAt": "2026-04-19T19:02:11.420Z",
"customer": {
"id": "cust_018f3a2b7c4d7c40a1b2",
"name": "João Silva",
"taxId": "12345678900",
"email": "joao@exemplo.com",
"phone": "+5511999999999"
}
},
"error": null,
"success": true
}Obrigatório
method (fixo em "PIX") e amount (em centavos, mínimo 100). Os demais
campos são opcionais.{
"method": "PIX",
"amount": 5000,
"description": "Pedido #1234",
"customerId": "cust_018f3a2b7c4d7c40a1b2",
"expiresIn": 1800,
"clientCallbackUrl": "https://meusite.com/webhooks/liquerapay"
}
Callback específico da cobrança
UseclientCallbackUrl quando uma cobrança precisar notificar um endpoint
específico. A URL não precisa estar previamente cadastrada: a API valida a
URL e cria ou atualiza internamente um webhook do merchant autenticado com
CHARGE_CREATED e CHARGE_PAID.
CHARGE_CREATEDé enfileirado logo depois que a cobrança é persistida, com statusPENDINGe os dados do PIX (semimageBase64).CHARGE_PAIDé enviado quando o pagamento for confirmado.- O callback usa o header
Liquera-Signature, além dos mesmos retries e histórico de entregas dos webhooks gerais. - Quando o campo é informado, esses eventos vão somente para o endpoint escolhido. Se omitido, seguem para todos os webhooks gerais inscritos.
secret e validar
Liquera-Signature, cadastre previamente a mesma URL em POST /webhooks e
guarde o valor retornado.Split de pagamento
O campo opcionalsplit[] divide a cobrança com outras contas Liquera. Os
repasses são liquidados pelo PSP no momento em que a cobrança é paga — a sua
conta recebe apenas o líquido, e cada recebedor recebe a parte dele direto no
saldo (mais o webhook SPLIT_RECEIVED).
{
"method": "PIX",
"amount": 10000,
"split": [
{ "merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1", "mode": "PERCENT", "value": 12.5 },
{ "merchantId": "clx8f2k9p0q1r2s3t4u5v6w7x8", "mode": "FIXED", "value": 1500 }
]
}
| Campo | Descrição |
|---|---|
merchantId | ID da conta Liquera que vai receber o repasse. Peça esse ID ao seu parceiro. |
mode | FIXED (valor fixo em centavos) ou PERCENT (percentual do valor bruto). |
value | FIXED → centavos (inteiro ≥ 1). PERCENT → 0.01 a 100, aceita fração (ex.: 12.5). |
netAmount— centavos que ficam com a sua conta =amount− taxa da Liquera − soma dos repassessplit[]— cada repasse resolvido:{ merchantId, mode, value, amount }, ondeamounté o valor efetivo em centavos (noPERCENT, arredondado para baixo)
O recebedor precisa ser uma conta Liquera elegível
O recebedor precisa ser uma conta Liquera elegível
merchantId do split precisa existir (senão 404 NOT_FOUND) e estar
com KYC aprovado, subconta ativa e chave PIX ativa — caso
contrário 400 BAD_REQUEST. Não é possível fazer split para uma chave PIX
externa nem para a sua própria conta.No máximo 5 repasses por cobrança
No máximo 5 repasses por cobrança
split[] aceita de 1 a 5 entradas, sem merchantId repetido.Precisa sobrar valor para a sua conta
Precisa sobrar valor para a sua conta
taxa da Liquera + soma dos repasses tem que deixar pelo menos 1
centavo para você. Se estourar, a criação retorna 400 BAD_REQUEST com o
detalhamento (bruto / taxa / splits / restante).A taxa da Liquera é cobrada só de você
A taxa da Liquera é cobrada só de você
Como apresentar o QR Code
A resposta traz dois formatos — escolha o melhor para seu canal:brCode (texto)
imageBase64 (imagem)
data:image/png;base64,...). Renderize com <img src={...}>.<!-- Renderizando direto no HTML -->
<img src="data:image/png;base64,iVBORw0KGgoAAAA..." alt="QR Code PIX" />
Validações importantes
Sua conta precisa estar apta a cobrar
Sua conta precisa estar apta a cobrar
400 BAD_REQUEST.amount respeita os limites do merchant
amount respeita os limites do merchant
minTicket e maxTicket definidos, além do limite fixo de
100 a 100.000.000 centavos. Valores fora do intervalo retornam
400 BAD_REQUEST.customerId precisa existir e pertencer ao seu merchant
customerId precisa existir e pertencer ao seu merchant
404 NOT_FOUND.expiresIn entre 60 e 2.592.000 segundos
expiresIn entre 60 e 2.592.000 segundos
description tem no máximo 140 caracteres
description tem no máximo 140 caracteres
clientCallbackUrl configura o callback da cobrança
clientCallbackUrl configura o callback da cobrança
CHARGE_CREATED e CHARGE_PAID.Authorizations
Autentique suas requisições enviando o token no header
Authorization: Bearer <token>.
O token pode ser:
- Uma API key com prefixo
liq_, gerada em Dashboard Liquerapay → Configurações → API Keys. - Um JWT retornado pelo login do dashboard (uso interno).
Não há distinção de ambiente — toda chave vale para o único ambiente disponível (produção).
Body
Método de pagamento — hoje só "PIX" é suportado.
PIX "PIX"
Valor da cobrança em centavos, sujeito ao limite do merchant.
100 <= x <= 1000000005000
Texto que aparece para o cliente no momento do pagamento.
140"Pedido"
Opcional. ID de um cliente já cadastrado para anexar à cobrança.
50"cust_018f3a2b7c4d7c40a1b2"
Tempo de validade do QR Code em segundos (60 a 2.592.000 = 30 dias). Padrão 86400 = 24h.
60 <= x <= 25920001800
URL HTTPS pública opcional para receber CHARGE_CREATED e
CHARGE_PAID somente desta cobrança. A API cria ou atualiza
internamente o endpoint no merchant autenticado e substitui os
webhooks gerais nesses eventos. Para obter o secret usado na
assinatura, cadastre previamente a mesma URL em POST /webhooks.
2048"https://meusite.com/webhooks/liquerapay"
Opcional. Divide a cobrança com outras contas Liquera (até 5 repasses). Cada recebedor precisa estar com KYC aprovado e ter subconta + chave PIX ativas. A soma dos repasses mais a taxa da Liquera precisa deixar pelo menos 1 centavo para a sua conta.
5Show child attributes
Show child attributes
[
{
"merchantId": "clq9a1b2c3d4e5f6g7h8i9j0k1",
"mode": "PERCENT",
"value": 12.5
}
]