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": {
"methods": {
"pix": true,
"card": true
},
"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 = R99,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 |
|---|
methods.pix | boolean | Habilita pagamento via PIX. | true |
methods.boleto | boolean | Habilita pagamento via Boleto. | false |
methods.card | 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 |
allowedPaymentMethods | string[] | Array de métodos permitidos (ex: ["pix", "card"]). | - |
{
"settings": {
"methods": {
"pix": true,
"boleto": false,
"card": 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. |
{
"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: {
methods: {
pix: true,
card: 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: {
methods: {
pix: true,
card: true,
boleto: 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: {
methods: {
pix: true,
card: 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}
📊 Status do Link
ACTIVE: Link ativo e disponível para pagamentosINACTIVE: 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
