Links de pagamento - Alpa Gateway API

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://alpa-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",
    "createdAt": "2025-12-30T00:00:00.000Z",
    "updatedAt": "2025-12-30T00:00:00.000Z"
  }
}

A URL pública do checkout é montada a partir do slug: https://checkout.usealpa.com/pay/{slug}.

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: `#FF3D02`).
`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 Alpa”.
`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://alpa-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://alpa-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://alpa-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://alpa-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://alpa-sistema-api.onrender.com/api/v1/payment-links/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

Atualizando um link

curl -X PATCH "https://alpa-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://alpa-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.usealpa.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

​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