Skip to main content

​
Visão geral

Os Links de pagamento são URLs personalizadas que você pode criar e compartilhar com seus clientes para receber pagamentos. Cada link pode ser configurado com valores, métodos de pagamento, produtos e muito mais.

​
Funcionalidades

  • Slug único: Cada link tem um identificador único e personalizável
  • Múltiplos métodos de pagamento: PIX, Cartão de Crédito/Débito, Boleto
  • Produtos: Associe produtos do seu catálogo ao link
  • Controle de estoque: Configure quantidade limitada de vendas
  • Parcelamento: Configure parcelamento até 12x
  • Validade: Defina data de expiração para o link
  • Meta Pixel: Integre com Meta Pixel para rastreamento
  • URL de redirecionamento: Configure para onde redirecionar após pagamento

​
Requisição Básica

curl -X POST "https://upay-sistema-api.onrender.com/api/v1/payment-links" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Produto Premium",
    "description": "Acesso completo à plataforma",
    "amount": 9900,
    "currency": "BRL",
    "settings": {
      "pixEnabled": true,
      "creditCardEnabled": true,
      "boletoEnabled": false,
      "maxInstallments": 12
    }
  }'

​
Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "produto-premium-abc123",
    "title": "Produto Premium",
    "description": "Acesso completo à plataforma",
    "amount": 9900,
    "currency": "BRL",
    "status": "ACTIVE",
    "url": "https://checkout.upaybr.com/pay/produto-premium-abc123",
    "createdAt": "2025-12-30T00:00:00.000Z",
    "updatedAt": "2025-12-30T00:00:00.000Z"
  }
}

​
Campos disponíveis

​
Campos obrigatórios

CampoTipoDescrição
titlestringTítulo do link de pagamento. Máximo 255 caracteres.

​
Campos opcionais

CampoTipoDescriçãoPadrão
descriptionstringDescrição detalhada do link. Máximo 1000 caracteres.-
amountnumberValor em centavos. Exemplo: 9900 = R99,00.Mıˊnimo:100(R 99,00. Mínimo: 100 (R 1,00).-
currencystringCódigo da moeda. Atualmente apenas “BRL” é suportado.”BRL”
expiresAtstringData de expiração no formato ISO 8601. Exemplo: “2024-12-31T23:59:59Z”.null
redirectUrlstringURL completa para redirecionar após pagamento. Deve começar com https://.-
productDescriptionstringDescrição adicional do produto. Máximo 500 caracteres.-
stockQuantitynumberQuantidade disponível em estoque. 0 = ilimitado. Mínimo: 0.0
stockEnabledbooleanAtiva controle de estoque. Se true, stockQuantity é obrigatório.false
metaPixelCodestringID do Meta Pixel para rastreamento. Formato: números apenas.-
statusstringStatus do link. Valores: “ACTIVE” ou “INACTIVE”.”ACTIVE”

​
Configurações de pagamento (settings)

O objeto settings permite configurar métodos de pagamento e comportamentos do checkout.
CampoTipoDescriçãoPadrão
pixEnabledbooleanHabilita pagamento via PIX.true
boletoEnabledbooleanHabilita pagamento via Boleto.false
creditCardEnabledbooleanHabilita pagamento via Cartão de Crédito.true
maxInstallmentsnumberNúmero máximo de parcelas. Mínimo: 1, Máximo: 12.1
interestFreeInstallmentsnumberParcelas sem juros. Deve ser ≤ maxInstallments.1
interestRatenumberTaxa de juros mensal (%).0
requirePhonebooleanExige telefone no checkout.true
requireAddressbooleanExige endereço completo no checkout.false
Exemplo: 
{
  "settings": {
    "pixEnabled": true,
    "boletoEnabled": false,
    "creditCardEnabled": true,
    "maxInstallments": 12,
    "interestFreeInstallments": 3,
    "interestRate": 2.5,
    "requirePhone": true,
    "requireAddress": true
  }
}

​
Personalização do Checkout (checkoutConfig)

O campo checkoutConfig permite personalizar a aparência e o comportamento visual do checkout (White-label).

​
Tema (theme)

CampoTipoDescrição
primaryColorstringCor principal em Hexadecimal (ex: #9747FF).
logoUrlstringURL da logomarca da sua empresa.
buttonTextstringTexto personalizado para o botão de pagamento.
bannerUrlstringURL da imagem do banner de topo.
bannerLayoutstringLayout do banner: full, contained, compact, none.
fontFamilystringFonte: default (sans), serif, mono.
borderRadiusstringCantos: square, default, rounded.
colorSchemestringEsquema: light, dark, system.

​
Componentes e Blocos

CampoTipoDescrição
showHeaderbooleanExibe/oculta o cabeçalho com logo.
showPoweredBybooleanSe false, remove a marca “Powered by Upay”.
showSocialProofbooleanExibe depoimentos/prova social configurados.
showTermsFooterbooleanExibe links de Termos e Privacidade.
Exemplo Completo: 
{
  "checkoutConfig": {
    "theme": {
      "primaryColor": "#000000",
      "fontFamily": "serif",
      "bannerLayout": "compact",
      "borderRadius": "square"
    },
    "showHeader": true,
    "showPoweredBy": false,
    "showTermsFooter": true,
    "termsUrl": "https://meusite.com/termos"
  }
}

​
Associando Produtos

{
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ]
}
Quando produtos são associados, o valor total é calculado automaticamente baseado nos preços dos produtos e quantidades.

​
📖 Exemplos Completos

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Curso Online',
    description: 'Acesso completo ao curso por 1 ano',
    amount: 19900, // R$ 199,00
    currency: 'BRL',
    settings: {
      pixEnabled: true,
      creditCardEnabled: true,
      maxInstallments: 6,
      interestFreeInstallments: 3
    }
  })
});

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Pacote Premium',
    description: 'Inclui 3 produtos do catálogo',
    products: [
      { productId: 'produto-1-id', quantity: 1 },
      { productId: 'produto-2-id', quantity: 2 }
    ],
    stockQuantity: 50,
    stockEnabled: true,
    settings: {
      pixEnabled: true,
      creditCardEnabled: true,
      boletoEnabled: true
    }
  })
});

const expiresAt = new Date();
expiresAt.setDate(expiresAt.getDate() + 30); // Expira em 30 dias

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Oferta Especial',
    description: 'Válido apenas este mês',
    amount: 9900,
    expiresAt: expiresAt.toISOString(),
    redirectUrl: 'https://meusite.com.br/obrigado',
    settings: {
      pixEnabled: true,
      creditCardEnabled: true
    }
  })
});

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

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

curl -X PATCH "https://upay-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Novo Título",
    "status": "INACTIVE"
  }'
Você pode atualizar apenas os campos que desejar. Campos não enviados permanecerão inalterados.

​
🗑️ Deletando um Link

curl -X DELETE "https://upay-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
A exclusão é permanente e não pode ser desfeita. Certifique-se de que realmente deseja deletar o link.

​
URL do checkout

Após criar um link, você receberá uma URL no formato: 
https://checkout.upaybr.com/pay/{slug}
Esta URL pode ser compartilhada diretamente com seus clientes.

​
📊 Status do Link

  • ACTIVE: Link ativo e disponível para pagamentos
  • INACTIVE: Link desativado (não aceita novos pagamentos)

​
Casos de uso

​
E-commerce

Crie links para produtos específicos com controle de estoque e múltiplos métodos de pagamento.

​
Assinaturas

Configure links recorrentes com valores e parcelamento adequados.

​
Doações

Crie links simples para receber doações via PIX ou cartão.

​
Cursos Online

Associe produtos (cursos) aos links e controle o acesso.

​
📚 Próximos Passos

Referência da API

Veja todos os endpoints disponíveis

Produtos

Aprenda a gerenciar produtos

Webhooks

Configure notificações em tempo real