Skip to main content

​
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

CampoTipoDescrição
productstringNome ou descrição do produto/serviço. Máximo 255 caracteres.
amountCentsnumberValor em centavos. Exemplo: 9900 = R$ 99,00.
clientNamestringNome completo do cliente. Máximo 255 caracteres.
clientEmailstringEmail válido do cliente.
clientDocumentstringCPF ou CNPJ do cliente (apenas números). Mínimo 11 dígitos.

​
Campos opcionais

CampoTipoDescriçãoPadrão
paymentMethodstringMétodo de pagamento: "PIX", "CARD", "BOLETO"."PIX"
clientPhonestringTelefone do cliente (apenas números). Exemplo: 11999999999.—
installmentsnumberNúmero de parcelas (apenas cartão). Mínimo: 1, Máximo: 12.1
paymentLinkIdstring (UUID)ID do link de pagamento associado.—
dueDatestring (ISO 8601)Data de vencimento da cobrança.—
metadataobjectDados adicionais personalizados (ex: orderId, source).—
postbackUrlstring (URL)URL para receber notificações de mudança de status da transação.—
trackingParamsobjectParâ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

StatusDescriçãoAção
PENDINGAguardando pagamentoAguardar confirmação
PROCESSINGProcessando pagamentoAguardar processamento
COMPLETEDPagamento confirmadoLiberar produto/serviço
FAILEDPagamento falhouTentar novamente
CANCELLEDTransação canceladaCriar nova transação
REFUNDEDPagamento reembolsadoRegistrar reembolso
EXPIREDTransação expiradaCriar 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

  1. Sempre use webhooks: Não confie apenas em polling para verificar status
  2. Armazene o ID da transação: Guarde o id e displayId no seu banco de dados
  3. Trate erros adequadamente: Implemente retry com backoff exponencial
  4. Valide dados do cliente: Verifique CPF/CNPJ, email e telefone antes de enviar
  5. Use metadata: Armazene informações adicionais para rastreamento
  6. Monitore expiração: PIX expira em 30 minutos, boleto em 3 dias
  7. 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