Endpoints /integrated-payment e /integrated-payment/status, com exemplos em 6 linguagens
Sobre esta referência
Esta página documenta, endpoint a endpoint, a criação de cobranças PIX e a consulta de status. Todos os campos, exemplos de resposta e mensagens de erro abaixo foram verificados ao vivo contra a API de produção em 19/07/2026 (cobranças reais de R$ 10,00, R$ 25,00 e R$ 50,00) e batem com a especificação OpenAPI usada em produção (/api-docs, versão 3.5) — em caso de qualquer divergência, a especificação Swagger é sempre a fonte de verdade.
Autenticação: todos os endpoints abaixo usam o parâmetro code (query em GET, corpo JSON em POST) — não é Basic Auth. Veja a página de Autenticação para detalhes. URL base usada nos exemplos: https://blackrocket.space/api.
⚠️ Sempre envie o header Accept: application/json. Vários endpoints validam parâmetros obrigatórios (code, value, ...) com o validador padrão do Laravel. Se a requisição não enviar esse header e um parâmetro obrigatório estiver faltando, a API retorna um redirect HTML 302 para a raiz do site em vez de um erro JSON — isso foi reproduzido ao vivo em /integrated-payment ao omitir code. Todos os exemplos de código abaixo já enviam esse header.
GET/integrated-payment
Cria um link/QRCode de cobrança PIX com valor pré-definido. Quando qrprint=true, a resposta é a imagem do QRCode (image/png) em vez de JSON. Limite de taxa: 60 requisições por minuto (verificado ao vivo via headers X-RateLimit-* em 19/07/2026).
Identificação do pagador (KYC) é obrigatória na prática. Mesmo que a validação da própria API não rejeite a requisição por falta desse dado, o PSP upstream (Eulen/DePix) rejeita a cobrança com 422 a menos que o pagador já seja conhecido (tenha um EUID cadastrado) ou que endUserTaxNumber seja informado. Veja o parâmetro abaixo e os exemplos de erro 422.
Parâmetros (query string)
Parâmetro
Tipo
Obrigatório
Descrição
code
string
Sim
Seu código de integração (API). Se ausente, com Accept: application/json retorna 422; sem esse header, retorna um redirect HTML 302.
value
number
Sim
Valor em REAIS (BRL), não centavos (ex.: 10 = R$ 10,00) — a API multiplica por 100 internamente. Mínimo de R$ 2,00 por cobrança.
description
string
Não
Descrição da cobrança.
qrprint
boolean
Não
Se true, retorna a imagem do QRCode diretamente em vez de JSON.
thirdwallet
string
Não
Endereço Liquid Network customizado para receber o pagamento, no lugar da carteira padrão associada ao code. Aviso crítico: a plataforma não é responsável por perdas causadas por endereço incorreto — transações na Liquid Network não podem ser revertidas.
endUserTaxNumber
string
Não (mas necessário na prática)
CPF/CNPJ do pagador (somente dígitos) ou um EUID DePix já existente (EU...). Usado para o KYC obrigatório do PSP upstream — sem ele, pagadores não cadastrados recebem 422.
webhook
string ("1", "true", "0", "false")
Não
Ativa o modo de webhook genérico quando 1 ou true.
response_url
string (URI)
Não
URL do seu listener (HTTPS em produção). Recebe um POST quando o pagamento é confirmado.
details
object
Não
Metadata customizada. Fica armazenada e é ecoada em details_transaction no callback.
Resposta de sucesso (200)
Resposta real, capturada em produção (cobrança de R$ 10,00, 19/07/2026). Note que id, qrCopyPaste e qrImageUrl ficam aninhados em pix.data.response, não no nível raiz.
qrImageUrl aponta para o domínio do PSP (resources.eulen.app), não para esta plataforma.
Para obter a imagem do QRCode diretamente:
# qrprint=true retorna a imagem do QRCode (image/png) em vez de JSON
curl -G "https://blackrocket.space/api/integrated-payment" \
--data-urlencode "code=SEU_CODIGO" \
--data-urlencode "value=10" \
--data-urlencode "qrprint=true" \
-o qrcode.png
Erros
Status
Quando ocorre
400
value ausente ou inválido. Formato error (não success/message): {"error": "Value (amount) is required and must be a positive number"}.
404
code sem permanent_link correspondente — {"error": "Invalid integrate code"} — ou wallet ausente — {"error": "Wallet not found"}.
422
Duas formas possíveis: (a) code ausente, com Accept: application/json — {"message": "The given data was invalid.", "errors": {"code": ["The code field is required."]}}; (b) valor abaixo do mínimo de R$ 2,00, mensagem sempre em português independentemente de Accept-Language — {"success": false, "message": "Erro de validação.", "errors": {"value": ["O valor mínimo para gerar um boleto é de R$ 2,00."]}}; (c) PSP rejeita por falta de KYC — {"success": false, "message": "EUID or end-user tax number is required to create a deposit", ...}.
429
Limite de 60 requisições/minuto excedido. {"message": "Too Many Attempts."}.
import requests
params = {
"code": "SEU_CODIGO",
"value": 10, # reais, não centavos: 10 = R$ 10,00
"description": "Pedido 1234",
"endUserTaxNumber": "00550235175", # CPF/CNPJ do pagador ou EUID DePix existente
}
response = requests.get(
"https://blackrocket.space/api/integrated-payment",
params=params,
headers={"Accept": "application/json"}, # evita redirect HTML 302 em caso de erro
)
data = response.json()
# Os campos úteis ficam aninhados em pix.data.response, não no nível raiz.
pix = data["pix"]["data"]["response"]
print(pix["id"], pix["qrCopyPaste"])
Java (java.net.http)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://blackrocket.space/api/integrated-payment?code=SEU_CODIGO&value=10&description=Pedido+1234&endUserTaxNumber=00550235175"))
.header("Accept", "application/json") // evita redirect HTML 302 em caso de erro
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
// Os campos úteis ficam em pix.data.response.{id,qrCopyPaste,qrImageUrl}
POST/integrated-payment
Mesmo comportamento do GET, com os parâmetros enviados como corpo JSON e a mesma resposta aninhada em pix.data.response. Retorna sempre JSON (não há modo qrprint no POST). Limite de taxa: 60 requisições por minuto.
Ao habilitar o webhook genérico (webhook: 1 + response_url), a plataforma faz o POST no seu response_url quando o pagamento é confirmado — é a plataforma que chama seu endpoint, não o contrário. O corpo desse callback segue o mesmo formato do payload documentado em /webhooks/deposit_v2, e a metadata enviada em details é ecoada em details_transaction. Veja um exemplo de endpoint receptor na página de Webhooks.
Corpo da requisição (JSON)
Campo
Tipo
Obrigatório
Descrição
code
string
Sim
Seu código de integração (API).
value
number
Sim
Valor em REAIS (BRL), não centavos (ex.: 10 = R$ 10,00; 12.10 = R$ 12,10). Mínimo de R$ 2,00.
description
string
Não
Descrição da cobrança.
endUserTaxNumber
string
Não (mas necessário na prática)
CPF/CNPJ do pagador (somente dígitos) ou EUID DePix existente. Sem isso, o PSP upstream pode rejeitar com 422 por falta de KYC.
thirdwallet
string
Não
Endereço Liquid Network customizado. Mesmo aviso de irreversibilidade do GET acima.
webhook
integer (0/1) ou boolean
Não
Ativa o modo de webhook genérico.
response_url
string (URI)
Não
URL do seu listener. Recebe um POST quando o pagamento é confirmado.
details
object
Não
Metadata customizada, aceita chaves e estruturas arbitrárias. Ecoada em details_transaction no callback.
Resposta de sucesso (200)
Resposta real, capturada em produção (cobrança de R$ 25,00, 19/07/2026):
Validação (veja o detalhamento completo em GET acima) — inclui o caso de KYC ausente: {"success": false, "message": "EUID or end-user tax number is required to create a deposit", ...}.
Verifica o status de uma ou mais cobranças de uma vez, a partir dos IDs retornados na criação. A API é stateless — não armazena sessões de cliente. O QRCode é válido por 20 minutos; o intervalo recomendado de verificação é de 10 em 10 minutos. Limite de taxa: 60 requisições por minuto. Este endpoint não exige o parâmetro code — apenas os IDs das transações.
⚠️ A resposta é um array JSON puro, na mesma ordem de listIds — não um envelope {"success": ..., "data": {...}}. Uma versão anterior desta documentação descrevia incorretamente um objeto indexado por ID; isso foi corrigido após verificação ao vivo em 19/07/2026.
Corpo da requisição (JSON)
Campo
Tipo
Obrigatório
Descrição
listIds
array de string
Sim
Lista de IDs de transação a verificar (os mesmos id retornados em pix.data.response.id na criação das cobranças).
Resposta de sucesso (200)
Resposta real, capturada em produção para duas cobranças pendentes e um ID desconhecido (19/07/2026):
status pode ser paid, pending, refunded, expired, delayed ou not_found (ID desconhecido, date sempre null nesse caso). Quando status é refunded, o item também traz payer, payer_euid e details, além de payer_tax_numer — sim, esse nome de campo tem um erro de digitação real da API (falta o "b" de "number"), mantido de propósito na documentação porque é exatamente o que a API retorna. Exemplo:
<?php
$payload = [
'listIds' => [
'019f7bd84a99797a88b617b0be04790d',
'019f7bd854be797a94cd821a7b2404d8',
],
];
$ch = curl_init('https://blackrocket.space/api/integrated-payment/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
// A resposta é um ARRAY JSON puro, na mesma ordem de listIds — não um objeto {success, data}.
$items = json_decode($response, true);
foreach ($items as $item) {
echo "{$item['depix_id']}: {$item['status']} ({$item['date']})\n";
}
JavaScript (fetch)
const response = await fetch('https://blackrocket.space/api/integrated-payment/status', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({
listIds: [
'019f7bd84a99797a88b617b0be04790d',
'019f7bd854be797a94cd821a7b2404d8',
],
}),
});
// A resposta é um ARRAY JSON puro, na mesma ordem de listIds — não um objeto {success, data}.
const items = await response.json();
for (const { depix_id, status, date } of items) {
console.log(depix_id, status, date);
}
TypeScript
interface PaymentStatusItem {
depix_id: string;
status: 'paid' | 'pending' | 'refunded' | 'expired' | 'delayed' | 'not_found';
date: string | null;
details?: string;
payer?: string;
// Nome de campo com erro de digitação real da API — mantido como está.
payer_tax_numer?: string;
payer_euid?: string;
}
// A resposta é um ARRAY JSON puro, não um objeto { success, data }.
type PaymentStatusResponse = PaymentStatusItem[];
const response = await fetch('https://blackrocket.space/api/integrated-payment/status', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({
listIds: [
'019f7bd84a99797a88b617b0be04790d',
'019f7bd854be797a94cd821a7b2404d8',
],
}),
});
const items: PaymentStatusResponse = await response.json();
Python (requests)
import requests
payload = {
"listIds": [
"019f7bd84a99797a88b617b0be04790d",
"019f7bd854be797a94cd821a7b2404d8",
],
}
response = requests.post(
"https://blackrocket.space/api/integrated-payment/status",
json=payload,
headers={"Accept": "application/json"},
)
# A resposta é uma LISTA JSON pura, na mesma ordem de listIds — não um objeto {"success", "data"}.
items = response.json()
for item in items:
print(item["depix_id"], item["status"], item["date"])
Java (java.net.http)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String json = """
{
"listIds": [
"019f7bd84a99797a88b617b0be04790d",
"019f7bd854be797a94cd821a7b2404d8"
]
}""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://blackrocket.space/api/integrated-payment/status"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
// A resposta é um array JSON puro, na mesma ordem de listIds.
Próximos passos
API — Saques — referência dos endpoints de saque (DePix → PIX).
API — Webhooks — payload dos webhooks recebidos e como validar o callback de saída.
