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)

Ao registrar uma nova transação, você pode definir uma URL no campo postbackUrl. Essa URL será utilizada para enviar atualizações automáticas sempre que houver mudança no status da transação.

O payload enviado no postback segue o formato do objeto de transação (exemplo abaixo).

Status

  • waiting_payment: pagamento ainda não realizado
  • pending: em processamento
  • approved: confirmado com sucesso
  • refused: pagamento negado
  • in_protest: disputa/contestação
  • refunded: valor devolvido ao pagador
  • paid: pagamento efetivado
  • cancelled: operação encerrada sem sucesso
  • chargeback: estorno iniciado pelo cliente/instituição

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.