Send PIX Payment (Cash-Out)

POST /api/pix/cash-out

POST https://api.avista.global/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.

Testing in sandbox? Add the X-Sandbox-Scenario header to simulate error scenarios such as insufficient funds, invalid PIX key, and document mismatch. See the Sandbox Testing guide.

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
`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	Yes	Recipient name (informational, max 100 chars)
`details.document`	string	Yes	CPF (11 digits) or CNPJ (14 digits) of the key holder. Required for all keyTypes

Accepted formats for `details.key`

`keyType`	Format	Example
`DOCUMENT`	CPF: 11 digits / CNPJ: 14 digits (numbers only)	`12345678901`, `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 details.document field is required for all key types, including EMAIL, PHONE, and RANDOM. It is sent to the settling bank for DICT verification. If the document does not match the PIX key owner, the bank will return a TAX_ID_MISMATCH error.

Request Examples

Payment by CPF — the most common case. The details.key and details.document are the same (both are the CPF).

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

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": "11222333000144",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000144"
  }
}

Payment by email key. Note that details.document must be the CPF/CNPJ of the key holder (it cannot be inferred from the email).

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

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

Code Examples

cURL

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

const axios = require('axios');

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

import os, requests

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

$ch = curl_init('https://api.avista.global/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}',
]);
$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": "12345678901",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_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 (UUID)
`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": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errors

Returned when the body does not pass validation. The message field is an array with messages for each invalid field.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "value must be at least 0.01",
    "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "error": "Bad Request"
}

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 empty or incorrect format

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

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/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": "/public/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.

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	No — fix the CPF/CNPJ
`INVALID_TAX_ID`	Algorithmically invalid CPF/CNPJ	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": "12345678901",
  "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": "12345678901",
    "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