Transferências Internas

Realizar Transferência Interna

POST/v1/internal-transfer

Cria uma nova transferência entre contas internas. Exige o header Idempotency-Key para garantir que a mesma operação não seja processada mais de uma vez.

Idempotency-Key Obrigatório

O header Idempotency-Key é obrigatório neste endpoint. Gere um UUID único por requisição para evitar transferências duplicadas em caso de retry.

Headers Obrigatórios

Campo	Tipo	Descrição
`api-secret`obrigatório	`string`	Chave secreta da API
`Idempotency-Key`obrigatório	`string`	Chave única para garantir idempotência. Use um UUID único por requisição.
`Content-Type`obrigatório	`string`	application/json

Definição do Body

Interface TypeScripttypescript

interface CreateInternalTransferRequest {
  to_email: string;        // Email do destinatário (máx. 255 caracteres)
  amount: number;          // Valor em BRL (mín. 0.01, máx. 2 casas decimais)
  idempotency_key: string; // Chave de idempotência (pode vir no body ou no header)
}

Parâmetros do Body

Campo	Tipo	Descrição
`to_email`obrigatório	`string`	Email do destinatário. Máximo: 255 caracteres.
`amount`obrigatório	`number`	Valor da transferência em BRL. Mínimo: 0.01, máx. 2 casas decimais.
`idempotency_key`obrigatório	`string`	Chave de idempotência. Pode ser enviada no body ou no header Idempotency-Key.

Exemplo — Gerando Idempotency-Key

JavaScript (Node.js)javascript

const crypto = require('crypto');

async function realizarTransferencia(toEmail, amount) {
  const idempotencyKey = crypto.randomUUID();
  
  const response = await axios.post(
    `${BASE_URL}/v1/internal-transfer`,
    { to_email: toEmail, amount },
    {
      headers: {
        'api-secret': process.env.API_SECRET,
        'Idempotency-Key': idempotencyKey,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data.data;
}

Campos da Resposta

Campo	Tipo	Descrição
`id`	`string (UUID)`	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 operação
`net_amount`	`number`	Valor líquido creditado ao destinatário
`status`	`string`	COMPLETED \| PENDING \| FAILED
`created_at`	`string (ISO 8601)`	Data e hora de criação

Regras de Negócio

Valor mínimo: R$ 0,01
O saldo deve cobrir o valor + taxa
Não é possível transferir para a própria conta
Transferências idênticas (mesmo valor, mesmo destinatário) são bloqueadas por 5 minutos para evitar duplicações
Use Idempotency-Key para garantir que retries não gerem transferências duplicadas
Remetente e destinatário não podem estar com acesso bloqueado

Erros Possíveis

400

Dados inválidos ou regra de negócio violada

"O email do destinatário é obrigatório"
"Email inválido"
"O valor da transferência deve ser maior que zero"
"Conta de destino não encontrada"
"Não é possível transferir para a própria conta"
"Saldo insuficiente para realizar a transferência"
"Uma transferência com o mesmo valor para este destinatário foi realizada recentemente. Aguarde 5 minutos."
"Transferência já processada anteriormente (idempotency)"

401

Não autenticado

"API Secret não fornecida"

403

Acesso negado

"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

Não encontrado

"Usuário não encontrado"

429

Operação em andamento

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

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

Headers

api-secret: sua-api-secret-aqui
Idempotency-Key: $(uuidgen)
Content-Type: application/json

Request Body (JSON)

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

cURL

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

Response 200

{
  "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"
  }
}