Documentação da API Pagjunto

Nossa API foi desenhada para ser simples e poderosa, permitindo que você integre um sistema de pagamentos compartilhados ("vaquinhas") diretamente em sua aplicação. Com poucos endpoints, você pode criar, gerenciar e ser notificado sobre pagamentos.

Autenticação

Nossa API utiliza uma chave (apiKey) para autenticar as requisições. Você pode encontrar sua chave de API no seu Dashboard de Parceiro, na aba de Configurações.

A chave deve ser enviada no corpo (body) de cada requisição que necessite de autenticação, como a criação de um pedido.

Como incluir a chave

Simplesmente adicione o par "apiKey": "sua_chave_secreta" ao objeto JSON que você envia para nossos endpoints.

Exemplo de payload JSON

// Exemplo de corpo da requisição
{
  "name": "Pedido de Exemplo",
  "totalValue": 150.00,
  "partnerId": "60d5f...",
  "apiKey": "abc-123-def-456" // <-- Sua chave aqui
}

POST Criar um Pedido

Este endpoint cria um novo pedido de pagamento compartilhado. Em resposta, você receberá um orderId único, que será usado para construir a URL de pagamento para seus clientes.

/v1/order

Parâmetros do Corpo (Body)

Parâmetro	Tipo	Descrição
name	String	Nome descritivo para o pedido (ex: "Pedido Mesa 5").
totalValue	Number	Obrigatório. Valor total a ser arrecadado.
partnerId	String	Obrigatório. ID do parceiro, obtido no seu dashboard.
apiKey	String	Obrigatório. Sua chave de API secreta.

Exemplo: JavaScript (Fetch)

const data = {
  name: 'Pedido para a Festa',
  totalValue: 250.50,
  partnerId: '60d5f1b4e6b3c1001f... ',
  apiKey: 'abc-123-def-456'
};

fetch('https://api.pagjunto.com/v1/order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
})
.then(res => res.json())
.then(orderId => {
  console.log('ID do Pedido Criado:', orderId);
  // "668ffb369c0d12e8c2d5e16a"
});

Resposta de Sucesso: 201 Created

"668ffb369c0d12e8c2d5e16a"

GET Consultar um Pedido

Utilize este endpoint para obter o status atual e todos os detalhes de um pedido existente, incluindo os pagamentos já realizados.

/v1/order

Parâmetros do Corpo (Body)

Parâmetro	Tipo	Descrição
orderId	String	Obrigatório. O ID do pedido que deseja consultar.

Exemplo: JavaScript (Fetch)

const orderId = '668ffb369c0d12e8c2d5e16a';

fetch('https://api.pagjunto.com/v1/order', {
  method: 'GET',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ orderId })
})
.then(res => res.json())
.then(pedido => console.log(pedido));

Resposta de Sucesso: 200 OK

{
  "name": "Pedido para a Festa",
  "orderId": "668ffb369...",
  "partnerId": "60d5f1b4e...",
  "totalValue": 250.5,
  "paidValue": 100,
  "status": "progress",
  "payersNames": ["João Silva"],
  "payersValues": [100],
  "payersIds": [999.999.999-33],
  "payersPhone": [(99)99999-9999],
  "createdAt": "2025-07-12T...",
  "updatedAt": "2025-07-12T..."
}

WEBHOOK Pedido Pago

Para automatizar seus processos, você pode configurar uma URL de Webhook no seu Dashboard. Nós enviaremos uma requisição POST para essa URL sempre que um pedido for totalmente pago.

Segurança

Para garantir que a requisição é genuína, todas os nossos webhooks são assinados. Nós incluímos um cabeçalho X-Pagjunto-Signature-256 na requisição.

A assinatura é um hash HMAC-SHA256, gerado usando sua apiKey como segredo e o corpo (body) da requisição como mensagem. Você deve calcular a mesma assinatura no seu servidor e comparar com a que recebeu para validar a autenticidade.

Payload do Webhook

O corpo da requisição terá a seguinte estrutura:

Parâmetro	Tipo	Descrição
event	String	Tipo do evento. Será sempre `"order.paid"`.
orderId	String	O ID único do pedido que foi pago.
totalValue	Number	O valor total do pedido.
paidAt	String	Data (ISO 8601) de quando o pedido foi pago.
payers	Array	Uma lista de objetos, cada um com `name` e `value` de cada pagador.

Exemplo: Validando o Webhook em Node.js

const crypto = require('crypto');
const express = require('express');
const app = express();

// Use o 'raw' body. Middlewares como o body-parser podem alterar o formato.
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

const PARTNER_API_KEY = 'sua_chave_secreta_aqui';

app.post('/webhook-pagjunto', (req, res) => {
  const signature = req.get('X-Pagjunto-Signature-256');
  const expectedSignature = crypto
    .createHmac('sha256', PARTNER_API_KEY)
    .update(req.rawBody) // Importante usar o corpo bruto!
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(400).send('Assinatura inválida.');
  }

  // Assinatura válida. Processe o evento.
  const { event, orderId } = req.body;
  
  if (event === 'order.paid') {
    console.log(`Pedido ${orderId} foi pago!`);
    // Execute sua lógica de negócio (ex: liberar produto, enviar email).
  }

  res.status(200).send();
});