API de Links de Pagamento

🤖 Explicar com IA

A API de Links de Pagamento ajuda as empresas a gerar e personalizar links de pagamento com detalhes específicos, como valor do pagamento, moeda, descrição e informações do cliente.

Uma vez gerado o link de pagamento, as empresas podem compartilhá-lo com seus clientes via e-mail, redes sociais ou outros canais de comunicação. Quando o cliente clica no link, ele é levado a uma página de processamento de pagamento onde pode inserir seus dados de pagamento e concluir a transação.

Criar um novo link de pagamento¶

Endpoint

POST /v1/payment-links/

Este endpoint permite criar um ou mais links de pagamento para clientes específicos ou sem detalhes do cliente.

Parâmetros de Consulta (Query Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
test	Indica se o link de pagamento está no modo de teste	boolean	false

Campos do Corpo da Solicitação (Request Body Fields):

Parâmetro	Descrição	Tipo	Obrigatório
description	Descrição do pagamento	string	true
amount	Valor do pagamento (mínimo equivalente a USD $1,00)	decimal	true
currency	Código da moeda (padrão: USD)	string	false
customers	Array de objetos de cliente ou IDs de cliente	array	false

Campos do Objeto de Cliente (se estiver fornecendo novos clientes):

Parâmetro	Descrição	Tipo	Obrigatório
id	UUID de cliente existente	string	false
customer	ID alternativo do cliente	string	false
first_name	Nome do cliente	string	false*
last_name	Sobrenome do cliente	string	false*
email	Endereço de e-mail do cliente	string	false*

*Obrigatórios em conjunto se não fornecer id ou customer.

Solicitação (Criar Link de Pagamento Único):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Assinatura Premium 1 Ano",
           "amount": 99.99,
           "currency": "USD",
           "customers": []
         }'

Solicitação (Criar Link de Pagamento para Múltiplos Clientes):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Licença de Produto",
           "amount": 49.99,
           "currency": "USD",
           "customers": [
             {
               "id": "550e8400-e29b-41d4-a716-446655440000"
             },
             {
               "first_name": "João",
               "last_name": "Silva",
               "email": "joao.silva@example.com"
             }
           ]
         }'

Resposta (201 Created - Link Único):

{
    "code": 201,
    "title": "Payment link created",
    "content": "The payment link was created correctly.",
    "type": "success",
    "data": {
        "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
        "link": "https://api.4geeks.io/pl/b3196f0b-bcba-46bc-b833-0bc845007c89"
    }
}

Resposta (201 Created - Múltiplos Links):

{
    "code": 201,
    "title": "Payment link created",
    "content": "The payment links were created correctly.",
    "type": "success",
    "data": [
        {
            "id": "987f6543-b21c-43d8-a567-123456789abc",
            "customer": "550e8400-e29b-41d4-a716-446655440000",
            "customer_name": "Alex Miller",
            "link": "https://api.4geeks.io/pl/987f6543-b21c-43d8-a567-123456789abc"
        },
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "customer": "650f9501-f40c-52e5-c827-557766551111",
            "customer_name": "João Silva",
            "link": "https://api.4geeks.io/pl/aabbccdd-1122-3344-5566-77889900aabb"
        }
    ]
}

Obter todos os links de pagamento¶

Endpoint

GET /v1/payment-links/

Este endpoint recupera todos os links de pagamento da sua conta com suporte a paginação.

Parâmetros de Consulta (Query Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
page	Número da página para paginação	integer	false
test	Filtrar pelo modo de teste (true/false)	boolean	false

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/payment-links/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Solicitação (Com Paginação):

curl -X GET 'https://api.4geeks.io/v1/payment-links/?page=1' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "count": 15,
    "next": "https://api.4geeks.io/v1/payment-links/?page=2",
    "previous": null,
    "results": [
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "description": "Assinatura Premium 1 Ano",
            "amount": "99.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-04T10:30:00Z"
        },
        {
            "id": "ccddee11-2233-4455-6677-88990011aabb",
            "description": "Licença de Produto",
            "amount": "49.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-03T15:45:00Z"
        }
    ]
}

Obter um link de pagamento específico¶

Endpoint

GET /v1/payment-links/{id}/

Este endpoint recupera os detalhes completos de um link de pagamento específico através do seu ID.

Parâmetros de Caminho (Path Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
id	O identificador único de um link de pagamento	string	true

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
    "description": "Assinatura Premium 1 Ano",
    "amount": 99.99,
    "currency": "USD",
    "payment_link": true,
    "active": true,
    "recurring": false,
    "next_date_of_payment": null,
    "status": "pending",
    "test": false,
    "created_on": "2025-12-04T22:56:39.903352Z",
    "payment_logs": []
}

Atualizar um link de pagamento¶

Endpoint

PUT /v1/payment-links/{id}/

Atualiza um link de pagamento existente com novos detalhes.

Parâmetros de Caminho (Path Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
id	O identificador único de um link de pagamento	string	true

Campos do Corpo da Solicitação (todos opcionais):

Parâmetro	Descrição	Tipo	Obrigatório
product	O ID do produto associado	string	false
customer	O ID do cliente (ou null para remover)	string	false
active	Se o link de pagamento está ativo	boolean	false
recurring	Determina se o link de pagamento é recorrente	boolean	false
next_date_of_payment	Próxima data de pagamento agendada (AAAA-MM-DD HH:MM:SS)	string	false
status	O status atual do link	string	false
test	Se true, o link está no modo de teste; false para produção	boolean	false

Valores de Status Válidos:

pending - Aguardando pagamento
paid - Pagamento concluído
paid_period - Pagamento do período concluído
pending_period - Pagamento do período pendente
cancelled / canceled - Link cancelado
defaulter - Pagamento em atraso
active - Link está ativo
inactive - Link está inativo

Solicitação:

curl -X PUT 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "active": true,
           "status": "pending",
           "recurring": false,
           "customer": null
         }'

Resposta (200 OK):

{
    "code": 200,
    "title": "Updated Payment Link",
    "content": "The Payment Link was updated successfully.",
    "type": "success"
}

Resposta (400 Bad Request - Status Inválido):

{
    "code": 400,
    "title": "Invalid Status",
    "content": "The specified state is invalid.",
    "type": "error"
}

Excluir um link de pagamento¶

Endpoint

DELETE /v1/payment-links/{id}/

Exclui um link de pagamento específico.

Parâmetros de Caminho (Path Parameters):

Parâmetro	Descrição	Tipo	Obrigatório
id	O identificador único de um link de pagamento	string	true

Solicitação:

curl -X DELETE 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "code": 200,
    "title": "Deleted",
    "content": "The Payment Link has been successfully removed.",
    "type": "success"
}

Tratamento de Erros¶

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Abaixo estão erros comuns específicos para links de pagamento:

400 Bad Request (Solicitação Inválida)¶

Ocorre quando a solicitação está malformada ou faltam campos obrigatórios.

Cenários:

Cenário	Mensagem de Erro	Solução
Descrição ausente	`"You have not provided a description for the payment."`	Inclua o campo `description`
Valor ausente	`"You have not provided a price for payment."`	Inclua o campo `amount`
Valor abaixo do mínimo	`"The amount is equal to $X USD, which is below the minimum of $1.00 USD"`	Aumente o valor para pelo menos o equivalente a $1,00 USD
Dados de cliente inválidos	`"You have not provided a first_name, last_name and email or a customer id."`	Forneça um ID de cliente existente ou os dados completos do cliente
Formato de data inválido	`"The date format must be YYYY-MM-DD HH:MM:SS"`	Use o formato: `AAAA-MM-DD HH:MM:SS`
Status inválido	`"The specified state is invalid."`	Use um status válido: pending, paid, cancelled, etc.

Exemplo de Resposta de Erro:

{
    "code": 406,
    "title": "Missing Data",
    "content": "You have not provided a description for the payment.",
    "type": "danger"
}

401 Unauthorized (Não Autorizado)¶

Falha na autenticação. A Chave de API é inválida, está ausente ou malformada.

Exemplo:

{
    "detail": "Authentication credentials were not provided."
}

Solução:

Verifique se você incluiu o parâmetro -u 'sk_test_...: ou o cabeçalho Authorization: Basic
Certifique-se de que sua Chave de API está correta e ativa
Teste com o Postman usando Basic Auth

404 Not Found (Não Encontrado)¶

O link de pagamento solicitado não existe.

Exemplo:

{
    "code": 404,
    "title": "Payment Link not found",
    "content": "The Payment Link could not be found, please check the id.",
    "type": "danger"
}

Solução:

Verifique se o ID do link de pagamento existe
Use o endpoint de listagem para encontrar o ID correto do link de pagamento
Certifique-se de que o link de pagamento pertence à sua conta de desenvolvedor

Notas Importantes¶

Validação do Link de Pagamento

O valor deve ser pelo menos o equivalente a USD $1,00
A descrição é obrigatória
Os links não podem ser modificados uma vez pagos

Informações do Cliente

Os links de pagamento podem ser criados com ou sem informações do cliente
Ao criar links para clientes existentes, forneça o UUID deles
Ao criar links para novos clientes, forneça first_name, last_name e email

Status do Pagamento

Os links de pagamento começam no status pending
O status é atualizado automaticamente com base na atividade de pagamento
Links recorrentes passam para paid_period após o pagamento

Teste vs Produção

Use sua Chave de Teste (sk_test_...) para desenvolvimento e testes
Use sua Chave de Produção (sk_live_...) para transações reais
O parâmetro de consulta ?test=true ou ?test=false controla o modo
O sistema detecta automaticamente o modo com base na Chave de API utilizada

Melhores Práticas¶

Inclua descrições claras - Ajude os clientes a entenderem pelo que estão pagando
Use a moeda correta - Corresponda à região do seu negócio e às expectativas dos clientes
Defina valores mínimos - Garanta que os valores sejam pelo menos o equivalente a $1,00 USD
Atribua clientes - Vincule pagamentos aos registros de clientes para um melhor acompanhamento
Monitore os logs de pagamento - Use os logs de pagamento para conciliar transações
Atualize o status adequadamente - Mantenha o status do link de pagamento em sincronia com o estado real do pagamento
Teste antes da produção - Use o modo de teste com chaves de API de teste para validação

Solução de Problemas¶

Problema: “The amount is below the minimum”¶

Causa: O valor do pagamento é menor que o equivalente a USD $1,00
Solução:

Aumente o campo amount para pelo menos 1.00
Verifique a conversão de moeda se estiver usando uma moeda diferente do USD

Problema: “You have not provided a description”¶

Causa: Campo obrigatório description ausente
Solução:

Inclua um título claro e descritivo para o pagamento
Exemplo: “Assinatura Premium”, “Licença de Produto”, “Taxa de Serviço”

Problema: “You have not provided a first_name, last_name and email or a customer id”¶

Causa: Informações de cliente incompletas
Solução:

Forneça um ID de cliente existente no array customers
Ou forneça os dados completos do cliente: first_name, last_name e email

Problema: “The specified state is invalid”¶

Causa: Valor de status inválido fornecido
Solução:

Use apenas valores de status válidos: pending, paid, paid_period, pending_period, cancelled, canceled, defaulter, active, inactive
Consulte a documentação para as definições de status

Problema: “Payment Link not found”¶

Causa: O ID do link de pagamento não existe ou pertence a uma conta de desenvolvedor diferente
Solução:

Verifique o ID do link de pagamento usando o endpoint de listagem
Certifique-se de que está usando a Chave de API correta
Verifique se o link de pagamento não foi excluído

Ainda tem dúvidas? Pergunte na comunidade..
Consulte el changelog.