Send PIX Payment (Cash-Out)

POST /api/pix/cash-outCopy Anchor Link

POST https://<api-host>/api/pix/cash-out

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.

AuthenticationCopy Anchor Link

Requires a Bearer token in the Authorization header.

Request BodyCopy Anchor Link

Accepted formats for details.keyCopy Anchor Link

Request ExamplesCopy Anchor Link

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

Ownership verification by settlement providerCopy Anchor Link

The Gateways 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 ExamplesCopy Anchor Link

curl -X POST "https://<api-host>/api/pix/cash-out" \
  -H "Authorization: Bearer $PIX_API_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-host>/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.PIX_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

Response (201 Created)Copy Anchor Link

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

ErrorsCopy Anchor Link

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