Public docs
Try it
Endpoint
Credentials
Secret key
Authorization
Request
Response
—
Click "Try it" to start a request and see the response here.

Payments API

Introdução

Esta API foi desenvolvida seguindo padrões REST. Todas as respostas são fornecidas no formato JSON.

Autenticação

Para acessar a API, autentique-se utilizando sua chave secreta no padrão Basic Auth.

  • Envie o header Authorization no formato:
    • Authorization: Basic <base64("x:{SECRET_KEY}")>

Exemplos (Basic Auth)

Substitua:

  • {BASE_URL}: URL do seu ambiente (ex.: http://localhost:3000)
  • {SECRET_KEY}: sua chave secreta

cURL

curl -X GET "{BASE_URL}/v1/company" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)"

Node.js (axios)

import axios from "axios";

const baseURL = "{BASE_URL}";
const secretKey = "{SECRET_KEY}";

const auth = Buffer.from(`x:${secretKey}`).toString("base64");

const api = axios.create({
  baseURL,
  headers: { Authorization: `Basic ${auth}` },
});

const { data } = await api.get("/v1/company");
console.log(data);

Python (requests)

import base64
import requests

base_url = "{BASE_URL}"
secret_key = "{SECRET_KEY}"

auth = base64.b64encode(f"x:{secret_key}".encode("utf-8")).decode("utf-8")
headers = { "Authorization": f"Basic {auth}" }

r = requests.get(f"{base_url}/v1/company", headers=headers, timeout=20)
print(r.status_code, r.text)

Webhooks (postbacks para o gateway)

Ao criar uma transação (POST /v1/transactions), você informa postbackUrl (ou callbackUrl). Sempre que o status mudar, a Subadquirente envia um POST para essa URL com o padrão oficial Paynux Sub — o mesmo para qualquer adquirente integrada.

Documentação completa: WEBHOOK-GATEWAY.md

Resumo do corpo JSON:

{
  "data": {
    "id": "<mesmo id retornado na criação da transação>",
    "status": "paid",
    "e2e": "<opcional: ID E2E do PIX quando disponível>"
  }
}
  • id: use para localizar a transação no seu sistema (é o campo id da resposta de criação).
  • status: status em minúsculas.
  • e2e: só vem quando a adquirente informar; caso contrário o campo não é enviado.

Status possíveis (exemplos)

  • pending: em processamento
  • paid: pagamento efetivado
  • refused: pagamento negado
  • refunded: valor devolvido
  • cancelled: operação encerrada
  • chargeback: estorno / contestação

(Os valores exatos dependem da adquirente e das configurações da sub.)

Endpoints

Dados da empresa

GET /v1/company

Retorna os dados da empresa vinculada à chave.

Exemplos

curl -X GET "{BASE_URL}/v1/company" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)"

Saldo disponível

GET /v1/balance/available

Retorna o saldo disponível.

Exemplos

curl -X GET "{BASE_URL}/v1/balance/available" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)"

Criar venda (PIX)

POST /v1/transactions

Cria uma transação de pagamento via PIX.

Body (JSON)

Campo Tipo Obrigatório Descrição
paymentMethod string Sim Meio de pagamento. Valor: pix
amount integer Sim Valor total em centavos (ex.: 100 = R$ 1,00)
customer object Sim Dados do cliente
items array Sim Itens vendidos (mín. 1 item)
shipping object Condicional Obrigatório caso algum item seja físico
isInfoProducts boolean Não true = produto físico, false = digital
postbackUrl string Não URL para receber atualizações desta transação
idSeller string Não Campo customizado
nameSeller string Não Campo customizado
emailSeller string Não Campo customizado

items[] (campos obrigatórios)

Além dos campos comuns, a validação exige:

  • title (string)
  • description (string)
  • unitPrice (integer, em centavos)
  • quantity (integer)
  • tangible (boolean)

Exemplo de request

{
  "paymentMethod": "pix",
  "amount": 2000,
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "phone": "11999999999",
    "document": { "type": "cpf", "number": "00000000000" },
    "address": {
      "street": "Rua Exemplo",
      "streetNumber": "100",
      "complement": "Apto 101",
      "zipCode": "12345678",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "Brasil"
    }
  },
  "items": [
    {
      "title": "Produto Teste",
      "description": "Descrição do produto",
      "unitPrice": 2000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "postbackUrl": "https://exemplo.com/webhook"
}

Exemplos (cURL / Node / Python)

cURL

curl -X POST "{BASE_URL}/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)" \
  --data '{
    "paymentMethod": "pix",
    "amount": 2000,
    "customer": {
      "name": "Cliente Exemplo",
      "email": "cliente@exemplo.com",
      "phone": "11999999999",
      "document": { "type": "cpf", "number": "00000000000" },
      "address": {
        "street": "Rua Exemplo",
        "streetNumber": "100",
        "complement": "Apto 101",
        "zipCode": "12345678",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil"
      }
    },
    "items": [
      {
        "title": "Produto Teste",
        "description": "Descrição do produto",
        "unitPrice": 2000,
        "quantity": 1,
        "tangible": false
      }
    ],
    "postbackUrl": "https://exemplo.com/webhook"
  }'

Node.js (axios)

import axios from "axios";

const baseURL = "{BASE_URL}";
const secretKey = "{SECRET_KEY}";
const auth = Buffer.from(`x:${secretKey}`).toString("base64");

const api = axios.create({
  baseURL,
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${auth}`,
  },
});

const payload = {
  paymentMethod: "pix",
  amount: 2000,
  customer: {
    name: "Cliente Exemplo",
    email: "cliente@exemplo.com",
    phone: "11999999999",
    document: { type: "cpf", number: "00000000000" },
    address: {
      street: "Rua Exemplo",
      streetNumber: "100",
      complement: "Apto 101",
      zipCode: "12345678",
      neighborhood: "Centro",
      city: "São Paulo",
      state: "SP",
      country: "Brasil",
    },
  },
  items: [
    {
      title: "Produto Teste",
      description: "Descrição do produto",
      unitPrice: 2000,
      quantity: 1,
      tangible: false,
    },
  ],
  postbackUrl: "https://exemplo.com/webhook",
};

const { data } = await api.post("/v1/transactions", payload);
console.log(data);

Python (requests)

import base64
import requests

base_url = "{BASE_URL}"
secret_key = "{SECRET_KEY}"
auth = base64.b64encode(f"x:{secret_key}".encode("utf-8")).decode("utf-8")

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Basic {auth}"
}

payload = {
  "paymentMethod": "pix",
  "amount": 2000,
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "phone": "11999999999",
    "document": { "type": "cpf", "number": "00000000000" },
    "address": {
      "street": "Rua Exemplo",
      "streetNumber": "100",
      "complement": "Apto 101",
      "zipCode": "12345678",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "Brasil"
    }
  },
  "items": [
    {
      "title": "Produto Teste",
      "description": "Descrição do produto",
      "unitPrice": 2000,
      "quantity": 1,
      "tangible": False
    }
  ],
  "postbackUrl": "https://exemplo.com/webhook"
}

r = requests.post(f"{base_url}/v1/transactions", json=payload, headers=headers, timeout=20)
print(r.status_code, r.text)

Response 200 (exemplo)

{
  "message": "Successfully registered sale",
  "insertId": 999,
  "transaction": {
    "id": "11111111-2222-3333-4444-555555555555",
    "amount": 2000,
    "paymentMethod": "PIX",
    "status": "waiting_payment",
    "createdAt": "2025-05-22T10:44:04-03:00",
    "updatedAt": "2025-05-22T10:44:04-03:00",
    "customer": { },
    "pix": {
      "qrcode": "00020101021226...",
      "expirationDate": "2025-05-24T00:00:00-03:00",
      "end2EndId": null,
      "receiptUrl": null
    },
    "items": [ ]
  }
}

Listar vendas

GET /v1/all/transactions

Query params

  • page (integer, default 1)
  • pageSize (integer, default 20, máximo 50)

Exemplos

curl -X GET "{BASE_URL}/v1/all/transactions?page=1&pageSize=20" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)"

Listar infrações

GET /v1/infringement

Query params

  • page (integer, default 1)
  • pageSize (integer, default 20, máximo 50)

Exemplos

curl -X GET "{BASE_URL}/v1/infringement?page=1&pageSize=20" \
  -H "Authorization: Basic $(printf 'x:{SECRET_KEY}' | base64)"

Observação (modelo de negócio)

A precificação (por exemplo, repassar uma taxa diferente ao gateway) deve ser tratada por configuração/contrato e não altera o formato do PIX gerado. O webhook e os dados de transação permanecem rastreáveis pelo status, valores e timestamps.

Atualize esta página editando docs/API.md.