Realizar pagamento PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.fypay.me/api/pix/cash-out

Requer um Bearer token no header Authorization. Veja Gerar Token para obter um.

Envia um pagamento PIX para uma chave PIX de destino. A transação é criada com status PENDING e o resultado final é notificado via webhook ou pode ser consultado via polling.

Autenticação

Requer token Bearer no header Authorization.

Request Body

Campo	Tipo	Obrigatório	Descrição
`value`	number	Sim	Valor em reais (até 2 casas decimais). Mínimo: `0.01`
`externalId`	string	Sim	Identificador externo único por conta (máx 50 caracteres)
`description`	string	Não	Descrição da transação (máx 140 chars)
`details`	object	Sim	Informações da chave PIX de destino
`details.key`	string	Sim	Chave PIX de destino (veja formatos na tabela abaixo)
`details.keyType`	string	Sim	Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`. Obrigatório pois a API não consulta DICT
`details.name`	string	Não	Nome do titular da chave (máx 100 caracteres). Alguns provedores de liquidação exigem o campo: recomendamos enviar sempre
`details.document`	string	Não	CPF (11 dígitos) ou CNPJ (14 dígitos) válido do titular da chave, apenas números. Alguns provedores de liquidação exigem o campo: recomendamos enviar sempre. A API valida só o formato; veja Verificação de titularidade por liquidante
`details.checkPixKeyWithDocument`	boolean	Não	Se `true`, pede a conferência de que a chave pertence ao CPF/CNPJ de `details.document` e a rejeição do pagamento se divergir. Exige `details.document` (sem ele, a API responde `400`). Só tem efeito nos provedores de liquidação que suportam a conferência. Default: `false`

Formatos aceitos para `details.key`

`keyType`	Formato	Exemplo
`DOCUMENT`	CPF: 11 dígitos / CNPJ: 14 dígitos (apenas números)	`12345678909`, `12345678000195`
`EMAIL`	Endereço de email válido	`usuario@exemplo.com`
`PHONE`	DDD + número (10-11 dígitos, sem DDI +55)	`11999999999`
`RANDOM`	UUID (com ou sem hífens)	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

O pagamento é sempre endereçado pela chave PIX (details.key). A API FyPay valida o formato de details.document, mas não o compara com details.key nem consulta a DICT antes de enviar. A conferência com o titular real da chave depende do provedor de liquidação da sua conta (e, em alguns provedores, de details.checkPixKeyWithDocument). Sem essa conferência, um details.document divergente não bloqueia o pagamento: o valor é creditado ao dono da chave. Veja Verificação de titularidade por liquidante.

Exemplos de Request

Pagamento por CPF — o caso mais comum. O details.key e details.document devem ser iguais (ambos são o CPF). A API não verifica essa igualdade: garanta isso do seu lado antes de enviar.

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}

Pagamento por CNPJ — comum em pagamentos B2B (fornecedores, notas fiscais).

{
  "value": 4500.00,
  "externalId": "NF-2024-0089",
  "description": "NF 0089/2024 - Serviços de hospedagem",
  "details": {
    "key": "11222333000181",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000181"
  }
}

Pagamento por chave email. Note que details.document deve ser o CPF/CNPJ do titular da chave (não pode ser inferido pelo email). Se o liquidante da sua conta não confere titularidade, um documento errado não impede o pagamento.

{
  "value": 89.90,
  "externalId": "COMM-2024-0456",
  "description": "Comissão venda #456",
  "details": {
    "key": "vendedor@loja.com.br",
    "keyType": "EMAIL",
    "name": "Roberto Vendas",
    "document": "98765432100"
  }
}

Pagamento por chave telefone. O formato é DDD + número (10 ou 11 dígitos), sem o DDI +55.

{
  "value": 25.00,
  "externalId": "REEMB-2024-0012",
  "description": "Reembolso uber colaborador",
  "details": {
    "key": "11987654321",
    "keyType": "PHONE",
    "name": "Pedro Almeida",
    "document": "11122233396"
  }
}

Pagamento por chave aleatória (EVP/UUID). Gerada pelo BACEN, não contém informação pessoal.

{
  "value": 1250.00,
  "externalId": "RENT-2024-JAN",
  "description": "Aluguel janeiro/2024",
  "details": {
    "key": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "keyType": "RANDOM",
    "name": "Imobiliária Central",
    "document": "55666777000181"
  }
}

Verificação de titularidade por liquidante

A API FyPay valida details.document apenas quanto ao formato (11 ou 14 dígitos e dígitos verificadores) e valida details.key quanto ao formato esperado para o keyType. Ela não compara details.document com details.key, não consulta a DICT e não bloqueia a operação quando os dois divergem. O pagamento é sempre endereçado pela chave PIX.

A conferência do documento com o titular real da chave, quando existe, é feita pelo provedor de liquidação configurado na sua conta:

Alguns provedores conferem details.document sempre que o campo é enviado. Em caso de divergência, a transação termina em ERROR, sem débito, e o webhook traz a mensagem do provedor.
Outros só fazem a conferência quando você envia details.checkPixKeyWithDocument: true.
Nos demais, o campo é aceito mas não é conferido: o pagamento é efetivado ao dono da chave.

Como saber o comportamento da minha conta? O provedor de liquidação é definido por conta. Em caso de dúvida, consulte seu gerente de integração. Se a sua operação exige que um documento divergente bloqueie o pagamento, valide a titularidade do seu lado antes de enviar: para keyType: DOCUMENT, garanta que details.document seja igual a details.key.

Exemplos de Código

cURL

curl -X POST "https://api.fypay.me/api/pix/cash-out" \
  -H "Authorization: Bearer $FYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.fypay.me/api/pix/cash-out',
  {
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.FYPAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.fypay.me/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["FYPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
},
)
print(response.json())

$ch = curl_init('https://api.fypay.me/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "value": 150.00,
      "externalId": "PAG-2024-0001",
      "description": "Pagamento freelancer - Janeiro/2024",
      "details": {
        "key": "12345678909",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678909"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.fypay.me/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("FYPAY_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response (201 Created)

Campo	Tipo	Descrição
`transactionId`	string	Identificador interno da transação gerada (string numérica)
`externalId`	string	Identificador externo informado na requisição
`status`	string	Status inicial: `PENDING`. Confirmação via webhook: `CONFIRMED` ou `ERROR`
`generateTime`	string	Data/hora de geração da transação (ISO 8601 UTC)

{
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Erros

Retornado quando o body não atende as validações. Erros nos campos de primeiro nível (value, externalId, description, details ou campo desconhecido) vêm com code: PUB_REQUEST_BODY_INVALID e os campos em details.violations, como no exemplo. Erros nos campos de details.* vêm com message em forma de lista, uma mensagem por campo.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_REQUEST_BODY_INVALID",
  "message": "Request body validation failed: value: value must not be less than 0.01",
  "userMessage": "Request body is invalid.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "details": {
    "violations": {
      "value": "value must not be less than 0.01"
    }
  }
}

Causas comuns:

value menor que 0.01 ou com mais de 2 casas decimais
details.keyType com valor inválido
details.key não corresponde ao formato do keyType
details.document com CPF/CNPJ inválido
externalId com mais de 50 caracteres ou description com mais de 140
details.checkPixKeyWithDocument: true sem details.document

O saldo disponível é menor que o valor da transação + taxa.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente para realizar esta operação.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "b2c3d4e5f6a7890123456789abcdef02",
  "errorCode": "PIX_INSUFFICIENT_BALANCE"
}

Outros erros de negócio na mesma categoria:

Código	Descrição
`PIX_INSUFFICIENT_BALANCE`	Saldo insuficiente (valor + taxa)
`PIX_TRANSACTION_LIMIT_EXCEEDED`	Valor excede o limite por transação
`PIX_DAILY_LIMIT_EXCEEDED`	Acumulado do dia excede o limite diário
`PIX_NIGHT_LIMIT_EXCEEDED`	Operação noturna excede o limite reduzido (20h–6h)
`PIX_INVALID_AMOUNT`	Valor menor que 0.01 ou com mais de 2 casas decimais
`PIX_INVALID_PIX_KEY`	Formato da chave não corresponde ao `keyType` informado

O externalId já foi utilizado para esta conta. Use um novo identificador. Retorna status 400 (não 409) com details contendo o ID da transação existente.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "Esta transação já existe no sistema.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "c57c14ee10aabd82e40dae9b940706e0",
  "errorCode": "PIX_DUPLICATE_EXTERNAL_ID",
  "details": {
    "externalId": "external-teste-002",
    "existingTransactionId": 466208
  }
}

O externalId funciona como chave de idempotência. Se você enviar a mesma requisição duas vezes com o mesmo externalId, a segunda chamada retornará erro — garantindo que o pagamento não seja duplicado. O campo details.existingTransactionId permite localizar a transação original.

Veja o guia de retentativas seguras.

Quando a resposta vem do registro de chaves negadas, a API devolve 422 sem criar nenhuma transação e inclui o cabeçalho Retry-After. O campo details.cached: true só aparece quando a resposta vem do registro. Sem ele, o PIX_KEY_NOT_FOUND veio do provedor na própria chamada. Veja Proteções no saque Pix por chave.

{
  "statusCode": 422,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_KEY_NOT_FOUND",
  "message": "Chave Pix não encontrada",
  "userMessage": "Chave Pix não encontrada",
  "errorId": "d4e5f6a7b8c9012345678909abcdef03",
  "errorCode": "PIX_KEY_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 900,
    "source": "provider-guard",
    "cached": true
  }
}

O provedor está bloqueando consultas. A API devolve 429 sem criar nenhuma transação e inclui o cabeçalho Retry-After. Aguarde o tempo indicado e repita o envio. Veja Proteções no saque Pix por chave.

{
  "statusCode": 429,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "message": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "userMessage": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "errorId": "e5f6a7b8c9d0123456789092abcdef04",
  "errorCode": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 60,
    "source": "provider-guard"
  }
}

Quando o banco liquidante rejeita a operação após a criação da transação, o status muda para ERROR e os campos errorCode/errorMessage são preenchidos no webhook de Cash-Out:

`errorCode`	Descrição	Retentável?
`TAX_ID_MISMATCH`	O `details.document` não corresponde ao titular da chave PIX (conferência feita pelo provedor de liquidação; veja Verificação de titularidade por liquidante)	Não — corrija o CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ rejeitado como inválido pelo provedor de liquidação	Não — corrija o documento
`BLOCKED_ACCOUNT`	Conta de destino bloqueada judicialmente	Não
`ACCOUNT_CLOSED`	Conta de destino encerrada	Não
`ORDER_REJECTED`	Banco de destino rejeitou a operação	Não
`PAYMENT_EXPIRED`	Transação expirou antes de ser processada	Sim — reenvie
`SETTLEMENT_TIMEOUT`	Banco de destino não respondeu a tempo	Sim — reenvie

Exemplo de payload do webhook com erro:

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "endToEndId": "E17758345EYNKPHCJKMS",
  "pixKey": "12345678909",
  "feeAmount": 0.07,
  "originalAmount": 1,
  "finalAmount": 1.07,
  "processingDate": "2026-04-10T15:22:49.970Z",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O documento informado não corresponde ao titular da chave PIX",
  "counterpart": {
    "name": "João Silva",
    "document": "12345678909",
    "bank": {
      "bankISPB": "13140088",
      "bankName": "ACESSO SOLUÇÕES DE PAGAMENTO S.A.",
      "bankCode": "332",
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

Quando status é CONFIRMED, os campos errorCode e errorMessage são null. Quando status é ERROR, eles indicam o motivo da rejeição.

Consulte o guia de integração PIX Cash-Out para exemplos de código, validação local de chaves e boas práticas.

Realizar pagamento PIX (Cash-Out)

Nesta página