SDK de Integração com a API de Pagamentos do PagSeguro

Este SDK facilita a integração com a API de pagamentos do PagSeguro (PagBank), permitindo a criação de pedidos, processamento de pagamentos, consultas e outras operações relacionadas.

Instalação

npm install pagseguro-payments

Configuração

Para utilizar o SDK, você precisa inicializar o cliente com suas credenciais do PagSeguro:

const { PagSeguroClient } = require('pagseguro-payments');

// Inicializa o cliente
const client = new PagSeguroClient({
  email: '[email protected]',
  token: 'seu-token-de-acesso',
  sandbox: true // Use false para ambiente de produção
});

Funcionalidades

Pedidos (Orders)

Criar um pedido

const orderData = {
  reference_id: 'pedido-123',
  customer: {
    name: 'José da Silva',
    email: '[email protected]',
    tax_id: '12345678909',
    phones: [
      {
        country: '55',
        area: '11',
        number: '999999999',
        type: 'MOBILE'
      }
    ]
  },
  items: [
    {
      name: 'Produto de Teste',
      quantity: 1,
      unit_amount: 1000, // R$ 10,00
      reference_id: 'produto-teste-1'
    }
  ],
  shipping: {
    address: {
      street: 'Avenida Brigadeiro Faria Lima',
      number: '1384',
      complement: 'Andar 4',
      locality: 'Pinheiros',
      city: 'São Paulo',
      region: 'São Paulo',
      region_code: 'SP',
      country: 'BRA',
      postal_code: '01452002'
    }
  },
  notification_urls: ['https://meusite.com/notificacoes']
};

// Cria o pedido
const order = await client.orders.create(orderData);
console.log('Pedido criado:', order.id);

Consultar um pedido

// Consulta um pedido pelo ID
const order = await client.orders.get('ORDE_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Pedido:', order);

Consultar pedidos por cobrança

// Consulta pedidos pelo ID da cobrança
const orders = await client.orders.getByCharge('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Pedidos:', orders);

Pagar um pedido

const paymentData = {
  charges: [
    {
      reference_id: 'pagamento-123',
      description: 'Pagamento de teste',
      amount: {
        value: 1000, // R$ 10,00
        currency: 'BRL'
      },
      payment_method: {
        type: 'CREDIT_CARD',
        installments: 1,
        capture: true,
        card: {
          number: '4111111111111111',
          exp_month: 12,
          exp_year: 2030,
          security_code: '123',
          holder: {
            name: 'José da Silva'
          }
        }
      }
    }
  ]
};

// Realiza o pagamento do pedido
const payment = await client.orders.pay('ORDE_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', paymentData);
console.log('Pagamento realizado:', payment);

Cobranças (Charges)

Consultar uma cobrança

// Consulta uma cobrança pelo ID
const charge = await client.charges.get('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Cobrança:', charge);

Capturar uma cobrança pré-autorizada

// Captura uma cobrança pré-autorizada
const charge = await client.charges.capture('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Cobrança capturada:', charge);

// Captura parcial
const partialCharge = await client.charges.capture('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', {
  amount: {
    value: 500 // R$ 5,00
  }
});
console.log('Cobrança parcialmente capturada:', partialCharge);

Cancelar uma cobrança

// Cancela uma cobrança
const charge = await client.charges.cancel('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Cobrança cancelada:', charge);

// Cancelamento parcial
const partialCharge = await client.charges.cancel('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', {
  amount: {
    value: 500 // R$ 5,00
  }
});
console.log('Cobrança parcialmente cancelada:', partialCharge);

Cancelar uma cobrança com mecanismo de tentativas

Em alguns casos, o PagSeguro pode retornar o erro refund_temporarily_unavailable ao tentar cancelar um pagamento recém-criado. Para lidar com essa situação, é recomendado implementar um mecanismo de tentativas múltiplas:

// Implementa um mecanismo de tentativas para o cancelamento
async function cancelChargeWithRetry(chargeId, cancelParams, maxAttempts = 3, waitTime = 10000) {
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    try {
      attempts++;
      console.log(`Tentativa ${attempts} de cancelar o pagamento...`);
      
      // Tenta cancelar o pagamento
      const canceledCharge = await client.charges.cancel(chargeId, cancelParams);
      console.log('Pagamento cancelado com sucesso:', canceledCharge.id);
      return canceledCharge;
      
    } catch (error) {
      const errorMessage = error.message || String(error);
      
      if (errorMessage.includes('refund_temporarily_unavailable') && attempts < maxAttempts) {
        // Se for o erro específico e ainda temos tentativas, aguarda e tenta novamente
        console.log(`Pagamento ainda não disponível para cancelamento. Aguardando ${waitTime/1000} segundos...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
      } else {
        // Se for outro erro ou acabaram as tentativas, lança o erro
        throw error;
      }
    }
  }
  
  throw new Error(`Não foi possível cancelar o pagamento após ${maxAttempts} tentativas.`);
}

// Exemplo de uso
try {
  const cancelParams = { amount: { value: 1000 } };
  const canceledCharge = await cancelChargeWithRetry('CHAR_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', cancelParams);
  console.log('Cobrança cancelada com sucesso:', canceledCharge);
} catch (error) {
  console.error('Erro ao cancelar cobrança:', error.message);
}

Criar sessão para autenticação 3DS

// Cria uma sessão para autenticação 3DS
const session = await client.charges.create3DSSession();
console.log('Sessão 3DS:', session);

Divisão de pagamentos

// Consulta uma divisão de pagamento
const split = await client.charges.getSplit('SPLIT_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Divisão de pagamento:', split);

// Libera a custódia de uma divisão de pagamento
await client.charges.releaseSplitCustody('SPLIT_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX');
console.log('Custódia liberada com sucesso');

Exemplos

Veja exemplos completos na pasta examples:

• Exemplos de Pedidos
• Exemplos de Cobranças

Ambiente de Testes

Para testar o SDK, você pode usar o ambiente de sandbox do PagSeguro. Configure suas credenciais de sandbox no arquivo .env.test:

[email protected]
PAGSEGURO_TOKEN=seu-token-de-sandbox

Documentação da API

Para mais informações sobre a API do PagSeguro, consulte a documentação oficial.

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para mais detalhes.