Realizar pagamento PIX (Cash-Out)

POST /api/pix/cash-outCopy Anchor Link

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

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çãoCopy Anchor Link

Requer token Bearer no header Authorization.

Request BodyCopy Anchor Link

Formatos aceitos para details.keyCopy Anchor Link

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

Verificação de titularidade por liquidanteCopy Anchor Link

A API Gateways 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ó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"
}

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