Primeiros Passos

CONTA

CASH IN

CASH OUT

FATURAS INTERNAS

TRANSFERÊNCIAS INTERNAS

CRYPTO

Webhooks PIX

Webhooks Faturas Internas

Webhooks Crypto

Referência

Documentação Oficial

API docs

Documentação completa para integrar soluções de pagamento com transações PIX e gerenciamento de cashouts. Construída para desenvolvedores que buscam simplicidade e robustez.

Início Rápido

Configure sua integração em minutos com nossos exemplos práticos e guias detalhados.

API RESTful

Métodos HTTP padrão com corpos de requisição e resposta em JSON limpo e consistente.

Webhooks

Notificações em tempo real para atualizações de status de transações e cashouts.

Guia de Integração

Para começar a usar nossa API de Pagamentos, siga estes passos:

Obtenha suas credenciais de API no painel administrativo
Configure os cabeçalhos de autenticação em suas requisições
Implemente endpoints de webhook para receber atualizações de status

Ambiente de Produção

Nossa API está disponível em ambiente de produção para processar pagamentos reais.

https://api.connectpay.vc

URL Base da API

Todas as requisições da API devem ser feitas para o seguinte endpoint base:

BASE URL

https://api.connectpay.vc

HTTPS

Importante

Todos os endpoints documentados abaixo devem ser anexados a esta URL base. Por exemplo, para criar uma transação, faça uma requisição para https://api.connectpay.vc/v1/transactions.

Autenticação

A API utiliza autenticação por chave de API através de cabeçalhos de requisição.

Cabeçalho de Autenticação

Inclua seu API secret no cabeçalho da requisição para autenticação.

Cabeçalho de Autenticação

http

api-secret: SEU_API_SECRET_AQUI

Nota de Segurança

Você pode obter seu API Secret na seção integrações → API de pagamentos no painel da sua conta. Mantenha seu API secret seguro e nunca o exponha em código do lado do cliente.

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/account-info" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json"

Exemplo JavaScript

JavaScript

javascript

const response = await fetch('https://api.connectpay.vc/v1/account-info', {
  headers: {
    'api-secret': 'seu_api_secret_aqui',
    'Content-Type': 'application/json'
  }
});

Informações da Conta

Recupera informações sobre a conta associada à chave de API.

GET

https://api.connectpay.vc/v1/account-info

v1.0

Informação

Este endpoint não requer parâmetros adicionais. As informações retornadas são baseadas na chave de API fornecida no cabeçalho de autenticação.

Resposta

Resposta de Informações da Conta

json

{
  "email": "joao.silva@exemplo.com",
  "name": "João Silva",
  "document": "12345678901"
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`email`	string	Endereço de email da conta
`name`	string	Nome do titular da conta
`document`	string	Número do documento da conta (CPF/CNPJ)

Consultar Transação

Recupera detalhes de uma transação previamente criada usando seu ID único.

GET

https://api.connectpay.vc/v1/transactions/{transaction_id}

v1.0

Parâmetros da URL

Parâmetro	Tipo	Descrição
`transaction_id` obrigatório	string	Identificador único da transação que deseja consultar

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/transactions/c22dc7e1-8b10-4580-9dc4-ebf78ceca475" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json"

Resposta

Resposta da Transação

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "status": "PENDING",
  "amount": 100.50,
  "payment_method": "PIX",
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999999999",
    "document": "12345678901",
    "address": {
      "cep": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "number": "123",
      "street": "Rua das Flores",
      "complement": "Apt 45",
      "neighborhood": "Centro"
    }
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	Identificador único da transação
`external_id`	string	Seu ID de referência externa
`status`	TransactionStatus	Status atual da transação
`amount`	number	Valor da transação em BRL
`payment_method`	string	Método de pagamento utilizado
`customer`	Customer	Objeto com informações do cliente
`created_at`	string	Timestamp de criação da transação (ISO 8601)

Criar Transação

Cria uma nova transação de pagamento no sistema com todos os detalhes necessários.

POST

https://api.connectpay.vc/v1/transactions

v1.0

Interface TypeScript

Definições de Tipo

typescript

interface CreateTransactionRequest {
  external_id?: string;
  total_amount: number;
  payment_method: "PIX";
  webhook_url?: string;
  items: TransactionItem[];
  ip?: string;
  customer: Customer;
}

interface TransactionItem {
  id: string;
  title: string;
  description?: string;
  price: number;
  quantity: number;
  is_physical: boolean;
}

interface Customer {
  name: string;
  email: string;
  phone: string;
  document_type: "CPF" | "CNPJ";
  document: string;
}

Exemplo de Requisição

Criar Transação - Requisição

json

{
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "payment_method": "PIX",
  "webhook_url": "https://sua-api.com/webhooks/transactions",
  "items": [
    {
      "id": "item_001",
      "title": "Assinatura Premium",
      "description": "Assinatura mensal premium",
      "price": 100.50,
      "quantity": 1,
      "is_physical": false
    }
  ],
  "ip": "192.168.1.1",
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999999999",
    "document_type": "CPF",
    "document": "12345678901"
  }
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`external_id`	string	Sua referência única para esta transação
`total_amount` obrigatório	number	Valor total da transação em BRL
`payment_method` obrigatório	string	Método de pagamento (atualmente apenas 'PIX')
`webhook_url`	string	URL para receber notificações de mudança de status
`items` obrigatório	TransactionItem[]	Array de itens na transação
`ip`	string	Endereço IP do cliente
`customer` obrigatório	Customer	Informações do cliente

Resposta

Criar Transação - Resposta

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "status": "PENDING",
  "total_value": 100.50,
  "customer": {
    "email": "joao.silva@exemplo.com",
    "name": "João Silva"
  },
  "payment_method": "PIX",
  "pix": {
    "payload": "00020126580014br.gov.bcb.pix..."
  },
  "hasError": false
}

Dica de Implementação

O campo pix.payload contém o código PIX que deve ser apresentado ao cliente para pagamento. Este código pode ser usado para gerar um QR Code ou ser copiado diretamente.

Cashout (Saque)

Cria uma nova transação de cashout (saque) utilizando PIX para transferir fundos.

POST

https://api.connectpay.vc/v1/cashout

v1.0

Interface TypeScript

Definição de Tipo

typescript

interface CreateCashoutRequest {
  external_id?: string;
  pix_key: string;
  pix_type: "CPF" | "CNPJ" | "EMAIL" | "PHONE" | "RANDOM";
  amount: number;
  webhook_url?: string;
}

Exemplo de Requisição

Criar Cashout - Requisição

json

{
  "external_id": "saque_12345",
  "pix_key": "joao.silva@exemplo.com",
  "pix_type": "EMAIL",
  "amount": 250.00,
  "webhook_url": "https://sua-api.com/webhooks/cashouts"
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`external_id`	string	Sua referência única para este cashout
`pix_key` obrigatório	string	Chave PIX para o destino do cashout
`pix_type` obrigatório	PixKeyType	Tipo da chave PIX sendo utilizada
`amount` obrigatório	number	Valor do cashout em BRL (mínimo 0.01)
`webhook_url`	string	URL para receber notificações de status do cashout

Formatos de Chave PIX

CPF

11 dígitos numéricos

12345678901

CNPJ

14 dígitos numéricos

12345678000195

Endereço de email válido

usuario@exemplo.com

PHONE

+55 seguido de 10-11 dígitos

+5511999999999

RANDOM

32-36 caracteres alfanuméricos

123e4567-e12b-12d3-a456-426614174000

Validação Importante

A chave PIX deve corresponder exatamente ao tipo especificado no campo pix_type. Chaves inválidas resultarão em erro 400.

Resposta

Criar Cashout - Resposta

json

{
  "success": true,
  "message": "Cashout criado com sucesso",
  "data": {
    "withdraw_id": "bb0fb3cb-015f-4604-8532-133a78c0c3e1",
    "cashout_id": "bb0fb3cb-015f-4604-8532-133a78c0c3e1",
    "is_pending": true
  }
}

Consultar Receipt do Cashout

Consulta o comprovante (receipt) de um cashout específico pelo ID, retornando um HTML formatado.

GET

https://api.connectpay.vc/v1/cashout/receipt/:cashoutId

v1.0

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário

Parâmetros de URL

Parâmetro	Tipo	Descrição
`cashoutId` obrigatório	string	ID único do cashout (UUID)

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/cashout/receipt/bb0fb3cb-015f-4604-8532-133a78c0c3e1" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Content-Type: application/json"

Resposta de Sucesso (200 OK)

Formato da Resposta

A resposta é retornada como HTML formatado, contendo o comprovante do cashout com todas as informações relevantes.

Exemplo de Resposta HTML

html

<!DOCTYPE html>
<html>
<head>
  <title>Comprovante de Cashout</title>
  <style>
    /* Estilos do comprovante */
  </style>
</head>
<body>
  <div class="receipt">
    <h1>Comprovante de Saque</h1>
    <p><strong>ID:</strong> bb0fb3cb-015f-4604-8532-133a78c0c3e1</p>
    <p><strong>Valor:</strong> R$ 250.00</p>
    <p><strong>Status:</strong> approved</p>
    <p><strong>Data:</strong> 2024-01-15T10:30:00.000Z</p>
    <!-- Mais informações do cashout -->
  </div>
</body>
</html>

Respostas de Erro

401 Unauthorized

"API Secret não fornecida"

403 Forbidden

"Você não tem permissão para acessar este cashout"

404 Not Found

"Cashout não encontrado"

Regras de Negócio

Permissão: apenas o usuário que criou o cashout pode consultar o receipt
Validação: o cashoutId deve ser um UUID válido
Formato: a resposta é retornada como HTML, não JSON
Autenticação: api-secret deve ser válido e pertencer ao criador do cashout

Exemplo Completo (JavaScript)

JavaScript

javascript

const axios = require('axios');

const API_SECRET = 'sua-api-secret-aqui';
const BASE_URL = 'https://api.example.com/v1';

async function consultarCashoutReceipt(cashoutId) {
  try {
    const response = await axios.get(
      `${BASE_URL}/v1/cashout/receipt/${cashoutId}`,
      {
        headers: {
          'api-secret': API_SECRET
        },
        responseType: 'text' // Importante: receber como texto para HTML
      }
    );
    
    console.log('Receipt HTML:', response.data);
    return response.data; // Retorna o HTML do comprovante
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data.message || error.response.data);
    } else {
      console.error('Erro na requisição:', error.message);
    }
    throw error;
  }
}

// Uso
consultarCashoutReceipt('bb0fb3cb-015f-4604-8532-133a78c0c3e1');

Criar Fatura Interna

Cria uma nova fatura interna para cobrança entre contas.

POST

https://api.connectpay.vc/v1/internal-invoice

v1.0

Rate Limit: 20 requisições por 60 segundos

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário
`Content-Type` obrigatório	string	application/json

Interface TypeScript

Definição de Tipo

typescript

interface CreateInternalInvoiceRequest {
  amount: number;              // Obrigatório - número, mínimo 0.01, máximo 2 casas decimais
  description?: string;         // Opcional - string, máximo 500 caracteres
  due_date?: string;           // Opcional - string ISO 8601 (data futura)
  webhook_url?: string;        // Opcional - URL válida, máximo 500 caracteres
  receiver_name?: string;      // Opcional - nome fictício do beneficiário da fatura (exibido na fatura)
}

Exemplo de Requisição

Criar Fatura Interna - Requisição

json

{
  "amount": 100.50,
  "description": "Descrição",
  "due_date": "2026-02-15T10:00:00Z",
  "webhook_url": "https://exemplo.com/webhook",
  "receiver_name": "Nome do Beneficiário"
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`amount` obrigatório	number	Valor da cobrança (mín. 0.01, máx. 2 casas decimais)
`description`	string	Descrição da fatura (máx. 500 caracteres)
`due_date`	string	Data de vencimento em formato ISO 8601 (deve ser uma data futura)
`webhook_url`	string	URL para receber notificações de atualização da fatura (máx. 500 caracteres)
`receiver_name`	string	Nome fictício do beneficiário da fatura (exibido na fatura para o pagador)

Exemplo de Requisição

cURL

bash

curl -X POST "https://api.connectpay.vc/v1/internal-invoice" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "description": "Descrição",
    "due_date": "2026-02-15T10:00:00Z",
    "webhook_url": "https://exemplo.com/webhook",
    "receiver_name": "Nome do Beneficiário"
  }'

Resposta de Sucesso (200 OK)

Criar Fatura Interna - Resposta

json

{
  "hasError": false,
  "message": "Cobrança criada com sucesso",
  "data": {
    "id": "uuid-da-cobranca",
    "code": "ABC12345",
    "invoice_url": "https://dashboard.url/finance?invoice_code=ABC12345",
    "invoice_qrcode_base64": "iVBORw0KG...",
    "guide": "1. Acesse o painel ConnectPay\n\n2. Vá até a aba Finanças\n...",
    "amount": 100.50,
    "fee": 2.50,
    "net_amount": 98.00,
    "status": "PENDING",
    "description": "Descrição",
    "due_date": "2026-02-15T10:00:00Z",
    "webhook_url": "https://exemplo.com/webhook",
    "created_at": "2026-01-28T10:00:00Z"
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	ID único da cobrança (UUID)
`code`	string	Código copia e cola para o usuúario identificar a fatura no painel
`invoice_url`	string	URL para acesso à fatura no dashboard
`invoice_qrcode_base64`	string	QR Code da fatura em formato base64
`guide`	string	Guia de instruções para pagamento
`amount`	number	Valor bruto da cobrança
`fee`	number	Taxa calculada automaticamente
`net_amount`	number	Valor líquido (amount - fee)
`status`	string	Status da fatura (PENDING, PAID, CANCELLED, EXPIRED)
`description`	string	Descrição da fatura
`due_date`	string	Data de vencimento (ISO 8601)
`webhook_url`	string	URL configurada para webhook
`created_at`	string	Data e hora de criação (ISO 8601)

Respostas de Erro

400 Bad Request

Possíveis mensagens:

"O valor da cobrança deve ser maior que zero"
"A data de vencimento deve ser uma data futura"

401 Unauthorized

"API Secret não fornecida"

403 Forbidden

Possíveis mensagens:

"Transferências internas estão desabilitadas"
"Saque automático não está habilitado para este usuário"
"Não é possível criar cobranças. Seu acesso está bloqueado"

404 Not Found

"Usuário não encontrado"

Regras de Negócio

Valor mínimo: R$ 0,01
Taxa: calculada automaticamente com base na configuração de taxas do usuário recebedor
Status: PENDING, PAID, CANCELLED, EXPIRED
Transferências internas devem estar habilitadas
Saque automático deve estar habilitado para o usuário

Exemplo Completo (JavaScript)

JavaScript

javascript

const axios = require('axios');

const API_SECRET = 'sua-api-secret-aqui';
const BASE_URL = 'https://api.example.com/v1';

async function criarFaturaInterna(amount, description, dueDate, webhookUrl, receiverName) {
  try {
    const response = await axios.post(
      `${BASE_URL}/internal-invoice`,
      {
        amount: amount,
        description: description,
        due_date: dueDate,
        webhook_url: webhookUrl,
        receiver_name: receiverName
      },
      {
        headers: {
          'api-secret': API_SECRET,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Fatura criada:', response.data);
    return response.data.data;
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data.message);
    } else {
      console.error('Erro na requisição:', error.message);
    }
    throw error;
  }
}

// Uso
criarFaturaInterna(100.50, "Descrição", "2026-02-15T10:00:00Z", "https://exemplo.com/webhook", "Nome do Beneficiário");

Buscar Fatura Interna por ID

Consulta os detalhes de uma fatura interna específica pelo ID.

GET

https://api.connectpay.vc/v1/internal-invoice/:id

v1.0

Rate Limit: 30 requisições por 60 segundos

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário

Parâmetros de URL

Parâmetro	Tipo	Descrição
`id` obrigatório	string	ID da cobrança (UUID)

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/internal-invoice/uuid-da-cobranca" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Content-Type: application/json"

Resposta de Sucesso (200 OK)

Buscar Fatura Interna - Resposta

json

{
  "hasError": false,
  "data": {
    "id": "uuid-da-cobranca",
    "code": "ABC12345",
    "amount": 100.50,
    "fee": 2.50,
    "net_amount": 98.00,
    "status": "PENDING",
    "description": "Descrição",
    "due_date": "2026-02-15T10:00:00Z",
    "created_at": "2026-01-28T10:00:00Z",
    "updated_at": "2026-01-28T10:00:00Z",
    "is_expired": false,
    "receiver": {
      "name": "Nome do Recebedor",
      "document": "123.456.789-00",
      "receiver_type": "PF"
    }
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	ID único da cobrança (UUID)
`code`	string	Código copia e cola para o usuúario identificar a fatura no painel
`amount`	number	Valor bruto da cobrança
`fee`	number	Taxa calculada automaticamente
`net_amount`	number	Valor líquido (amount - fee)
`status`	string	Status da fatura (PENDING, PAID, CANCELLED, EXPIRED)
`description`	string	Descrição da fatura
`due_date`	string	Data de vencimento (ISO 8601)
`created_at`	string	Data e hora de criação (ISO 8601)
`updated_at`	string	Data e hora da última atualização (ISO 8601)
`is_expired`	boolean	Indica se a fatura está expirada (true se due_date passou e status é PENDING)
`receiver`	object	Informações do recebedor
`receiver.name`	string	Nome do recebedor
`receiver.document`	string	CPF ou CNPJ formatado
`receiver.receiver_type`	string	Tipo do recebedor (PF \| PJ \| null)

Respostas de Erro

401 Unauthorized

"API Secret não fornecida"

403 Forbidden

"Transferências internas estão desabilitadas"

404 Not Found

Possíveis mensagens:

"Fatura não encontrada"
"Usuário não encontrado"

Observações Importantes

O campo receiver_account_id foi removido da resposta do endpoint de criação
Ambos os endpoints verificam se as transferências internas estão habilitadas
O endpoint de criação valida se o usuário tem saque automático habilitado
Status possíveis: PENDING, PAID, CANCELLED, EXPIRED
A taxa (fee) é calculada automaticamente com base na configuração de taxas do usuário recebedor

Exemplo Completo (JavaScript)

JavaScript

javascript

const axios = require('axios');

const API_SECRET = 'sua-api-secret-aqui';
const BASE_URL = 'https://api.example.com/v1';

async function buscarFaturaInterna(invoiceId) {
  try {
    const response = await axios.get(
      `${BASE_URL}/internal-invoice/${invoiceId}`,
      {
        headers: {
          'api-secret': API_SECRET
        }
      }
    );
    
    console.log('Fatura encontrada:', response.data);
    return response.data.data;
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data.message);
    } else {
      console.error('Erro na requisição:', error.message);
    }
    throw error;
  }
}

// Uso
buscarFaturaInterna('uuid-da-cobranca');

Status da Fatura

PENDING

Fatura pendente de pagamento

PAID

Fatura paga

CANCELLED

Fatura cancelada

EXPIRED

Fatura expirada

Realizar Transferência Interna

Cria uma nova transferência interna entre contas.

POST

https://api.connectpay.vc/v1/internal-transfer

v1.0

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário
`Idempotency-Key` obrigatório	string	Chave única para garantir idempotência (obrigatório)
`Content-Type` obrigatório	string	application/json

Interface TypeScript

Definição de Tipo

typescript

interface CreateInternalTransferRequest {
  to_email: string;
  amount: number;
  idempotency_key: string;
}

Exemplo de Requisição

Realizar Transferência Interna - Requisição

json

{
  "to_email": "destinatario@example.com",
  "amount": 100.50
}

Idempotency-Key Obrigatório

O header Idempotency-Key é obrigatório para todas as requisições. Você pode enviar o idempotency_key no body ou no header, mas é recomendado usar o header.

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`to_email` obrigatório	string	Email do destinatário (máx. 255 caracteres)
`amount` obrigatório	number	Valor da transferência (mín. 0.01, máx. 2 casas decimais)
`idempotency_key` obrigatório	string	Chave única para evitar duplicações (obrigatório, pode ser enviado no header Idempotency-Key)

Exemplo de Requisição

cURL

bash

curl -X POST "https://api.connectpay.vc/v1/internal-transfer" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Idempotency-Key: unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "destinatario@example.com",
    "amount": 100.50
  }'

Resposta de Sucesso (200 OK)

Realizar Transferência Interna - Resposta

json

{
  "hasError": false,
  "message": "Transferência interna realizada com sucesso",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from_account_id": "user-123",
    "to_account_id": "user-456",
    "amount": 100.50,
    "fee": 2.50,
    "net_amount": 100.50,
    "status": "COMPLETED",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	ID único da transferência
`from_account_id`	string	ID da conta remetente
`to_account_id`	string	ID da conta destinatária
`amount`	number	Valor bruto transferido
`fee`	number	Taxa cobrada na transferência
`net_amount`	number	Valor líquido creditado ao destinatário
`status`	string	Status da transferência (COMPLETED, PENDING, FAILED)
`created_at`	string	Data e hora de criação (ISO 8601)

Respostas de Erro

400 Bad Request

Possíveis mensagens:

"O email do destinatário é obrigatório"
"Email inválido"
"O valor da transferência é obrigatório"
"O valor da transferência deve ser maior que zero"
"O valor deve ser um número válido"
"Conta de destino não encontrada"
"Não é possível transferir para a própria conta"
"Saldo insuficiente para realizar a transferência. Necessário: R$ X.XX (valor: R$ Y.YY + taxa: R$ Z.ZZ)"
"Uma transferência com o mesmo valor para este destinatário foi realizada recentemente. Por favor, aguarde 5 minutos antes de tentar novamente."
"Transferência já processada anteriormente (idempotency)"

401 Unauthorized

"API Secret não fornecida"

403 Forbidden

Possíveis mensagens:

"Não é possível realizar transferências. Seu acesso está bloqueado."
"Saque automático não está habilitado para este usuário."
"Não é possível transferir para esta conta. O acesso está bloqueado."

404 Not Found

"Usuário não encontrado"

429 Too Many Requests

"Uma transferência já está sendo processada. Por favor, aguarde."

Regras de Negócio

Valor mínimo: R$ 0,01
Taxa: calculada automaticamente (percentual + valor fixo)
Saldo: deve cobrir valor + taxa
Duplicação: bloqueia transferências idênticas nos últimos 5 minutos
Idempotência: use Idempotency-Key para evitar duplicações
Validações: remetente e destinatário não podem estar bloqueados
Não é possível transferir para a própria conta
Saque automático deve estar habilitado

Exemplo Completo (JavaScript)

JavaScript

javascript

const axios = require('axios');
const crypto = require('crypto');

const API_SECRET = 'sua-api-secret-aqui';
const BASE_URL = 'https://api.example.com/v1';

async function criarTransferencia(toEmail, amount) {
  const idempotencyKey = crypto.randomUUID();
  
  try {
    const response = await axios.post(
      `${BASE_URL}/internal-transfer`,
      {
        to_email: toEmail,
        amount: amount
      },
      {
        headers: {
          'api-secret': API_SECRET,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Transferência criada:', response.data);
    return response.data.data;
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data.message);
    } else {
      console.error('Erro na requisição:', error.message);
    }
    throw error;
  }
}

// Uso
criarTransferencia('destinatario@example.com', 100.50);

Consultar Transferência Interna

Consulta os detalhes de uma transferência interna específica pelo ID.

GET

https://api.connectpay.vc/v1/internal-transfer/:transfer_id

v1.0

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário

Parâmetros de URL

Parâmetro	Tipo	Descrição
`transfer_id` obrigatório	string	ID único da transferência (UUID)

Exemplo de Requisição

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/internal-transfer/550e8400-e29b-41d4-a716-446655440000" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "Content-Type: application/json"

Resposta de Sucesso (200 OK)

Consultar Transferência Interna - Resposta

json

{
  "hasError": false,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from_account_id": "user-123",
    "to_account_id": "user-456",
    "to_account_email": "destinatario@example.com",
    "amount": 100.50,
    "fee": 2.50,
    "net_amount": 100.50,
    "status": "COMPLETED",
    "metadata": {},
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	string	ID único da transferência
`from_account_id`	string	ID da conta remetente
`to_account_id`	string	ID da conta destinatária
`to_account_email`	string	Email da conta destinatária
`amount`	number	Valor bruto transferido
`fee`	number	Taxa cobrada na transferência
`net_amount`	number	Valor líquido creditado ao destinatário
`status`	string	Status da transferência (COMPLETED, PENDING, FAILED)
`metadata`	object	Metadados adicionais da transferência
`created_at`	string	Data e hora de criação (ISO 8601)
`updated_at`	string	Data e hora da última atualização (ISO 8601)

Respostas de Erro

400 Bad Request

"ID da transferência é obrigatório"

401 Unauthorized

"API Secret não fornecida"

403 Forbidden

"Você não tem permissão para acessar esta transferência"

Nota: Você só pode consultar transferências que você criou (onde você é o remetente).

404 Not Found

Possíveis mensagens:

"Transferência interna não encontrada"
"Usuário não encontrado"

Regras de Negócio

Permissão: apenas o remetente pode consultar a transferência
Validação: o transfer_id deve ser um UUID válido
Autenticação: api-secret deve ser válido e pertencer ao remetente

Exemplo Completo (JavaScript)

JavaScript

javascript

const axios = require('axios');

const API_SECRET = 'sua-api-secret-aqui';
const BASE_URL = 'https://api.example.com/v1';

async function consultarTransferencia(transferId) {
  try {
    const response = await axios.get(
      `${BASE_URL}/internal-transfer/${transferId}`,
      {
        headers: {
          'api-secret': API_SECRET
        }
      }
    );
    
    console.log('Transferência encontrada:', response.data);
    return response.data.data;
  } catch (error) {
    if (error.response) {
      console.error('Erro:', error.response.data.message);
    } else {
      console.error('Erro na requisição:', error.message);
    }
    throw error;
  }
}

// Uso
consultarTransferencia('550e8400-e29b-41d4-a716-446655440000');

Status da Transferência

PENDING

Transferência em processamento

COMPLETED

Transferência concluída com sucesso

FAILED

Transferência falhou

Depósito Crypto

Cria uma nova transação de depósito em criptomoedas.

POST

https://api.connectpay.vc/v1/crypto/deposits

v1.0

Rate Limit

20 requisições por minuto

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário
`idempotency-key`	string	Chave única para garantir idempotência (opcional)

Interface TypeScript

Definição de Tipo

typescript

interface CreateCryptoDepositRequest {
  asset: "BTC" | "USDT" | "USDC" | "ETH";
  chain: "TRC20" | "ERC20" | "BEP20" | "BTC" | "POLYGON";
  amount: string;
  webhook_url?: string;
}

Exemplo de Requisição

Criar Depósito Crypto - Requisição

json

{
  "asset": "USDT",
  "chain": "ERC20",
  "amount": "100.50",
  "webhook_url": "https://seu-servidor.com/webhook"
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`asset` obrigatório	string	Moeda. Valores aceitos: BTC, USDT, USDC, ETH
`chain` obrigatório	string	Rede blockchain. Valores aceitos: TRC20, ERC20, BEP20, BTC, POLYGON
`amount` obrigatório	string	Quantidade a depositar. Número positivo maior que zero, até 18 casas decimais
`webhook_url`	string	URL para receber notificações sobre atualizações da transação (máximo 255 caracteres)

Validações

A chain deve ser compatível com o asset informado. O amount deve ser um número positivo maior que zero.

Exemplo de Requisição

cURL

bash

curl -X POST "https://api.connectpay.vc/v1/crypto/deposits" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "idempotency-key: unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT",
    "chain": "ERC20",
    "amount": "100.50",
    "webhook_url": "https://seu-servidor.com/webhook"
  }'

Resposta de Sucesso (200 OK)

Criar Depósito Crypto - Resposta

json

{
  "hasError": false,
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset": "USDT",
    "chain": "ERC20",
    "amount": "100.50",
    "net_amount": "99.50",
    "fee": "1.00",
    "deposit_address": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
    "qr_code": "data:image/png;base64,iVBORw0KG...",
    "expires_at": "2024-01-15T10:30:00.000Z",
    "status": "PENDING_CONFIRMATION",
    "created_at": "2024-01-15T09:30:00.000Z"
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`transaction_id`	string	ID único da transação
`asset`	string	Moeda depositada (em maiúsculas)
`chain`	string \| null	Rede blockchain (em maiúsculas)
`amount`	string	Valor original solicitado (antes da taxa)
`net_amount`	string	Valor líquido que será creditado (amount - fee)
`fee`	string	Taxa da plataforma (apenas no SDK)
`deposit_address`	string	Endereço para depósito
`qr_code`	string	QR Code do endereço (se disponível)
`expires_at`	Date	Data/hora de expiração do endereço de depósito
`status`	string	Status da transação (ex: PENDING_CONFIRMATION)
`created_at`	Date	Data/hora de criação da transação

Respostas de Erro

401 Unauthorized

"API Secret inválida"

400 Bad Request

"Serviço não habilitado"

Withdraw Crypto (Saque)

Cria uma nova transação de saque em criptomoedas.

POST

https://api.connectpay.vc/v1/crypto/withdraws

v1.0

Rate Limit

20 requisições por minuto

Headers

Parâmetro	Tipo	Descrição
`api-secret` obrigatório	string	Chave secreta da API do usuário
`idempotency-key`	string	Chave única para garantir idempotência (opcional)

Interface TypeScript

Definição de Tipo

typescript

interface CreateCryptoWithdrawRequest {
  asset: "BTC" | "USDT" | "USDC" | "ETH";
  chain: "TRC20" | "ERC20" | "BEP20" | "BTC" | "POLYGON";
  amount: string;
  wallet: string;
  webhook_url?: string;
}

Exemplo de Requisição

Criar Withdraw Crypto - Requisição

json

{
  "asset": "USDT",
  "chain": "ERC20",
  "amount": "50.00",
  "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
  "webhook_url": "https://seu-servidor.com/webhook"
}

Parâmetros da Requisição

Parâmetro	Tipo	Descrição
`asset` obrigatório	string	Moeda. Valores aceitos: BTC, USDT, USDC, ETH
`chain` obrigatório	string	Rede blockchain. Valores aceitos: TRC20, ERC20, BEP20, BTC, POLYGON
`amount` obrigatório	string	Quantidade a sacar. Número positivo maior que zero, até 18 casas decimais
`wallet` obrigatório	string	Endereço da carteira de destino
`webhook_url`	string	URL para receber notificações sobre atualizações da transação (máximo 255 caracteres)

Validações

A chain deve ser compatível com o asset informado. O amount deve ser um número positivo maior que zero. O usuário deve ter saldo suficiente (incluindo a taxa).

Exemplo de Requisição

cURL

bash

curl -X POST "https://api.connectpay.vc/v1/crypto/withdraws" \
  -H "api-secret: sua-api-secret-aqui" \
  -H "idempotency-key: unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT",
    "chain": "ERC20",
    "amount": "50.00",
    "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
    "webhook_url": "https://seu-servidor.com/webhook"
  }'

Resposta de Sucesso (200 OK)

Criar Withdraw Crypto - Resposta

json

{
  "hasError": false,
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "asset": "USDT",
    "chain": "ERC20",
    "amount": "50.00",
    "fee": "1.00",
    "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
    "status": "PROCESSING",
    "created_at": "2024-01-15T09:30:00.000Z"
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`transaction_id`	string	ID único da transação
`asset`	string	Moeda sacada (em maiúsculas)
`chain`	string \| null	Rede blockchain (em maiúsculas)
`amount`	string	Valor solicitado para saque
`fee`	string	Taxa da plataforma (apenas no SDK)
`wallet`	string	Endereço da carteira de destino
`status`	string	Status da transação (ex: PROCESSING)
`created_at`	Date	Data/hora de criação da transação

Respostas de Erro

401 Unauthorized

"API Secret inválida"

400 Bad Request

"Saldo insuficiente"

Listar Chains (Redes Blockchain)

Lista todas as redes blockchain suportadas, agrupadas por moeda.

GET

https://api.connectpay.vc/v1/crypto/chains

v1.0

Endpoint Público

Este endpoint não requer autenticação. Rate limit: 60 requisições por minuto.

Query Parameters (Opcionais)

Parâmetro	Tipo	Descrição
`asset`	string	Filtrar por uma moeda específica (ex: USDT, BTC, ETH)

Exemplo de Requisição - Todas as Chains

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/crypto/chains" \
  -H "Content-Type: application/json"

Exemplo de Requisição - Chains de um Asset

cURL

bash

curl -X GET "https://api.connectpay.vc/v1/crypto/chains?asset=USDT" \
  -H "Content-Type: application/json"

Resposta de Sucesso - Todas as Chains

Listar Chains - Resposta (Todas)

json

{
  "hasError": false,
  "data": {
    "BTC": [
      {
        "label": "Bitcoin",
        "value": "BTC",
        "description": "Rede Bitcoin"
      }
    ],
    "ETH": [
      {
        "label": "Ethereum",
        "value": "ERC20",
        "description": "Rede Ethereum (ERC20)"
      }
    ],
    "USDT": [
      {
        "label": "Ethereum",
        "value": "ERC20",
        "description": "Rede Ethereum (ERC20)"
      },
      {
        "label": "Binance Smart Chain",
        "value": "BEP20",
        "description": "Rede Binance Smart Chain (BEP20)"
      },
      {
        "label": "Polygon",
        "value": "POLYGON",
        "description": "Rede Polygon"
      }
    ],
    "USDC": [
      {
        "label": "Ethereum",
        "value": "ERC20",
        "description": "Rede Ethereum (ERC20)"
      },
      {
        "label": "Binance Smart Chain",
        "value": "BEP20",
        "description": "Rede Binance Smart Chain (BEP20)"
      },
      {
        "label": "Polygon",
        "value": "POLYGON",
        "description": "Rede Polygon"
      }
    ]
  }
}

Resposta de Sucesso - Chains de um Asset

Listar Chains - Resposta (Filtrado)

json

{
  "hasError": false,
  "data": {
    "asset": "USDT",
    "chains": [
      {
        "label": "Ethereum",
        "value": "ERC20",
        "description": "Rede Ethereum (ERC20)"
      },
      {
        "label": "Binance Smart Chain",
        "value": "BEP20",
        "description": "Rede Binance Smart Chain (BEP20)"
      },
      {
        "label": "Polygon",
        "value": "POLYGON",
        "description": "Rede Polygon"
      }
    ]
  }
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`label`	string	Nome amigável da rede (ex: "Ethereum", "Bitcoin")
`value`	string	Código interno usado nas requisições (ex: "ERC20", "BTC")
`description`	string	Descrição da rede

Nota Importante

Use o campo value da chain nas requisições de depósito e withdraw. Por exemplo, se o value for "ERC20", use "ERC20" no campo chain dos endpoints de depósito/withdraw.

Respostas de Erro

400 Bad Request

"Asset 'INVALID' não encontrado ou não possui chains suportadas"

400 Bad Request

"Serviço não habilitado"

Webhooks de Crypto

Receba notificações em tempo real quando o status das transações crypto mudar.

Headers do Webhook

Headers

http

Content-Type: application/json
User-Agent: Crypto-Webhook/1.0

Payload do Webhook

O payload é padronizado e enviado como JSON sempre que o status da transação é atualizado.

Interface do Payload

typescript

interface CryptoWebhook {
  id: string;
  type: "DEPOSIT" | "WITHDRAW" | "SWAP";
  asset: string;
  chain: string | null;
  amount: string;
  deposit_address?: string | null; // apenas para DEPOSIT
  wallet?: string | null; // apenas para WITHDRAW
  status: "PENDING_CONFIRMATION" | "PROCESSING" | "CONFIRMED" | "FAILED" | "CANCELED";
  platform_fee: string;
  tx_hash?: string | null;
  expires_at?: Date | null; // apenas para DEPOSIT
  created_at: Date;
  updated_at: Date;
  confirmed_at?: Date | null;
}

Exemplo de Payload - Depósito

Webhook de Depósito Crypto

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "DEPOSIT",
  "asset": "USDT",
  "chain": "ERC20",
  "amount": "100.50",
  "deposit_address": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
  "status": "CONFIRMED",
  "platform_fee": "1.00",
  "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "expires_at": "2024-01-15T10:30:00.000Z",
  "created_at": "2024-01-15T09:30:00.000Z",
  "updated_at": "2024-01-15T10:00:00.000Z",
  "confirmed_at": "2024-01-15T10:00:00.000Z"
}

Exemplo de Payload - Withdraw

Webhook de Withdraw Crypto

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "WITHDRAW",
  "asset": "USDT",
  "chain": "ERC20",
  "amount": "50.00",
  "wallet": "0x742d35Cc1D1B2F48dE3D7d8c53c4E7Db0C4bC123",
  "status": "CONFIRMED",
  "platform_fee": "1.00",
  "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "created_at": "2024-01-15T09:30:00.000Z",
  "updated_at": "2024-01-15T10:00:00.000Z",
  "confirmed_at": "2024-01-15T10:00:00.000Z"
}

Campos do Payload

Parâmetro	Tipo	Descrição
`id`	string	ID da transação (crypto_transaction.id)
`type`	string	Tipo da transação. Valores: DEPOSIT, WITHDRAW, SWAP
`asset`	string	Moeda da transação
`chain`	string \| null	Rede blockchain
`amount`	string	Quantidade da transação
`deposit_address`	string \| null	Endereço de depósito (apenas para DEPOSIT)
`wallet`	string \| null	Endereço da carteira de destino (apenas para WITHDRAW)
`status`	string	Status atual da transação (ex: PENDING_CONFIRMATION, CONFIRMED, FAILED, PROCESSING)
`platform_fee`	string	Taxa da plataforma cobrada
`tx_hash`	string \| null	Hash da transação na blockchain (quando disponível)
`expires_at`	Date \| null	Data/hora de expiração do endereço de depósito (apenas para DEPOSIT)
`created_at`	Date	Data/hora de criação da transação
`updated_at`	Date	Data/hora da última atualização
`confirmed_at`	Date \| null	Data/hora de confirmação da transação (quando disponível)

Status Possíveis das Transações

PENDING_CONFIRMATION

Aguardando confirmação (depósitos)

PROCESSING

Em processamento (saques)

CONFIRMED

Confirmada e finalizada

FAILED

Falhou

CANCELED

Cancelada

Comportamento do Webhook

O webhook é enviado após o processamento de atualizações do provedor
Timeout: 10 segundos
O sistema registra tentativas e respostas em logs internos
O webhook é enviado sempre que o status da transação muda
O servidor deve responder com status HTTP 2xx para indicar recebimento

Observações Importantes

Idempotência: Use o header idempotency-key para evitar duplicação de transações
Taxa: O campo fee aparece apenas nas respostas do SDK, não nas do frontend
Compatibilidade: Verifique a compatibilidade entre asset e chain antes de enviar. Use o endpoint /v1/crypto/chains para listar as chains suportadas por cada asset
Webhooks: A URL do webhook deve ser acessível publicamente e responder em até 10 segundos
Valores: Todos os valores monetários são strings para preservar precisão decimal
Chains: Use o campo value retornado pelo endpoint de chains nas requisições de depósito/withdraw

Webhooks de Transação PIX

Receba notificações em tempo real quando o status das transações mudar.

Payload do Webhook

Este payload é enviado para sua URL de webhook sempre que o status de uma transação muda.

Interface do Payload

typescript

interface TransactionWebhook {
  id: string;
  external_id: string | null;
  total_amount: number;
  status: "AUTHORIZED" | "PENDING" | "CHARGEBACK" | "FAILED" | "IN_DISPUTE";
  payment_method: string;
}

Exemplo de Payload

Atualização de Status da Transação

json

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "status": "AUTHORIZED",
  "payment_method": "PIX"
}

Melhores Práticas para Webhooks

Responda com código HTTP 200 para confirmar recebimento
Implemente lógica de retry para falhas temporárias
Verifique assinaturas de webhook para segurança

Processe webhooks de forma assíncrona
Use chaves de idempotência para duplicatas
Mantenha logs detalhados para debugging

Exemplo de Implementação

Node.js + Express

javascript

app.post('/webhooks/transactions', (req, res) => {
  const { id, external_id, total_amount, status, payment_method } = req.body;
  
  // Processar o webhook de forma assíncrona
  processTransactionWebhook({
    id,
    external_id,
    total_amount,
    status,
    payment_method
  });
  
  // Responder imediatamente com 200
  res.status(200).json({ received: true });
});

Webhooks de Cashout PIX

Seja notificado quando ocorrerem mudanças de status nos cashouts.

Status Possíveis do Cashout

approved

Cashout aprovado e processado

pending

Cashout aguardando processamento

processing

Cashout sendo processado

failed

Falha no processamento

rejected

Cashout rejeitado

Exemplo de Payload

Atualização de Status do Cashout

json

{
  "id": "f2c5f6e7-f710-437f-ad8c-44022316123e",
  "external_id": "saque_12345",
  "status": "approved",
  "total_amount": 250.00,
  "pix_key": "joao.silva@exemplo.com"
}

Webhooks de Fatura Interna

Receba notificações em tempo real quando o status das faturas internas mudar.

Quando os Webhooks são Enviados

Os webhooks são enviados automaticamente quando ocorrem mudanças de status:

Quando a fatura é paga

status: "PAID"

Quando a fatura expira

status: "EXPIRED"

Formato do Webhook

Configurações e formato do webhook enviado para sua URL.

Método e Headers

Configuração

text

Método: POST
Content-Type: application/json
User-Agent: Invoice-Webhook/1.0
Timeout: 10 segundos

Payload do Webhook

Este payload é enviado para sua URL de webhook sempre que o status de uma fatura interna muda.

Interface do Payload

typescript

interface InternalInvoiceWebhook {
  id: string;                    // UUID da cobrança
  code: string;                  // Código único de 8 caracteres
  amount: number;                 // Valor da cobrança
  status: "PENDING" | "PAID" | "CANCELLED" | "EXPIRED";
  description: string;            // Descrição da cobrança
  due_date: string | null;        // Data de vencimento (ISO 8601) ou null
  created_at: string;             // Data de criação (ISO 8601)
  updated_at: string;             // Data de atualização (ISO 8601)
}

Exemplos de Payload

Webhook - Fatura Paga

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "ABC12345",
  "amount": 100.50,
  "status": "PAID",
  "description": "Pagamento de serviços",
  "due_date": "2026-02-15T10:00:00Z",
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T15:30:00Z"
}

Webhook - Fatura Expirada

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "ABC12345",
  "amount": 100.50,
  "status": "EXPIRED",
  "description": "Pagamento de serviços",
  "due_date": "2026-01-27T10:00:00Z",
  "created_at": "2026-01-20T10:00:00Z",
  "updated_at": "2026-01-28T16:00:00Z"
}

Melhores Práticas para Webhooks

Responda com código HTTP 200 para confirmar recebimento
Implemente lógica de retry para falhas temporárias
Verifique assinaturas de webhook para segurança

Processe webhooks de forma assíncrona
Use chaves de idempotência para duplicatas
Mantenha logs detalhados para debugging

Exemplo de Implementação

Node.js + Express

javascript

app.post('/webhooks/internal-invoice', (req, res) => {
  const { id, code, amount, status, description, due_date, created_at, updated_at } = req.body;
  
  // Processar o webhook de forma assíncrona
  processInternalInvoiceWebhook({
    id,
    code,
    amount,
    status,
    description,
    due_date,
    created_at,
    updated_at
  });
  
  // Responder imediatamente com 200
  res.status(200).json({ received: true });
});

Importante

O webhook será enviado apenas quando o status mudar para PAID ou EXPIRED
O timeout do webhook é de 10 segundos - certifique-se de responder rapidamente
A URL do webhook deve ser configurada no campo webhook_url ao criar a fatura
O campo due_date pode ser null se não houver data de vencimento configurada

Formato de Resposta

Formatos de resposta padrão e códigos de status utilizados pela API.

Resposta de Sucesso

Formato de Sucesso

json

{
  "data": {
    // Dados da resposta aqui
  },
  "success": true
}

Resposta de Erro

Formato de Erro

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados de requisição inválidos",
    "details": []
  },
  "success": false
}

Status das Transações

Valores possíveis para o campo status nas transações

PENDING

Transação aguardando pagamento

AUTHORIZED

Pagamento aprovado e processado

FAILED

Falha no processamento do pagamento

CHARGEBACK

Chargeback foi iniciado

IN_DISPUTE

Transação está em disputa

Códigos de Erro

Códigos de status HTTP e respostas de erro retornadas pela API.

400

Bad Request

A requisição era inválida ou não pode ser atendida. Causas comuns:

Parâmetros obrigatórios ausentes
Valores ou formatos de parâmetros inválidos
JSON malformado no corpo da requisição

401

Unauthorized

Falha na autenticação. Causas comuns:

Cabeçalho API secret ausente
API secret inválido ou expirado
API secret para ambiente incorreto

404

Not Found

O recurso solicitado não foi encontrado. Causas comuns:

URL do endpoint inválida
ID da transação não existe
Recurso foi deletado

500

Internal Server Error

Ocorreu um erro inesperado em nossos servidores. Tente novamente mais tarde ou entre em contato com o suporte se o problema persistir.

Dica de Debugging

Todos os erros incluem um campo message com detalhes específicos sobre o problema. Use essas mensagens para diagnosticar e corrigir problemas de integração rapidamente.