Send PIX Payment (Cash-Out)

POST /api/pix/cash-out

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

Requires a Bearer token in the Authorization header. See Generate Token to obtain one.

Sends a PIX payment to a destination PIX key. The transaction is created with status PENDING and the final result is notified via webhook or can be queried via polling.

Authentication

Requires a Bearer token in the Authorization header.

Request Body

Field	Type	Required	Description
`value`	number	Yes	Amount in BRL (up to 2 decimal places). Minimum: `0.01`
`externalId`	string	Yes	Unique external identifier per account (max 50 characters)
`description`	string	No	Transaction description (max 140 chars)
`details`	object	Yes	Destination PIX key information
`details.key`	string	Yes	Destination PIX key (see formats in the table below)
`details.keyType`	string	Yes	Key type: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`. Required because the API does not query DICT
`details.name`	string	No	Key holder name (max 100 characters). Some settlement providers require it: we recommend always sending it
`details.document`	string	No	Valid CPF (11 digits) or CNPJ (14 digits) of the key holder, digits only. Some settlement providers require it: we recommend always sending it. The API validates format only; see Ownership verification by settlement provider
`details.checkPixKeyWithDocument`	boolean	No	If `true`, requests a check that the key belongs to the CPF/CNPJ in `details.document`, rejecting the payment on mismatch. Requires `details.document` (without it, the API responds `400`). Only takes effect on settlement providers that support the check. Default: `false`

Accepted formats for `details.key`

`keyType`	Format	Example
`DOCUMENT`	CPF: 11 digits / CNPJ: 14 digits (numbers only)	`12345678909`, `12345678000195`
`EMAIL`	Valid email address	`usuario@exemplo.com`
`PHONE`	Area code + number (10-11 digits, without country code +55)	`11999999999`
`RANDOM`	UUID (with or without hyphens)	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

The payment is always addressed by the PIX key (details.key). The FyPay API validates the format of details.document, but does not compare it with details.key and does not query DICT before sending. Checking it against the actual key holder depends on your account's settlement provider (and, on some providers, on details.checkPixKeyWithDocument). Without that check, a mismatched details.document does not block the payment: the amount is credited to the key owner. See Ownership verification by settlement provider.

Request Examples

Payment by CPF — the most common case. The details.key and details.document must be the same (both are the CPF). The API does not verify this equality: enforce it on your side before sending.

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

Payment by CNPJ — common in B2B payments (suppliers, invoices).

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

Payment by email key. Note that details.document must be the CPF/CNPJ of the key holder (it cannot be inferred from the email). If your account's provider does not check ownership, a wrong document does not prevent the payment.

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

Payment by phone key. The format is area code + number (10 or 11 digits), without the country code +55.

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

Payment by random key (EVP/UUID). Generated by BACEN, it does not contain personal information.

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

Ownership verification by settlement provider

The FyPay API validates details.document only for format (11 or 14 digits and check digits) and validates details.key against the format expected for the keyType. It does not compare details.document with details.key, does not query DICT, and does not block the operation when the two differ. The payment is always addressed by the PIX key.

Checking the document against the actual key holder, where it exists, is done by the settlement provider configured on your account:

Some providers check details.document whenever the field is sent. On mismatch, the transaction ends in ERROR, with no debit, and the webhook carries the provider's message.
Others only perform the check when you send details.checkPixKeyWithDocument: true.
On the rest, the field is accepted but not checked: the payment is completed to the key owner.

How do I know how my account behaves? The settlement provider is defined per account. When in doubt, ask your integration manager. If your operation requires a mismatched document to block the payment, verify ownership on your side before sending: for keyType: DOCUMENT, make sure details.document equals details.key.

Code Examples

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)

Field	Type	Description
`transactionId`	string	Internal identifier of the generated transaction (numeric string)
`externalId`	string	External identifier provided in the request
`status`	string	Initial status: `PENDING`. Confirmation via webhook: `CONFIRMED` or `ERROR`
`generateTime`	string	Transaction generation date/time (ISO 8601 UTC)

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

Errors

Returned when the body does not pass validation. Errors in top-level fields (value, externalId, description, details or an unknown field) come with code: PUB_REQUEST_BODY_INVALID and the fields in details.violations, as in the example. Errors in details.* fields come with message as a list, one message per field.

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

Common causes:

value less than 0.01 or with more than 2 decimal places
details.keyType with invalid value
details.key does not match the keyType format
details.document with an invalid CPF/CNPJ
externalId longer than 50 characters or description longer than 140
details.checkPixKeyWithDocument: true without details.document

The available balance is less than the transaction amount + fee.

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

Other business errors in the same category:

Code	Description
`PIX_INSUFFICIENT_BALANCE`	Insufficient balance (amount + fee)
`PIX_TRANSACTION_LIMIT_EXCEEDED`	Amount exceeds per-transaction limit
`PIX_DAILY_LIMIT_EXCEEDED`	Daily accumulated amount exceeds daily limit
`PIX_NIGHT_LIMIT_EXCEEDED`	Nighttime operation exceeds reduced limit (8 PM - 6 AM)
`PIX_INVALID_AMOUNT`	Amount less than 0.01 or with more than 2 decimal places
`PIX_INVALID_PIX_KEY`	Key format does not match the provided `keyType`

The externalId has already been used for this account. Use a new identifier. Returns status 400 (not 409) with details containing the existing transaction ID.

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

The externalId works as an idempotency key. If you send the same request twice with the same externalId, the second call will return an error — ensuring the payment is not duplicated. The details.existingTransactionId field allows you to locate the original transaction.

See the safe retries guide.

When the answer comes from the denied-keys registry, the API returns 422 without creating any transaction and includes the Retry-After header. The details.cached: true field only appears when the answer comes from the registry. Without it, the PIX_KEY_NOT_FOUND came from the provider during the call itself. See Safeguards on Pix key cash-out.

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

The provider is blocking lookups. The API returns 429 without creating any transaction and includes the Retry-After header. Wait the indicated time and send the request again. See Safeguards on Pix key cash-out.

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

When the settling bank rejects the operation after the transaction is created, the status changes to ERROR and the errorCode/errorMessage fields are sent in the Cash-Out webhook:

`errorCode`	Description	Retryable?
`TAX_ID_MISMATCH`	The `details.document` does not match the PIX key holder (check performed by the settlement provider; see Ownership verification by settlement provider)	No — fix the CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ rejected as invalid by the settlement provider	No — fix the document
`BLOCKED_ACCOUNT`	Destination account judicially blocked	No
`ACCOUNT_CLOSED`	Destination account closed	No
`ORDER_REJECTED`	Destination bank rejected the operation	No
`PAYMENT_EXPIRED`	Transaction expired before being processed	Yes — resend
`SETTLEMENT_TIMEOUT`	Destination bank did not respond in time	Yes — resend

Webhook payload example with error:

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

When status is CONFIRMED, the errorCode and errorMessage fields are null. When status is ERROR, they indicate the reason for the rejection.

See the PIX Cash-Out integration guide for code examples, local key validation, and best practices.

Send PIX Payment (Cash-Out)

On this page