Links de pagamento

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

Criando seu primeiro link

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

Campo	Tipo	Descrição
`title`	string	Título do link de pagamento. Máximo 255 caracteres.

Campos opcionais

Campo	Tipo	Descrição	Padrão
`description`	string	Descrição detalhada do link. Máximo 1000 caracteres.	-
`amount`	number	Valor em centavos. Exemplo: 9900 = R $99,00. Mínimo: 100 (R$ 1,00).	-
`currency`	string	Código da moeda. Atualmente apenas “BRL” é suportado.	”BRL”
`expiresAt`	string	Data de expiração no formato ISO 8601. Exemplo: “2024-12-31T23:59:59Z”.	null
`redirectUrl`	string	URL completa para redirecionar após pagamento. Deve começar com https://.	-
`productDescription`	string	Descrição adicional do produto. Máximo 500 caracteres.	-
`stockQuantity`	number	Quantidade disponível em estoque. 0 = ilimitado. Mínimo: 0.	0
`stockEnabled`	boolean	Ativa controle de estoque. Se true, `stockQuantity` é obrigatório.	false
`metaPixelCode`	string	ID do Meta Pixel para rastreamento. Formato: números apenas.	-
`status`	string	Status 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.

Campo	Tipo	Descrição	Padrão
`pixEnabled`	boolean	Habilita pagamento via PIX.	true
`boletoEnabled`	boolean	Habilita pagamento via Boleto.	false
`creditCardEnabled`	boolean	Habilita pagamento via Cartão de Crédito.	true
`maxInstallments`	number	Número máximo de parcelas. Mínimo: 1, Máximo: 12.	1
`interestFreeInstallments`	number	Parcelas sem juros. Deve ser ≤ `maxInstallments`.	1
`interestRate`	number	Taxa de juros mensal (%).	0
`requirePhone`	boolean	Exige telefone no checkout.	true
`requireAddress`	boolean	Exige 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`)

Campo	Tipo	Descrição
`primaryColor`	string	Cor principal em Hexadecimal (ex: `#9747FF`).
`logoUrl`	string	URL da logomarca da sua empresa.
`buttonText`	string	Texto personalizado para o botão de pagamento.
`bannerUrl`	string	URL da imagem do banner de topo.
`bannerLayout`	string	Layout do banner: `full`, `contained`, `compact`, `none`.
`fontFamily`	string	Fonte: `default` (sans), `serif`, `mono`.
`borderRadius`	string	Cantos: `square`, `default`, `rounded`.
`colorScheme`	string	Esquema: `light`, `dark`, `system`.

Componentes e Blocos

Campo	Tipo	Descrição
`showHeader`	boolean	Exibe/oculta o cabeçalho com logo.
`showPoweredBy`	boolean	Se `false`, remove a marca “Powered by Upay”.
`showSocialProof`	boolean	Exibe depoimentos/prova social configurados.
`showTermsFooter`	boolean	Exibe 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

Link Simples com PIX e Cartão

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
    }
  })
});

Link com Produtos e Estoque

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
    }
  })
});

Link com Expiração e Redirecionamento

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
    }
  })
});

Listando links

Listar Todos os Links

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

Buscar Link Específico

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

Atualizando um link

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

Primeiros Passos

Guias

Suporte

Visão geral

Funcionalidades

Criando seu primeiro link

Requisição Básica

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

Configurações de pagamento (`settings`)

Personalização do Checkout (`checkoutConfig`)

Tema (`theme`)

Componentes e Blocos

Associando Produtos

📖 Exemplos Completos

Link Simples com PIX e Cartão

Link com Produtos e Estoque

Link com Expiração e Redirecionamento

Listando links

Listar Todos os Links

Buscar Link Específico

Atualizando um link

🗑️ Deletando um Link

URL do checkout

📊 Status do Link

Casos de uso

E-commerce

Assinaturas

Doações

Cursos Online

📚 Próximos Passos

Referência da API

Produtos

Webhooks

​Visão geral

​Funcionalidades

​Criando seu primeiro link

​Requisição Básica

​Resposta

​Campos disponíveis

​Campos obrigatórios

​Campos opcionais

​Configurações de pagamento (settings)

​Personalização do Checkout (checkoutConfig)

​Tema (theme)

​Componentes e Blocos

​Associando Produtos

​📖 Exemplos Completos

​Link Simples com PIX e Cartão

​Link com Produtos e Estoque

​Link com Expiração e Redirecionamento

​Listando links

​Listar Todos os Links

​Buscar Link Específico

​Atualizando um link

​🗑️ Deletando um Link

​URL do checkout

​📊 Status do Link

​Casos de uso

​E-commerce

​Assinaturas

​Doações

​Cursos Online

​📚 Próximos Passos

Referência da API

Produtos

Webhooks

Visão geral

Funcionalidades

Criando seu primeiro link

Requisição Básica

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

Configurações de pagamento (`settings`)

Personalização do Checkout (`checkoutConfig`)

Tema (`theme`)

Componentes e Blocos

Associando Produtos

📖 Exemplos Completos

Link Simples com PIX e Cartão

Link com Produtos e Estoque

Link com Expiração e Redirecionamento

Listando links

Listar Todos os Links

Buscar Link Específico

Atualizando um link

🗑️ Deletando um Link

URL do checkout

📊 Status do Link

Casos de uso

E-commerce

Assinaturas

Doações

Cursos Online

📚 Próximos Passos