Realizar pago PIX (Cash-Out)

POST /api/pix/cash-outCopy Anchor Link

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

Envia un pago PIX a una clave PIX de destino. La transaccion se crea con estado PENDING y el resultado final se notifica via webhook o puede consultarse via polling.

AutenticacionCopy Anchor Link

Requiere un Bearer token en el header Authorization.

Request BodyCopy Anchor Link

Formatos aceptados para details.keyCopy Anchor Link

Ejemplos de RequestCopy Anchor Link

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

Verificación de titularidad por liquidanteCopy Anchor Link

La API Gateways valida details.document solo en cuanto al formato (11 o 14 dígitos y dígitos verificadores) y valida details.key según el formato esperado para el keyType. No compara details.document con details.key, no consulta la DICT y no bloquea la operación cuando ambos divergen. El pago siempre se direcciona por la clave PIX.

La verificación del documento contra el titular real de la clave, cuando existe, la realiza el proveedor de liquidación configurado en su cuenta:

• Algunos proveedores verifican details.document siempre que se envía el campo. Si hay divergencia, la transacción termina en ERROR, sin débito, y el webhook trae el mensaje del proveedor.
• Otros solo realizan la verificación cuando usted envía details.checkPixKeyWithDocument: true.
• En los demás, el campo se acepta pero no se verifica: el pago se acredita al dueño de la clave.

¿Cómo saber el comportamiento de mi cuenta? El proveedor de liquidación se define por cuenta. En caso de duda, consulte a su gerente de integración. Si su operación exige que un documento divergente bloquee el pago, valide la titularidad de su lado antes de enviar: para keyType: DOCUMENT, asegúrese de que details.document sea igual a details.key.

Ejemplos de CódigoCopy 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"
}

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