Transferência PIX

Visão Geral

O endpoint POST /api/dict/pix inicia uma transferência PIX para a chave informada. A chave pode ser CPF, CNPJ, e-mail, telefone ou EVP (chave aleatória).

A resposta síncrona confirma que a transferência foi aceita para processamento. O resultado final (LIQUIDATED ou ERROR) chega pelo webhook TRANSFER.

Endpoint

POST https://api.fypay.me/api/dict/pix

Headers

stringobrigatorio

Token Bearer obtido em POST https://api.fypay.me/api/auth/token. Esta rota não usa certificado de cliente.

stringobrigatorio

Identificador único da transferência gerado pelo seu sistema. Até 50 caracteres e único por conta (um UUID é uma boa escolha). Ele vira o identificador externo da transação e volta nos campos endToEndId da resposta e idempotencyKey do webhook TRANSFER.

Exemplo: 550e8400-e29b-41d4-a716-446655440000

Request Body

stringobrigatorio

Chave PIX de destino. O tipo é identificado pelo formato:

E-mail: contém @
EVP: UUID (chave aleatória)
Telefone: com DDI, no formato +55DDDNUMERO (ex.: +5511999999999)
CPF: 11 dígitos
CNPJ: 14 dígitos

string

CPF ou CNPJ do destinatário. É repassado ao provedor de liquidação, e alguns provedores exigem esse documento. Quando omitido, a API usa os dígitos da própria chave.

string

Mensagem que acompanha a transferência PIX. Volta em data.remittanceInformation no webhook TRANSFER.

objectobrigatorio

Dados do pagamento.

string

HIGH ou NORM. Aceito por compatibilidade e validado, mas não altera o processamento.

string

Aceito por compatibilidade, sem efeito.

number

Entre 1 e 10800. Aceito por compatibilidade e validado, mas não altera o processamento.

array

Lista de strings. Aceito por compatibilidade, sem efeito: a API não bloqueia instituições por ISPB.

Request

curl -X POST https://api.fypay.me/api/dict/pix \
  -H "Authorization: Bearer <token>" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "destino@email.com",
    "creditorDocument": "12345678909",
    "description": "Pagamento referente a NF 12345",
    "payment": {
      "currency": "BRL",
      "amount": 100.50
    }
  }'

const idempotencyKey = crypto.randomUUID();

const response = await fetch('https://api.fypay.me/api/dict/pix', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'x-idempotency-key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pixKey: 'destino@email.com',
    creditorDocument: '12345678909',
    description: 'Pagamento referente a NF 12345',
    payment: {
      currency: 'BRL',
      amount: 100.50,
    },
  }),
});

const transfer = await response.json();

import requests
import uuid

idempotency_key = str(uuid.uuid4())

response = requests.post(
    'https://api.fypay.me/api/dict/pix',
    headers={
        'Authorization': f'Bearer {token}',
        'x-idempotency-key': idempotency_key,
        'Content-Type': 'application/json',
    },
    json={
        'pixKey': 'destino@email.com',
        'creditorDocument': '12345678909',
        'description': 'Pagamento referente a NF 12345',
        'payment': {
            'currency': 'BRL',
            'amount': 100.50,
        },
    }
)

transfer = response.json()

Response

{
  "endToEndId": "550e8400-e29b-41d4-a716-446655440000",
  "eventDate": "2024-01-15T10:30:00.000Z",
  "id": 12345,
  "payment": {
    "amount": 100.5
  },
  "type": "PENDING"
}

{
  "statusCode": 400,
  "code": "PIX_INSUFFICIENT_BALANCE",
  "userMessage": "Saldo insuficiente para realizar esta operação.",
  "details": {
    "availableReais": "50.00",
    "requiredReais": "100.50"
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

{
  "statusCode": 422,
  "code": "PIX_KEY_NOT_FOUND",
  "details": {
    "cached": true,
    "retryAfterSeconds": 300
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

Campos da Resposta

endToEndIdstring

Não é o End to End ID do PIX. Este campo devolve o valor do header x-idempotency-key. O End to End ID real chega em data.endToEndId no webhook TRANSFER.

eventDatestring

Data e hora de criação da transferência (ISO 8601).

idnumber

ID da transação na FyPay. É o mesmo valor de data.id no webhook TRANSFER.

paymentobject

typestring

Status da transação no momento da resposta:

PENDING: transferência em processamento (caso normal)
CONFIRMED: transferência já confirmada
ERROR: falha na transferência

Idempotência

O x-idempotency-key é obrigatório e precisa ser único por conta. Ele protege contra envio em dobro: se você repetir uma chave já usada, nenhuma nova transferência é criada e a API responde 400 com o código PIX_DUPLICATE_EXTERNAL_ID. O campo details.existingTransactionId traz o ID da transferência original.

const key = '550e8400-e29b-41d4-a716-446655440000';

const res1 = await createTransfer(key, { amount: 100 });

const res2 = await createTransfer(key, { amount: 100 });

A primeira chamada cria a transferência (201, type: "PENDING"). A segunda é recusada com 400 PIX_DUPLICATE_EXTERNAL_ID, sem débito. Para acompanhar o resultado da primeira, aguarde o webhook TRANSFER ou consulte GET https://api.fypay.me/api/pix/transaction/{id} com o id numérico ou com a própria chave.

Depois de um erro 5xx ou de um timeout, não troque a chave para tentar de novo: o pagamento pode ter saído. Aguarde o webhook TRANSFER correlacionando pelo data.idempotencyKey. Veja TRANSFER.

Webhook de Transferência

Quando a transferência for processada, as URLs cadastradas para o evento cash_out com o formato PIX BACEN recebem um webhook do tipo TRANSFER (trecho):

{
  "data": {
    "id": 12345,
    "txId": "550e8400-e29b-41d4-a716-446655440000",
    "pixKey": "destino@email.com",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.5",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "creditorAccount": {
      "ispb": "12345678",
      "name": "João Silva",
      "bankName": "Banco Exemplo S.A.",
      "issuer": "000",
      "number": "123456",
      "document": "12345678909",
      "accountType": null
    },
    "remittanceInformation": "Pagamento referente a NF 12345"
  },
  "type": "TRANSFER"
}

Webhook TRANSFER

Veja a documentação completa do webhook TRANSFER

Erros Comuns

Código HTTP	`code`	Causa	O que fazer
400	`PUB_REQUEST_BODY_INVALID`	Corpo inválido (`amount` ausente ou menor que `0.01`, `priority` fora de `HIGH`/`NORM` etc.)	Confira `details.violations`
400	`PIX_DUPLICATE_EXTERNAL_ID`	`x-idempotency-key` já usado nesta conta	Nada foi criado; veja `details.existingTransactionId`
400	`PIX_INSUFFICIENT_BALANCE`	Saldo insuficiente	Consulte o saldo e tente com uma nova chave
401		Token ausente, inválido ou expirado	Gere um novo token
422	`PIX_KEY_NOT_FOUND`	Chave não existe no DICT	Confirme a chave com o destinatário. Com `details.cached: true`, aguarde `details.retryAfterSeconds`. Veja Chave inexistente
429	`TOO_MANY_PIX_KEYS_NOT_FOUND`	Muitas chaves inexistentes no saque por chave	Aguarde o tempo do header `Retry-After`. Veja Provedor bloqueando consultas

Transferência PIX

Visão Geral

Endpoint

Headers

Request Body

Request

Response

Campos da Resposta

Idempotência

Webhook de Transferência

Webhook TRANSFER

Erros Comuns

Próximos Passos

Consultar Saldo

Webhook TRANSFER

Nesta página

Transferência PIX

Propriedades

Propriedades

Webhook TRANSFER

Consultar Saldo

Webhook TRANSFER

Nesta página