Skip to main content

Bem-vindo ao Glossário

Encontrou um termo que não conhece? Este glossário explica os principais conceitos e termos técnicos usados na documentação da Upay de forma simples e direta.

​
Autenticação e Segurança

​
Bearer Token

Também chamado de API Key ou chave de API, é o método de autenticação usado para autorizar suas requisições à API da Upay. A chave é enviada no header HTTP Authorization: Bearer SUA_API_KEY. Sem uma chave válida, nenhuma requisição será aceita.

​
Webhook Secret

String secreta configurada ao criar uma assinatura de webhook. Garante que as notificações recebidas vieram realmente da Upay. Deve ser validada no seu servidor para evitar requisições maliciosas.

​
HTTPS

Versão segura do HTTP que usa criptografia TLS/SSL. Todos os endpoints da Upay e as URLs de webhook precisam obrigatoriamente usar HTTPS.

​
TLS/SSL

Protocolos de segurança que criptografam a comunicação na internet. Utilizados em todas as conexões com a API da Upay.

​
Ambientes e Modos

​
Ambiente de Desenvolvimento

Modo de testes onde as transações são simuladas e nenhum valor real é movimentado. Na Upay, o ambiente é definido pela chave de API utilizada: chaves de desenvolvimento geram transações de teste.

​
Ambiente de Produção

Modo real onde as transações são processadas e valores reais são movimentados. Requer conta verificada e chave de API de produção.

​
Sandbox

Outro nome para o ambiente de desenvolvimento/testes. Ideal para desenvolver e validar sua integração antes de ir para produção.

​
Pagamentos e Cobranças

URL reutilizável gerada pela Upay que pode ser compartilhada com clientes para receber pagamentos via PIX, cartão ou boleto. Pode ter estoque limitado, cupons, parcelamento e URLs de redirecionamento configuráveis.

​
Checkout

Processo onde o cliente finaliza a compra e realiza o pagamento. Pode acontecer numa página gerenciada pela Upay (via link de pagamento) ou diretamente na sua aplicação.

​
Gateway de Pagamento

Plataforma intermediária que processa pagamentos entre o cliente e o vendedor. A Upay é um gateway de pagamento que facilita transações PIX, cartão e boleto.

​
Transação

Registro de uma operação financeira. Cada transação tem um ID único, status, método de pagamento e informações do cliente.

​
PIX

Sistema de pagamento instantâneo brasileiro que permite transferências 24h/7 em segundos, sem custo para o pagador.

​
Boleto

Método de pagamento brasileiro que gera um código de barras para pagamento em bancos, lotéricas ou internet banking. Pode levar até 3 dias úteis para compensar.

​
Parcelamento

Divisão do pagamento em múltiplas parcelas mensais no cartão de crédito. Pode ser com ou sem juros.

​
Payout / Saque

Transferência do saldo da sua conta Upay para sua chave PIX ou conta bancária. Métodos suportados: PIX e TED.

​
Estrutura de Dados

​
Centavos

Unidade usada pela API para representar valores monetários. 100 centavos = R$ 1,00. Exemplo: 10000 = R$ 100,00.

​
Slug

Identificador único e legível usado em URLs de links de pagamento. Gerado automaticamente, mas pode ser personalizado. Exemplo: meu-produto-premium

​
Metadata

Campo opcional que permite armazenar informações adicionais personalizadas junto com recursos da API (transações, links de pagamento, etc.). Aceita qualquer objeto JSON. Exemplo: 
{
  "metadata": {
    "pedido_interno": "12345",
    "origem": "site",
    "campanha": "black-friday"
  }
}

​
External ID

Identificador único do seu sistema para relacionar recursos da Upay com registros internos. Útil para buscar transações usando seus próprios códigos de pedido.

​
UUID

Identificador único de 128 bits gerado automaticamente para identificar recursos na API. Formato: 550e8400-e29b-41d4-a716-446655440000.

​
Cupons e Descontos

​
Cupom

Código promocional que oferece desconto em uma compra. Pode ser percentual (ex: 10% off) ou valor fixo (ex: R$ 5,00 off). Suporta limite de usos e validade.

​
Desconto Percentual

Tipo de desconto aplicado como porcentagem sobre o valor total. Exemplo: Cupom de 15% em uma compra de R100,00→descontodeR 100,00 → desconto de R 15,00.

​
Desconto Fixo

Tipo de desconto com valor fixo independente do total da compra. Exemplo: Cupom de R$ 20,00 em qualquer compra.

​
Afiliados

​
Programa de Afiliados

Configuração criada por um anunciante que define a comissão paga a afiliados que indicarem clientes. Cada programa tem sua taxa de comissão e regras próprias. URL única gerada para cada afiliado dentro de um programa. Rastreia as vendas originadas por aquele afiliado.

​
Comissão

Valor pago automaticamente ao afiliado quando uma venda é realizada através do seu link. Calculada com base nas regras do programa.

​
Status

​
Status da Transação

  • PENDING: Aguardando pagamento
  • PAID: Pago e confirmado
  • CANCELLED: Cancelada
  • EXPIRED: Expirada
  • REFUNDED: Reembolsada

​
Status do Saque

  • PENDING: Solicitação recebida, aguardando processamento
  • PROCESSING: Em processamento
  • COMPLETED: Concluído com sucesso
  • CANCELLED: Cancelado
  • FAILED: Falhou

​
Webhooks

​
Webhook

Mecanismo onde a Upay envia notificações automáticas para o seu servidor sempre que algo importante acontece (como um pagamento confirmado), sem você precisar consultar a API constantemente.

​
Assinatura de Webhook

Configuração que define para qual URL e para quais eventos a Upay deve enviar notificações. Uma conta pode ter múltiplas assinaturas.

​
Evento

Ação que dispara um webhook. Exemplos: transaction.paid, payment_link.expired, withdrawal.completed. Cada evento contém informações sobre o que aconteceu.

​
Payload

Dados enviados pela Upay no corpo da notificação HTTP ao seu endpoint de webhook.

​
URLs e Endpoints

​
Base URL

Endereço raiz de todas as requisições à API: https://upay-sistema-api.onrender.com

​
Endpoint

URL específica que executa uma função na API. Exemplo: POST /api/v1/payment-links cria um novo link de pagamento.

​
Return URL

URL para onde o cliente é redirecionado ao clicar em “voltar” no checkout, antes de completar o pagamento.

​
Completion URL

URL para onde o cliente é redirecionado após completar o pagamento com sucesso.

​
Padrões Técnicos

​
REST

Estilo arquitetural para APIs que usa métodos HTTP padrão: GET (consultar), POST (criar), PATCH (atualizar), DELETE (remover).

​
JSON

Formato de dados leve e legível usado para troca de informações entre sistemas. Toda a API da Upay usa JSON.

​
ISO 8601

Padrão internacional para datas e horários. Formato: 2026-01-15T10:30:00Z.

​
BRL

Código ISO 4217 para Real Brasileiro (R$). Moeda padrão de toda a API.

​
CPF / CNPJ

Documentos de identificação brasileiros. CPF para pessoas físicas (11 dígitos) e CNPJ para empresas (14 dígitos).

​
Estrutura de Resposta

Todas as respostas da API seguem o padrão: 
{
  "data": { },
  "error": null,
  "success": true
}
  • Se success for true, a operação foi bem-sucedida e os dados estarão em data
  • Se success for false, a operação falhou e a mensagem de erro estará no campo error

​
Códigos HTTP comuns

  • 200 OK — Sucesso
  • 201 Created — Recurso criado com sucesso
  • 400 Bad Request — Requisição inválida (verifique os parâmetros)
  • 401 Unauthorized — API Key ausente ou inválida
  • 404 Not Found — Recurso não encontrado
  • 429 Too Many Requests — Rate limit atingido
  • 500 Internal Server Error — Erro interno da Upay

Não encontrou o termo que procura?

Entre em contato com nosso suporte: suporte@upaybr.com