Criar Transferência PIX

Esta seção explica como criar uma nova transferência PIX (transação de saque/envio) para enviar dinheiro para outra conta.

Visão Geral

As transferências PIX permitem que você envie dinheiro para outras contas usando chaves PIX. Você pode transferir para:

• CPF
• CNPJ
• E-mail
• Telefone
• Chave aleatória (EVP)

Importante

Antes de criar uma transferência, verifique se há saldo suficiente na conta. Consulte as Informações da Conta para verificar o saldo disponível.

Endpoint

POST /account/{account_id}/transfer/pix/create

Cria uma nova transferência PIX (transação de saque/envio).

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/transfer/pix/create

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Parâmetros da URL:

• account_id (obrigatório): ID da conta que realizará a transferência

Body:

{
  "pix_key": "700.592.353-73",
  "pix_type": "cpf",
  "amount": 0.01,
  "extra": {
    "document": "12345678900",
    "name": "Joao Silva"
  }
}

Campos do Body:

Campo	Tipo	Obrigatório	Descrição
pix_key	string	✅ Sim	Chave PIX do destinatário
pix_type	string	✅ Sim	Tipo da chave PIX
amount	number	✅ Sim	Valor da transferência (decimal)
extra	object	✅ Sim	Dados extra (Nome, documento, email)

Tipos de Chave PIX (pix_type):

Tipo	Descrição	Formato do pix_key
cpf	CPF	Apenas números (ex: 70059235373)
cnpj	CNPJ	Apenas números
email	E-mail	E-mail válido (ex: [email protected])
phone	Telefone	Formato: +5521999999999
evp	Chave aleatória	UUID (ex: 123e4567-e89b-12d3-a456-426614174000)

Exemplo de Requisição:

curl -X POST \
  'https://app.finexis.com.br/api/v1/gateway/account/6/transfer/pix/create' \
  -H 'Authorization: Bearer {seu_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "pix_key": "70059235373",
    "pix_type": "cpf",
    "amount": 0.01,
    "extra": {
      "name": "Maria da Silva",
      "document": "9876542100"
    }
  }'

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Transaction created successfully",
  "data": {
    "account_id": 6,
    "provider_id": 2,
    "type": "debit",
    "amount": "0.010000000000000000",
    "currency": "",
    "status": "pending",
    "description": null,
    "external_id": "bbd38496-4d8b-4a53-9b0e-3f1c761c70a3",
    "reference": "E45756448202511202220nq7ycQvyxkG",
    "metadata": {
      "uuid": "dff0c247-367b-441f-b9c5-ed8b7985078c",
      "end_to_end": "E45756448202511202220nq7ycQvyxkG",
      "transaction_id": 2011996,
      "reference": "bbd38496-4d8b-4a53-9b0e-3f1c761c70a3",
      "status": "pending",
      "type": "debit",
      "amount": 0.01,
      "description": null,
      "currency": "BRL",
      "nonce": "F4wtv5bhCtKwpCsV",
      "sha256": "04d2f269778f1b789301410a0ea388ce770aba82ecdc28233ab7f08b11bf0c50",
      "hash_schema": ["end_to_end", "value", "nonce"],
      "completed_at": "2025-11-20 22:20:51",
      "coust": 0,
      "transaction_time": 1763677251
    },
    "updated_at": "2025-11-20 22:20:51",
    "created_at": "2025-11-20 22:20:51",
    "id": 21,
    "account": {
      "id": 6,
      "user_id": 2,
      "name": "JOAO",
      "lastname": "USER",
      "number": "00000006",
      "avatar": null,
      "is_active": true,
      "created_at": "2025-11-16 21:15:17",
      "updated_at": "2025-11-20 21:49:52",
      "balance": {
        "id": 2,
        "account_id": 6,
        "currency": "BRL",
        "available": "0.10",
        "pending": "0.00",
        "is_frozen": true,
        "created_at": "2025-11-19 17:39:02",
        "updated_at": "2025-11-20 22:20:51"
      }
    }
  }
}

Campos Importantes da Resposta

Campo	Descrição
reference	Referência única da transação (use para consultar status)
external_id	ID externo da transação
type	Tipo de transação (debit para saque/envio)
status	Status da transação (pending, completed, failed, etc.)
metadata.end_to_end	Identificador end-to-end da transação PIX
account.balance.available	Saldo disponível da conta após a transação

Validações Importantes

Verificação de Saldo

Sempre verifique o saldo antes de criar uma transferência:

// 1. Consultar informações da conta
const accountInfo = await getAccountInfo(accountId);

// 2. Verificar saldo disponível
if (accountInfo.balance < amount) {
  throw new Error('Saldo insuficiente');
}

// 3. Criar transferência
const transfer = await createTransfer(accountId, pixKey, pixType, amount);

Formato das Chaves

Certifique-se de usar o formato correto para cada tipo de chave:

• CPF: Apenas números, sem pontos ou traços
• CNPJ: Apenas números, sem pontos, traços ou barras
• E-mail: Deve ser um e-mail válido
• Telefone: Formato internacional com código do país (ex: +5521999999999)
• EVP: UUID válido

Tipos de Transação

Tipo	Descrição
debit	Transação de débito (envio/saque) - valor é descontado da conta
credit	Transação de crédito (recebimento) - valor é creditado na conta

Próximos Passos

Após criar a transferência:

1. Consultar Status: Use Consultar Status para verificar se foi concluída
2. Listar Transferências: Use Listar Transferências para ver o histórico
3. Verificar Saldo: Consulte as Informações da Conta para confirmar o novo saldo