Transações

Visão geral

As Transações representam todas as operações de pagamento realizadas através da Upay Gateway API. Cada transação contém informações completas sobre o pagamento, incluindo método utilizado, status, valores e dados do cliente.

Pré-requisitos

Antes de começar, você precisa:

Uma conta ativa na Upay
Sua API Key configurada (veja Autenticação)
Conhecimento básico de APIs REST

Funcionalidades

Múltiplos métodos de pagamento: PIX, Cartão de Crédito/Débito, Boleto
Rastreamento em tempo real: Acompanhe o status de cada transação
Histórico completo: Consulte todas as transações com paginação
Detalhes do cliente: Informações completas do pagador
Webhooks: Receba notificações automáticas de mudanças de status
Filtros avançados: Busque por status, método de pagamento, período e mais

Criando uma transação

Requisição Básica - PIX

curl -X POST "https://upay-sistema-api.onrender.com/api/v1/transactions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
    "paymentMethod": "PIX",
    "amountCents": 9900,
    "client": {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "+5511999999999",
      "document": "12345678900"
    }
  }'

Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayId": "TRX-2025-001234",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440001",
    "amountCents": 9900,
    "amount": 99.00,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "status": "PENDING",
    "pixQrCode": "00020126580014br.gov.bcb.pix...",
    "pixQrCodeUrl": "https://api.qrserver.com/v1/create-qr-code/?data=...",
    "pixExpiresAt": "2025-12-30T01:00:00.000Z",
    "client": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "+5511999999999",
      "document": "12345678900"
    },
    "createdAt": "2025-12-30T00:00:00.000Z",
    "updatedAt": "2025-12-30T00:00:00.000Z"
  }
}

Campos disponíveis

Campos obrigatórios

Campo	Tipo	Descrição
`paymentLinkId`	string	ID do link de pagamento associado. UUID válido.
`paymentMethod`	string	Método de pagamento. Valores: “PIX”, “CREDIT_CARD”, “DEBIT_CARD”, “BOLETO”.
`amountCents`	number	Valor em centavos. Exemplo: 9900 = R $99,00. Mínimo: 100 (R$ 1,00).
`client`	object	Dados do cliente (veja abaixo).

Dados do cliente (`client`)

Campo	Tipo	Descrição	Obrigatório
`name`	string	Nome completo do cliente. Máximo 255 caracteres.	Sim
`email`	string	Email válido do cliente.	Sim
`phone`	string	Telefone com código do país. Formato: +5511999999999.	Sim
`document`	string	CPF ou CNPJ (apenas números).	Sim
`address`	object	Endereço completo (obrigatório para boleto).	Condicional

Endereço (`address`)

Campo	Tipo	Descrição
`street`	string	Logradouro.
`number`	string	Número.
`complement`	string	Complemento (opcional).
`neighborhood`	string	Bairro.
`city`	string	Cidade.
`state`	string	Estado (UF).
`zipCode`	string	CEP (apenas números).

Campos opcionais

Campo	Tipo	Descrição	Padrão
`currency`	string	Código da moeda. Atualmente apenas “BRL”.	”BRL”
`installments`	number	Número de parcelas (apenas cartão de crédito). Mínimo: 1, Máximo: 12.	1
`metadata`	object	Dados adicionais personalizados.

📖 Exemplos Completos

Transação com Cartão de Crédito

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentLinkId: 'link-id-aqui',
    paymentMethod: 'CREDIT_CARD',
    amountCents: 19900, // R$ 199,00
    installments: 3,
    client: {
      name: 'Maria Santos',
      email: '[email protected]',
      phone: '+5511988888888',
      document: '98765432100'
    },
    card: {
      number: '4111111111111111',
      holderName: 'MARIA SANTOS',
      expiryMonth: '12',
      expiryYear: '2028',
      cvv: '123'
    }
  })
});

Transação com Boleto

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentLinkId: 'link-id-aqui',
    paymentMethod: 'BOLETO',
    amountCents: 29900, // R$ 299,00
    client: {
      name: 'Pedro Oliveira',
      email: '[email protected]',
      phone: '+5511977777777',
      document: '12345678900',
      address: {
        street: 'Rua das Flores',
        number: '123',
        complement: 'Apto 45',
        neighborhood: 'Centro',
        city: 'São Paulo',
        state: 'SP',
        zipCode: '01310100'
      }
    }
  })
});

Transação com Metadata

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentLinkId: 'link-id-aqui',
    paymentMethod: 'PIX',
    amountCents: 9900,
    client: {
      name: 'Ana Costa',
      email: '[email protected]',
      phone: '+5511966666666',
      document: '11122233344'
    },
    metadata: {
      orderId: 'ORD-2025-001',
      customerId: 'CUST-123',
      source: 'website',
      campaign: 'black-friday'
    }
  })
});

Consultando transações

Listar Todas as Transações

curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "displayId": "TRX-2025-001234",
      "amountCents": 9900,
      "amount": 99.00,
      "currency": "BRL",
      "paymentMethod": "PIX",
      "status": "COMPLETED",
      "client": {
        "name": "João Silva",
        "email": "[email protected]"
      },
      "createdAt": "2025-12-30T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Buscar Transação Específica

curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

Filtros Disponíveis

# Filtrar por status
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions?status=COMPLETED" \
  -H "Authorization: Bearer SUA_API_KEY"

# Filtrar por método de pagamento
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions?paymentMethod=PIX" \
  -H "Authorization: Bearer SUA_API_KEY"

# Filtrar por período
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions?startDate=2025-01-01&endDate=2025-12-31" \
  -H "Authorization: Bearer SUA_API_KEY"

# Combinar filtros
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/transactions?status=COMPLETED&paymentMethod=PIX&page=1&limit=50" \
  -H "Authorization: Bearer SUA_API_KEY"

📊 Status da Transação

Status	Descrição	Ação
`PENDING`	Aguardando pagamento	Aguardar confirmação
`PROCESSING`	Processando pagamento	Aguardar processamento
`COMPLETED`	Pagamento confirmado	Liberar produto/serviço
`FAILED`	Pagamento falhou	Tentar novamente
`CANCELLED`	Transação cancelada	Criar nova transação
`REFUNDED`	Pagamento reembolsado	Registrar reembolso
`EXPIRED`	Transação expirada	Criar nova transação

Métodos de pagamento

PIX

Tempo de expiração: 30 minutos (padrão)
Confirmação: Instantânea
Retorno: QR Code e código copia-e-cola
Webhook: payment.completed quando confirmado

{
  "pixQrCode": "00020126580014br.gov.bcb.pix...",
  "pixQrCodeUrl": "https://api.qrserver.com/v1/create-qr-code/?data=...",
  "pixExpiresAt": "2025-12-30T01:00:00.000Z"
}

Cartão de Crédito

Parcelamento: Até 12x
Confirmação: Imediata ou em até 2 dias úteis
Retorno: Status da autorização
Webhook: payment.completed ou payment.failed

Cartão de Débito

Parcelamento: Não disponível
Confirmação: Imediata
Retorno: Status da autorização
Webhook: payment.completed ou payment.failed

Boleto

Vencimento: 3 dias úteis (padrão)
Confirmação: 1-3 dias úteis após pagamento
Retorno: URL do boleto e código de barras
Webhook: payment.completed quando compensado

{
  "boletoUrl": "https://boleto.upaybr.com/...",
  "boletoBarcode": "34191.79001 01043.510047 91020.150008 1 84350000002000",
  "boletoExpiresAt": "2025-01-02T23:59:59.000Z"
}

🔔 Webhooks

Configure webhooks para receber notificações automáticas sobre mudanças de status:

// Eventos disponíveis
const events = [
  'payment.completed',   // Pagamento confirmado
  'payment.failed',      // Pagamento falhou
  'payment.pending',     // Pagamento pendente
  'payment.refunded',    // Pagamento reembolsado
  'payment.cancelled'    // Pagamento cancelado
];

Veja o guia completo de webhooks para mais detalhes.

Segurança

Validação de Dados

Sempre valide os dados antes de criar uma transação:

function validateTransaction(data) {
  // Validar valor mínimo
  if (data.amountCents < 100) {
    throw new Error('Valor mínimo: R$ 1,00');
  }
  
  // Validar email
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(data.client.email)) {
    throw new Error('Email inválido');
  }
  
  // Validar CPF/CNPJ
  if (!isValidDocument(data.client.document)) {
    throw new Error('CPF/CNPJ inválido');
  }
  
  return true;
}

Proteção contra Duplicatas

Use metadata para rastrear transações e evitar duplicatas:

const transaction = await upay.transactions.create({
  // ... outros campos
  metadata: {
    orderId: 'ORD-2025-001',
    idempotencyKey: generateUniqueKey()
  }
});

Boas práticas

Sempre use webhooks: Não confie apenas em polling para verificar status
Armazene o ID da transação: Guarde o id e displayId no seu banco de dados
Trate erros adequadamente: Implemente retry com backoff exponencial
Valide dados do cliente: Verifique CPF/CNPJ, email e telefone antes de enviar
Use metadata: Armazene informações adicionais para rastreamento
Monitore expiração: PIX expira em 30 minutos, boleto em 3 dias
Implemente timeout: Configure timeout adequado nas requisições

Casos de uso

E-commerce

Processe pagamentos de produtos com múltiplos métodos e parcelamento.

Assinaturas

Crie transações recorrentes para cobranças mensais.

Marketplace

Gerencie transações entre múltiplos vendedores.

Doações

Aceite doações via PIX com confirmação instantânea.

Serviços

Cobre por serviços prestados com boleto ou cartão.

📚 Próximos Passos

Referência da API

Veja todos os endpoints disponíveis

Links de pagamento

Crie links para receber pagamentos

Webhooks

Configure notificações em tempo real

Tratamento de Erros

Entenda os códigos de erro

Introdução

Recursos

Guias

Link de pagamento

Produtos

Clientes

Cupom

Saldo

Webhooks

​Visão geral

​Pré-requisitos

​Funcionalidades

​Criando uma transação

​Requisição Básica - PIX

​Resposta

​Campos disponíveis

​Campos obrigatórios

​Dados do cliente (client)

​Endereço (address)

​Campos opcionais

​📖 Exemplos Completos

​Transação com Cartão de Crédito

​Transação com Boleto

​Transação com Metadata

​Consultando transações

​Listar Todas as Transações

​Resposta

​Buscar Transação Específica

​Filtros Disponíveis

​📊 Status da Transação

​Métodos de pagamento

​PIX

​Cartão de Crédito

​Cartão de Débito

​Boleto

​🔔 Webhooks

​Segurança

​Validação de Dados

​Proteção contra Duplicatas

​Boas práticas

​Casos de uso

​E-commerce

​Assinaturas

​Marketplace

​Doações

​Serviços

​📚 Próximos Passos

Referência da API

Links de pagamento

Webhooks

Tratamento de Erros

Visão geral

Pré-requisitos

Funcionalidades

Criando uma transação

Requisição Básica - PIX

Resposta

Campos disponíveis

Campos obrigatórios

Dados do cliente (`client`)

Endereço (`address`)

Campos opcionais

📖 Exemplos Completos

Transação com Cartão de Crédito

Transação com Boleto

Transação com Metadata

Consultando transações

Listar Todas as Transações

Resposta

Buscar Transação Específica

Filtros Disponíveis

📊 Status da Transação

Métodos de pagamento

PIX

Cartão de Crédito

Cartão de Débito

Boleto

🔔 Webhooks

Segurança

Validação de Dados

Proteção contra Duplicatas

Boas práticas

Casos de uso

E-commerce

Assinaturas

Marketplace

Doações

Serviços

📚 Próximos Passos