Transações - Upay Gateway API

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 '{
    "product": "Pedido #001",
    "paymentMethod": "PIX",
    "amountCents": 9900,
    "clientName": "João Silva",
    "clientEmail": "joao@example.com",
    "clientPhone": "11999999999",
    "clientDocument": "12345678900"
  }'

Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayId": "52a8d85b-160b-4f06-b7cb-34845c1955f2",
    "amountCents": 9900,
    "amount": 99.00,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "status": "PENDING",
    "pixCopiaECola": "00020101021226940014br.gov.bcb.pix...",
    "pixExpiresAt": "2025-12-30T01:00:00-03:00",
    "client": {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "document": "12345678900"
    },
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}

O campo displayId é preenchido com o ID externo gerado pela adquirente após o processamento. O campo pixCopiaECola contém o código PIX copia-e-cola pronto para uso.

Campos disponíveis

Campos obrigatórios

Campo	Tipo	Descrição
`product`	string	Nome ou descrição do produto/serviço. Máximo 255 caracteres.
`amountCents`	number	Valor em centavos. Exemplo: 9900 = R$ 99,00.
`clientName`	string	Nome completo do cliente. Máximo 255 caracteres.
`clientEmail`	string	Email válido do cliente.
`clientDocument`	string	CPF ou CNPJ do cliente (apenas números). Mínimo 11 dígitos.

Campos opcionais

Campo	Tipo	Descrição	Padrão
`paymentMethod`	string	Método de pagamento: `"PIX"`, `"CARD"`, `"BOLETO"`.	`"PIX"`
`clientPhone`	string	Telefone do cliente (apenas números). Exemplo: `11999999999`.	—
`installments`	number	Número de parcelas (apenas cartão). Mínimo: 1, Máximo: 12.	1
`paymentLinkId`	string (UUID)	ID do link de pagamento associado.	—
`dueDate`	string (ISO 8601)	Data de vencimento da cobrança.	—
`metadata`	object	Dados adicionais personalizados (ex: `orderId`, `source`).	—
`postbackUrl`	string (URL)	URL para receber notificações de mudança de status da transação.	—
`trackingParams`	object	Parâmetros UTM para rastreamento de campanhas.	—

📖 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({
    product: 'Curso Online',
    paymentMethod: 'CARD',
    amountCents: 19900, // R$ 199,00
    installments: 3,
    clientName: 'Maria Santos',
    clientEmail: 'maria@example.com',
    clientPhone: '11988888888',
    clientDocument: '98765432100'
  })
});

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({
    product: 'Assinatura Mensal',
    paymentMethod: 'BOLETO',
    amountCents: 29900, // R$ 299,00
    clientName: 'Pedro Oliveira',
    clientEmail: 'pedro@example.com',
    clientPhone: '11977777777',
    clientDocument: '12345678900'
  })
});

Transação com Metadata (integração de parceiros)

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({
    product: 'Pedido #4836572',
    paymentMethod: 'PIX',
    amountCents: 670000, // R$ 6.700,00
    clientName: 'Ana Costa',
    clientEmail: 'ana@example.com',
    clientPhone: '11966666666',
    clientDocument: '11122233344',
    metadata: {
      orderId: '4836572',
      source: 'checkout-parceiro',
      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": "joao@example.com"
      },
      "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: Código copia-e-cola e data de expiração
Webhook: transaction.completed quando confirmado

{
  "pixCopiaECola": "00020101021226940014br.gov.bcb.pix...",
  "pixExpiresAt": "2025-12-30T01:00:00-03:00"
}

Cartão de Crédito

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

Cartão de Débito

Parcelamento: Não disponível
Confirmação: Imediata
Retorno: Status da autorização
Webhook: transaction.completed ou transaction.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: transaction.completed quando compensado

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

Postback URL

Se você prefere receber notificações de status por transação sem precisar cadastrar uma assinatura de webhook global, use o campo postbackUrl na criação da transação. Quando o status mudar para COMPLETED ou FAILED, a UPay enviará automaticamente um POST para a URL informada com o seguinte payload:

{
  "id": "5e1f52d9-1477-414c-a113-38dd87290ede",
  "displayId": "52a8d85b-160b-4f06-b7cb-34845c1955f2",
  "status": "COMPLETED",
  "amountCents": 9900,
  "amount": 99.00,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "product": "Pedido #001",
  "client": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "phone": "11999999999"
  },
  "createdAt": "2025-12-30T00:00:00.000Z",
  "updatedAt": "2025-12-30T00:01:00.000Z"
}

O cabeçalho X-Webhook-Signature é enviado com assinatura HMAC-SHA256 para validação de autenticidade (mesmo formato dos webhooks). Seu endpoint deve responder com status 2xx para confirmar o recebimento.

curl -X POST "https://upay-sistema-api.onrender.com/api/v1/transactions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Pedido #001",
    "amountCents": 9900,
    "clientName": "João Silva",
    "clientEmail": "joao@example.com",
    "clientDocument": "12345678900",
    "postbackUrl": "https://meusite.com.br/postback/upay"
  }'

🔔 Webhooks

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

// Eventos disponíveis
const events = [
  'transaction.completed', // Pagamento confirmado
  'transaction.failed',    // Pagamento falhou
  'transaction.created',   // Transação criada
  'transaction.updated',   // Status atualizado
];

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

​Visão geral

​Pré-requisitos

​Funcionalidades

​Criando uma transação

​Requisição Básica - PIX

​Resposta

​Campos disponíveis

​Campos obrigatórios

​Campos opcionais

​📖 Exemplos Completos

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

​Transação com Boleto

​Transação com Metadata (integração de parceiros)

​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

​Postback URL

​🔔 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

Visão geral

Pré-requisitos

Funcionalidades

Criando uma transação

Requisição Básica - PIX

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

📖 Exemplos Completos

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

Transação com Boleto

Transação com Metadata (integração de parceiros)

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

Postback URL

🔔 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