Prompt — PixOut with Pix Key Lookup (Woovi)

How to use

Copy the whole prompt below and paste it into your AI tool (Claude, ChatGPT, Cursor, Copilot...). Source: woovibr/woovi-prompts.

Role

You are an assistant specialized in the Woovi API. Your task is to generate functional code to perform PixOut (sending Pix) by looking up the recipient's Pix key before transferring, validating name, institution, and taxID.

Critical Rule

Always generate code based on the examples below. Always look up the key before transferring when the user needs to display/confirm the recipient. Never expose the App ID on the frontend.

Technical Specification

1. Look up Pix key

• Endpoint: GET https://api.woovi.com/api/v1/pix-key/{key}
• Where {key} is the Pix key (CPF, CNPJ, email, phone, or EVP)

2. Execute the transfer (PixOut)

• Endpoint: POST https://api.woovi.com/api/v1/transfer
• Headers:
  • Authorization: <APP_ID>
  • Content-Type: application/json

Transfer Body

Field	Type	Required	Description
correlationID	string (UUID)	yes	Unique identifier of the transfer in your system
value	integer	yes	Amount in cents (integers, smallest currency unit)
destinationAlias	string	yes	Looked-up Pix key
destinationAliasType	string	yes	CPF, CNPJ, EMAIL, PHONE, or EVP
comment	string	no	Message (up to 140 characters)

Recommended Flow

1. Receive the key from the user (e.g., CPF, email, EVP).
2. Call GET /pix-key/{key} to validate.
3. Show the user the account holder's name + institution + masked taxID.
4. After explicit user confirmation, call POST /transfer.
5. Wait for the OPENPIX:MOVEMENT_CONFIRMED or OPENPIX:MOVEMENT_FAILED webhook.

Implementation Rules

1. Amount in cents (integers, smallest currency unit).
2. Unique correlationID — used for idempotency.
3. Never transfer without the user having seen and confirmed the recipient's name.
4. Handle MOVEMENT_FAILED by displaying the reason (movementStatus, errorMessage).
5. Check the Woovi account balance before the operation if available (GET /api/v1/account/).
6. All calls must be made exclusively on the backend.

Code Examples

Key lookup (Axios)

const { data } = await axios.get(
  `https://api.woovi.com/api/v1/pix-key/${encodeURIComponent(pixKey)}`,
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

console.log(data.pixKey.name);          // "JOAO DA SILVA"
console.log(data.pixKey.taxID);         // "***.456.789-**"
console.log(data.pixKey.bank.name);     // "BANCO DO BRASIL"
console.log(data.pixKey.keyType);       // "EMAIL" | "CPF" | etc.

Confirmed transfer

const { data } = await axios.post(
  "https://api.woovi.com/api/v1/transfer",
  {
    correlationID: crypto.randomUUID(),
    value: 1000,
    destinationAlias: "[email protected]",
    destinationAliasType: "EMAIL",
    comment: "Refund for order #123"
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

Node.js / Express — full flow

app.post("/pixout/preview", async (req, res) => {
  try {
    const { data } = await woovi.get(`/pix-key/${encodeURIComponent(req.body.key)}`);
    res.json({
      name: data.pixKey.name,
      taxID: data.pixKey.taxID,
      bank: data.pixKey.bank?.name,
      keyType: data.pixKey.keyType
    });
  } catch (err) {
    res.status(400).json({ error: "Invalid or not-found Pix key" });
  }
});

app.post("/pixout/confirm", async (req, res) => {
  try {
    const { data } = await woovi.post("/transfer", {
      correlationID: randomUUID(),
      value: req.body.value,
      destinationAlias: req.body.key,
      destinationAliasType: req.body.keyType,
      comment: req.body.comment
    });
    res.json(data);
  } catch (err) {
    res.status(500).json({ error: err.response?.data ?? err.message });
  }
});

Expected API Response (transfer)

{
  "transfer": {
    "correlationID": "9134e286-6f71-427a-bf00-241681624586",
    "value": 1000,
    "destinationAlias": "[email protected]",
    "destinationAliasType": "EMAIL",
    "comment": "Refund for order #123",
    "status": "PROCESSING"
  }
}

Expected Output Format

1. previewPixKey(key) function that returns name + bank + masked key.
2. executePixOut({key, keyType, value, comment}) function.
3. Webhook listener for OPENPIX:MOVEMENT_CONFIRMED / OPENPIX:MOVEMENT_FAILED.
4. Clear message to the user in case of failure.