ClickPay API

Bem-vindo à Atualização Multi-Provedor da ClickPay

A ClickPay evoluiu para se tornimgar um gateway de pagamento multi-provedor. Agora, as contas estão conectadas a bancos e instituições financeiras independentes, permitindo que cada conta criada seja atribuída a uma credencial bancária distinta e segura. Essa arquitetura torna as operações mais seguras e independentes, oferecendo uma camada extra de proteção e flexibilidade.

Devido a essa mudança, algumas atualizações foram feitas nos retornos das chamadas API. No entanto, essas mudanças são de nível leve e não exigem muito esforço técnico para adaptação.

1. PIX IN - Recebimento de Pagamentos

O endpoint de PIX IN permite solicitar o recebimento de valores via PIX. Ele gera um QR Code e os dados necessários para que o cliente pague a transação via PIX.

Endpoint:

URL: https://clickpay.finance/api/pix

Método: POST

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Corpo da Requisição

O corpo da requisição deve ser enviado no formato JSON e conter os seguintes campos:


{
    "userId": 10,  // ID único do usuário do seu sistema (INT)
    "amount": 5.00 // Valor do PIX em BRL (float)
}

Resposta de Sucesso (HTTP 200)

Se a solicitação for bem-sucedida, você receberá uma resposta JSON com os detalhes do pagamento via PIX. O status do pagamento pode variar entre:

payment.pending payment.paid payment.canceled


{
    "tx_id": "SHCP4C3C9KOF",
    "copia_e_cola": "base64_do_qrcode",
    "qrcode": "base64_string_qrcode",
    "valor_cobrado": 5,
    "method_code": "pix",
    "user_id": 10,
    "status": "payment.pending"
}

2. PIX OUT - Pagamento de Beneficiários

Este endpoint permite realizar pagamentos via PIX para um ou mais beneficiários de forma assíncrona. Cada transação de PIX OUT enviará um callback para o webhook informado, com status atualizados automaticamente. Os status possíveis para PIX OUT são:

withdraw.pending withdraw.paid withdraw.canceled withdraw.failed

Endpoint:

URL: https://clickpay.finance/api/withdraw

Método: POST

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Corpo da Requisição

O corpo da requisição deve ser enviado no formato JSON e conter os seguintes campos:


{
    "userId": 20,             // ID único do usuário (INT)
    "pixKeyType": "CPF",      // Tipo da chave PIX (CPF, CNPJ, TELEFONE, EMAIL, CHAVE_ALEATORIA)
    "pixKey": "38100469561",  // Chave PIX obrigatória (string)
    "amount": 5               // Valor obrigatório do saque (float)
}

Callback (Webhook de Notificação)

Para garantir a segurança dos callbacks, todos os callbacks enviados pela ClickPay incluem um cabeçalho chamado secureCode, que contém um UUID exclusivo. Esse código permite que os clientes validem a origem do callback e garantam que ele foi enviado diretamente dos nossos servidores.

Exemplo de Callback para withdraw.paid


Headers:
secureCode: "seu secureCode que recebeu junto as credências da API"

Body:
{
"status": "withdraw.paid",
"data": {
        "tx_id": "52WV956JZ315",
        "user_id": 20
    }
}

Exemplo de Callback para withdraw.canceled


Headers:
secureCode: "seu secureCode que recebeu junto as credências da API"

Body:
{
    "status": "withdraw.canceled",
    "data": {
        "tx_id": "52WV956JZ315",
        "user_id": 20
    }
}

Exemplo de Callback para withdraw.failed


Headers:
secureCode: "seu secureCode que recebeu junto as credências da API"

Body:
{
    "status": "withdraw.failed",
    "data": {
        "tx_id": "52WV956JZ315",
        "user_id": 20
    }
}

3. Consulta de Transação PIX

Este endpoint permite consultar o status de uma transação PIX já criada, retornando os detalhes da transação de acordo com user_id ou tx_id (string).

Endpoint:

URL: https://clickpay.finance/api/transaction/

Método: POST

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Corpo da Requisição

O corpo da requisição deve ser enviado no formato JSON e conter o seguinte campo:


{
    "search": "85c6627b-1e04-4884-bc1f-b68b3397dffd"  // "user_id" ou "tx_id" (string) ou "E2E PIX"
}

Resposta de Sucesso (HTTP 200)

Se a transação for encontrada, a resposta incluirá os detalhes da transação, como o ID da transação, o valor, a descrição e o status:


    {
        "transactionId": "85c6627b-1e04-4884-bc1f-b68b3397dffd",
        "userId": "12222",
        "amount": 100.00,
        "description": "Pagamento de Fatura",
        "status": "PAID",
        "createdAt": "2024-10-22 10:53:31",
        "updatedAt": "2024-10-22 11:10:15"
    }

Resposta de Erro (HTTP 400)

Se a transação não for encontrada, o sistema retornará uma mensagem de erro:


{
    "error": "Transaction not found"
}

4. Consulta de saldo

Este endpoint permite consultar saldo da conta.

Endpoint:

URL: https://clickpay.finance/api/balance/

Método: GET

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Resposta de Sucesso (HTTP 200)

Se a busca for bem sucedida será retornado um objeto com o saldo:


{
    "balance": "560.87",
}

Resposta de Erro (HTTP 401)

Caso ocorra erro de autenticação na requisição o erro será apresentado:


{
    "error": "Unauthorized for this request"
}

5. Comprovante de transação

Este endpoint permite os dados para gerar um comprovante de transação.

Endpoint:

URL: https://clickpay.finance/api/generate/receipt/{{ txId }}

Método: GET

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Resposta de Sucesso (HTTP 200)

Se a busca for bem sucedida será retornado um objeto com o saldo:


{
    "tx_id": "595f42802f4579b58b44c2b0d21abe",
    "copia_e_cola": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/a62c3200-8944-48c1-aca8-af816ed0ee925204000053039865802BR5925MEGA_SERVICOS,_TECNOLOGIA6002SP62070503***6304D208",
    "qrcode": "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",
    "amount": "5.00",
    "method_code": "pix",
    "user_id": "123",
    "status": "paid",
    "payer_name": "Nome do pagador",
    "payer_document": "CPF do pagador",
    "e2e": "E00416968202411051528kRNvgsChncG",
    "created_at": "05/11/2024 12:27",
    "updated_at": "05/11/2024 20:28"
}

Resposta de Erro (HTTP 400)

Caso ocorra erro de autenticação na requisição o erro será apresentado:


{
    "error": "Error creating receipt"
}

6. Link do comprovante da transação e download em PDF

Este endpoint permite os dados para gerar um comprovante e download de transação.

Endpoint:

URL: https://clickpay.finance/api/download/receipt/{{ txId }}

Método: GET

Headers:


Content-Type: application/json
partnerId: seu_partner_id
authKey: sua_chave_de_autenticação

Resposta de Sucesso (HTTP 200)

Se a busca for bem sucedida será retornado um objeto com o saldo:


{
    "tx_id": "595f42802f4579b58b44c2b0d21abe",
    "copia_e_cola": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/a62c3200-8944-48c1-aca8-af816ed0ee925204000053039865802BR5925MEGA_SERVICOS,_TECNOLOGIA6002SP62070503***6304D208",
    "qrcode": "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",
    "amount": "5.00",
    "method_code": "pix",
    "user_id": "123",
    "status": "paid",
    "payer_name": "Nome do pagador",
    "payer_document": "CPF do pagador",
    "e2e": "E00416968202411051528kRNvgsChncG",
    'receipt_link' => 'https://clickpay.finance/view/receipt/1982079',
    'receipt_pdf_download' => 'https://clickpay.finance/api/download/receipt/1982079',
    "created_at": "05/11/2024 12:27",
    "updated_at": "05/11/2024 20:28"
}

Resposta de Erro (HTTP 400)

Caso ocorra erro de autenticação na requisição o erro será apresentado:


{
    "error": "Error creating receipt"
}

7. Limites e Considerações

Valor Mínimo: O valor mínimo para PIX IN e PIX OUT é de R$ 5,00.

Valor Máximo: O valor máximo por transação de PIX OUT é de R$ 100.000,00.

Webhook: É necessário informar uma URL de webhook para receber notificações de atualizações de status para PIX IN e PIX OUT. As transações de PIX OUT agora são processadas de forma assíncrona.

ClickPay - Documentação Técnica

Bem-vindo à Atualização Multi-Provedor da ClickPay

1. PIX IN - Recebimento de Pagamentos

Endpoint:

Headers:

Corpo da Requisição

Resposta de Sucesso (HTTP 200)

2. PIX OUT - Pagamento de Beneficiários

Endpoint:

Headers:

Corpo da Requisição

Callback (Webhook de Notificação)

Exemplo de Callback para withdraw.paid

Exemplo de Callback para withdraw.canceled

Exemplo de Callback para withdraw.failed

3. Consulta de Transação PIX

Endpoint:

Headers:

Corpo da Requisição

Resposta de Sucesso (HTTP 200)

Resposta de Erro (HTTP 400)

4. Consulta de saldo

Endpoint:

Headers:

Resposta de Sucesso (HTTP 200)

Resposta de Erro (HTTP 401)

5. Comprovante de transação

Endpoint:

Headers:

Resposta de Sucesso (HTTP 200)

Resposta de Erro (HTTP 400)

6. Link do comprovante da transação e download em PDF

Endpoint:

Headers:

Resposta de Sucesso (HTTP 200)

Resposta de Erro (HTTP 400)

7. Limites e Considerações