Solux LogoDocumentação API
Voltar ao site

Documentação Solux API

Bem-vindo à documentação oficial da API Solux. Aqui você encontrará tudo o que precisa para integrar pagamentos PIX em sua aplicação.

PIX - Pagamentos Instantâneos

Receba pagamentos em tempo real via PIX com QR Code dinâmico, chave PIX e notificações instantâneas via webhook.

URL Base

url
https://soluxpagamentos.com

Todas as requisições devem usar esta URL como base.

Formato de Resposta

Todas as respostas da API são retornadas no formato JSON. Em caso de erro, seguimos o padrão RFC 7807.

Exemplo de Resposta de Sucesso

json
{
  "data": {
    "id": "f2d96218-6635-4839-81d7-9f2d5aaf4f14",
    "status": "WAITING_PAYMENT",
    "paymentMethod": "PIX",
    "amount": 500
  },
  "status": 200,
  "message": "Transação criada com sucesso."
}

Autenticação

A API utiliza autenticação via X-Client-Id e X-API-Key. Você deve incluir essas credenciais em todas as requisições.

Headers Obrigatórios

http
X-Client-Id: e1c98954cc404cbcb2868af9b40c7a33
X-API-Key: sua-api-key-secreta
Content-Type: application/json
Accept: application/json

Como Obter Credenciais

1

Acesse o painel em https://soluxpagamentos.com

2

Navegue até Configurações → API & Integrações

3

Copie o Client ID (público e único para sua aplicação)

4

Clique em Gerar Nova Chave para criar uma API Key

5

Guarde sua API Key em um local seguro (ela será exibida apenas uma vez)

Importante: A API Key é secreta e deve ser armazenada com segurança. Nunca a compartilhe ou exponha em código cliente.

Tratamento de Erros

A API Solux segue o padrão RFC 7807 (Problem Details for HTTP APIs) para retornar erros:

json
{
  "type": "https://soluxpagamentos.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Os dados fornecidos são inválidos.",
  "instance": "/api/v1/transactions/create",
  "errors": [
    {
      "field": "amount",
      "message": "O valor deve ser maior que zero."
    }
  ],
  "traceId": "00-abc123-def456-00"
}

Códigos de Status HTTP

400

Bad Request - Requisição inválida. Verifique os parâmetros enviados.

401

Unauthorized - Credenciais ausentes ou inválidas.

403

Forbidden - Acesso negado ao recurso.

404

Not Found - Recurso não encontrado.

429

Too Many Requests - Limite de requisições excedido.

500

Internal Server Error - Erro interno do servidor.

Status de Transações e Webhooks

Entenda os diferentes status que uma transação ou saque pode assumir durante seu ciclo de vida.

Status Possíveis

awaiting

A transação foi criada e está aguardando o pagamento do cliente. O QR Code PIX foi gerado e está disponível para pagamento.

pending

A solicitação foi recebida e está sendo processada. Para saques, significa que o pedido foi enviado ao provedor e aguarda confirmação.

successful

A operação foi concluída com sucesso. Para depósitos (PixIn), o pagamento foi confirmado. Para saques (CashOut), o valor foi transferido para a conta destino.

failure

A operação falhou ou foi rejeitada. Isso pode ocorrer por diversos motivos como: saldo insuficiente, chave PIX inválida, conta destino inválida, ou erro no provedor.

refunded

A transação foi estornada. O valor foi devolvido ao pagador original. Isso pode ocorrer por solicitação do cliente ou por motivos operacionais.

Fluxo de Status

PIX In (Depósitos)

awaitingpendingsuccessful

Cash Out (Saques)

pendingsuccessful

Criar Transação (PIX)

Cria uma transação de pagamento via PIX. Valores monetários são sempre em centavos (inteiros).

POST/api/v1/transactions/create

Headers Obrigatórios

http
Content-Type: application/json
Accept: application/json
X-Client-Id: <client_id>
X-API-Key: <api_key>
Idempotency-Key: tx_<unique> (Recomendado)

Request Body

Importante: Todos os valores monetários (amount, unitPrice, fee) devem ser informados em centavos. Exemplo: R$ 5,00 = 500

json
{
  "amount": 500,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "installments": 1,
  "customer": {
    "id": "CUST-1729131560000",
    "name": "Joao Teste",
    "email": "joao.teste@exemplo.com",
    "document": { "number": "24577481600", "type": "CPF" },
    "phone": "11987654321",
    "externalRef": "LEAD-1234"
  },
  "items": [
    {
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }
  ],
  "pix": { "expiresInDays": 1 },
  "postbackUrl": "https://seu-site.com/webhook",
  "metadata": "{\"origem\":\"n8n\",\"ambiente\":\"producao\"}",
  "traceable": true,
  "ip": "177.123.45.67"
}

Response 200 (PIX)

json
{
  "data": {
    "id": "ebe485c6-cdf4-4736-aa3e-464044c4d4eb",
    "externalRef": "686725",
    "amount": 500,
    "refundedAmount": 0,
    "providerCompanyId": "b6877393-8a98-4e4e-8a20-e086aacf3d8c",
    "companyId": 1,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "https://seu-site.com/webhook",
    "metadata": null,
    "traceable": true,
    "createdAt": "2025-10-17T01:38:51.943Z",
    "updatedAt": "2025-10-17T01:38:51.943Z",
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix...",
      "url": null,
      "expirationDate": "2025-10-18T01:38:51.943Z"
    }
  },
  "status": 200,
  "message": "Transação criada com sucesso."
}

Exemplo cURL

bash
curl -X POST https://soluxpagamentos.com/api/v1/transactions/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "Idempotency-Key: tx_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "customer": {
      "id": "CUST-123",
      "name": "Joao",
      "email": "joao@ex.com",
      "document": {"number": "24577481600", "type": "CPF"},
      "phone": "11987654321"
    },
    "items": [{
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true
    }],
    "pix": { "expiresInDays": 1 }
  }'

Listar Transações

Consulte todas as transações da sua empresa com paginação, ordenação e filtros.

GET/api/Transaction/company/transactions

Parâmetros de Query (Opcionais)

page

Número da página (padrão: 1)

pageSize

Itens por página (padrão: 50, max: 100)

sort

Ordenação: createdAt_desc ou createdAt_asc

Exemplo JavaScript

javascript
const CLIENT_ID = 'e1c98954cc404cbcb2868af9b40c7a33';
const API_KEY = 'sua-api-key-secreta';

const query = {
  page: 1,
  pageSize: 50,
  sort: 'createdAt_desc',
};

const queryString = Object.entries(query)
  .filter(([, v]) => v !== undefined && v !== null)
  .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
  .join('&');

const response = await fetch(
  `https://soluxpagamentos.com/api/Transaction/company/transactions?${queryString}`,
  {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'X-Client-Id': CLIENT_ID,
      'X-API-Key': API_KEY,
    },
  }
);

const data = await response.json();
console.log('Transações:', data);

Buscar Transação por ID

Recupera os detalhes completos de uma transação específica usando seu transactionId.

GET/api/Transaction/transactionByTransactionId/{transactionId}

Exemplo cURL

bash
curl -X GET "https://soluxpagamentos.com/api/Transaction/transactionByTransactionId/QR19118133a7zYiIkam7odGU1tzpfy" \
  -H "Accept: application/json" \
  -H "X-Client-Id: e1c98954cc404cbcb2868af9b40c7a33" \
  -H "X-API-Key: sua-api-key-secreta"

Response (200 OK)

json
[
  {
    "ok": true,
    "transactionId": "QR19118133a7zYiIkam7odGU1tzpfy",
    "status": "PAID",
    "paymentMethod": "PIX",
    "amount": 2500,
    "description": "Transação PIX",
    "createdAt": "2026-02-13T14:01:42.392076",
    "paidAt": "2026-02-13T14:02:09.953202+00:00",
    "customer": {
      "id": "850797b2-e202-4bc3-b2f5-35db88c80639",
      "name": "developers test",
      "email": "joao.teste@example.com",
      "document": "24577481600"
    },
    "qrCode": "00020101021226790014br.gov.bcb.pix...",
    "qrCodeUrl": "data:image/png;base64,...",
    "metadata": null,
    "raw": {
      "data": {
        "id": "QR19118133a7zYiIkam7odGU1tzpfy",
        "internalId": 459,
        "idempotencyKey": "tx_1770991301132_866966",
        "companyId": 1,
        "leadId": "850797b2-...",
        "status": "PAID",
        "internalStatus": "Successful",
        "paymentMethod": "PIX",
        "integration": "LottoPay",
        "amount": 2500,
        "amountDecimal": 25,
        "installments": 1,
        "creditAwaiting": 0,
        "totalDeducted": 0,
        "description": "Transação PIX",
        "items": [],
        "provider": {
          "txId": "QR19118133a7zYiIkam7odGU1tzpfy",
          "endToEndId": "E2289643120260213...",
          "pixKey": null,
          "amount": 25,
          "creditedAt": "2026-02-13T14:02:09",
          "payer": {
            "name": "NOME DO PAGADOR",
            "document": "50651470862"
          },
          "receiver": {
            "name": null,
            "document": null
          }
        },
        "createdAt": "2026-02-13T14:01:42.392076",
        "updatedAt": "2026-02-13T14:02:09.953202+00:00",
        "paidAt": "2026-02-13T14:02:09.953202+00:00",
        "metadata": null
      },
      "status": 200,
      "message": "Transação recuperada com sucesso."
    },
    "url": "https://soluxpagamentos.com/api/Transaction/transactionByTransactionId/QR19118133a7zYiIkam7odGU1tzpfy"
  }
]

Status Possíveis

PENDING

Aguardando pagamento PIX

PAID

Pagamento confirmado

EXPIRED

QR Code expirado sem pagamento

REFUNDED

Pagamento estornado

Consultar Saldo (Balance)

Consulta o saldo disponível de uma empresa. Valores monetários são sempre em centavos (R$ 25,00 = 2500).

GET/api/Balance/balance/{companyId}?currency=BRL

Response (200 OK)

json
{
  "id": 1,
  "companyId": 1,
  "currency": "BRL",
  "enBalanceStatus": "Released",
  "accBalance": 5.00,
  "accBalanceCredit": 0.00,
  "accBalanceCreditAwaiting": 0.00
}

Exemplo JavaScript

javascript
const companyId = 1;
const currency = 'BRL';

const response = await fetch(
  `https://soluxpagamentos.com/api/Balance/balance/${companyId}?currency=${currency}`,
  {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'X-Client-Id': 'e1c98954cc404cbcb2868af9b40c7a33',
      'X-API-Key': 'sua-api-key-secreta'
    }
  }
);

const balance = await response.json();
console.log('Saldo disponível:', balance.accBalance);

Solicitar Saque (Withdraw)

Solicita um saque do saldo disponível da empresa. Se a requisição incluir uma chave PIX (pixKey), ela será usada prioritariamente.

POST/api/Withdraw/request

Observação: Se pixKey for omitida, o sistema automaticamente usará a chave PIX cadastrada na conta bancária (BankAccount) da empresa.

Request Body

json
{
  "amount": 2500,
  "currency": "BRL",
  "pixKey": "50651470862",
  "pixKeyType": "CPF",
  "description": "Saque teste via chave custom",
  "metadata": { "origem": "n8n", "pedidoId": 123 }
}

Exemplo cURL

bash
curl -X POST 'https://soluxpagamentos.com/api/Withdraw/request' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: e1c98954cc404cbcb2868af9b40c7a33' \
  -H 'X-API-Key: sua-api-key-secreta' \
  -H 'Idempotency-Key: wd_test_pix_custom' \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "pixKey": "50651470862",
    "pixKeyType": "CPF",
    "description": "Saque R$10 via chave custom",
    "metadata": { "origem": "n8n", "pedidoId": 123 }
  }'

Consultar Saque por Lookup

Consulta um saque por múltiplos identificadores (ID, EndToEnd, TID, ProviderPaymentId, IdempotencyKey).

GET/api/Withdraw/lookup?q={identificador}

Query Parameters

qObrigatório

Chave de busca. Pode ser: Id, ProviderEndToEndId, ProviderTid, ProviderPaymentId ou IdempotencyKey

companyId

Filtro opcional (apenas útil para Admin/Manager via JWT)

Resposta de Sucesso (200 OK)

json
{
  "ok": true,
  "withdraw": {
    "id": 1390,
    "companyId": 1,
    "value": 1112.00,
    "currency": "BRL",
    "pixKey": "12505368473",
    "pixKeyType": "CPF",
    "creditorDocument": "44444444444444",
    "enTransaction": "Successful",
    "provider": "A55",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "providerTid": "wld-00001390",
    "providerEndToEndId": "E48756121202602031458MHoTfthbxEq",
    "providerStatus": "successful",
    "providerPayload": "{... string JSON do provedor ...}"
  },
  "keys": {
    "id": 1390,
    "companyId": 1,
    "providerTid": "wld-00001390",
    "providerPaymentId": "175b4f3a-2d71-401c-9dd2-1f33cb32fc7a",
    "end2end": "E48756121202602031458MHoTfthbxEq",
    "idempotencyKey": "2ce66db9-7d2f-4761-a5d4-46799ab8709f"
  }
}

Exemplos cURL

Buscar por ID:

bash
curl -sS "https://soluxpagamentos.com/api/Withdraw/lookup?q=1390" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Buscar por EndToEnd:

bash
curl -sS "https://soluxpagamentos.com/api/Withdraw/lookup?q=E123...XYZ" \
  -H "X-Client-Id: <client_id>" \
  -H "X-API-Key: <secret>"

Webhooks

Receba notificações automáticas sobre eventos de transações e saques.

Webhook PixIn (Depósitos)

Receba notificações automáticas sempre que uma transação de entrada (PIX) mudar de status.

Pagamento Confirmado

json
{
  "object": "transaction",
  "type": "cashin",
  "status": "successful",
  "companyId": 1,
  "transactionId": "6dcf2aee0d6148e1a12b78db78",
  "subTransactionId": 41394,
  "externalRef": "LEAD-1764252408748_52740",
  "method": "pix",
  "value": 500,
  "amount": 5,
  "currency": "BRL",
  "endToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerEndToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerTxId": "6dcf2aee0d6148e1a12b78db78",
  "pixKey": "c32361fa-44de-4be7-815f-0e782a10860c",
  "payer": {
    "name": "ANGELO ALVES DE MARCHI",
    "documentId": "50651470862",
    "bankName": null,
    "ispb": null
  },
  "receiver": {
    "name": null,
    "documentId": "48969523000177"
  },
  "processedAt": "2025-11-27T11:07:14.997603Z"
}

Reenvio Automático

  • 3 tentativas automáticas (1 min / 5 min / 15 min)
  • Idempotência garantida pelo header X-Idempotency-Key

Webhook CashOut (Saques)

Receba notificações automáticas sobre o status das solicitações de saque.

POSTDefinida pelo cliente na rota /api/SendWebhook

Endpoint: URL definida pelo cliente. Exemplo: https://meusite.com.br/api/webhook/solux

Headers Obrigatórios

http
Content-Type: application/json
X-Idempotency-Key: <uuid>

Exemplo de Webhook CashOut

json
{
  "object": "withdraw",
  "type": "cashout",
  "status": "successful",
  "companyId": 1,
  "withdrawId": 7184,
  "value": 10,
  "valueInCents": 1000,
  "currency": "BRL",
  "provider": "A55",
  "providerStatus": 1,
  "providerTid": "wld-00007184",
  "providerPaymentId": "uuid-provider",
  "endToEndId": "Exxxxxxxx",
  "providerAmount": 10,
  "providerConfirmedAt": "2025-11-27T10:12:33Z",
  "providerDebitedAt": null,
  "providerPayload": { ... },
  "pixKey": "chave",
  "pixKeyType": "CPF",
  "creditorDocument": "xxx",
  "payer": {
    "name": "NOME DO BANCO/A55",
    "document": "xxx",
    "ispb": "xxxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },
  "receiver": {
    "name": "NOME DO CLIENTE",
    "document": "xxx",
    "ispb": "xxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },
  "createdAt": "2025-11-27T00:00:00Z",
  "updatedAt": "2025-11-27T00:00:00Z",
  "processedAt": "2025-11-27T00:00:00Z",
  "metadata": null
}

Quando o Webhook é Enviado

  • O saque é confirmado (successful)
  • O saque é estornado (refunded)
  • O saque é recusado (failure)

Exemplo de Resposta

json
{ "received": true, "idempotent": false }