Prompt — PixOut without 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) without looking up the Pix key beforehand — a direct/automated flow for refunds, payouts, commissioning, or programmatic splits where the recipient is already trusted and pre-registered.

Critical Rule

Always generate code based on the examples below. Use this flow only when you already have certainty about the recipient (e.g., refund of the original purchase, known split, pre-registered partner). Never expose the App ID on the frontend.

Technical Specification

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

Body

Field	Type	Required	Description
correlationID	string (UUID)	yes	Unique identifier — idempotency key
value	integer	yes	Amount in cents (integers, smallest currency unit)
destinationAlias	string	yes	Destination Pix key
destinationAliasType	string	yes	CPF, CNPJ, EMAIL, PHONE, or EVP
comment	string	no	Message (up to 140 characters)

Typical Use Cases

• Partial refund after order cancellation (returns to the key already validated at purchase).
• Marketplace seller payouts with a previously registered and audited key.
• Commission / cashback payments in batches.
• B2B flows where the recipient is a contractual partner.

Implementation Rules

1. Idempotency: always reuse the same correlationID to retry the same transfer. Woovi does not duplicate.
2. Confirm the operation via the OPENPIX:MOVEMENT_CONFIRMED webhook.
3. On failure (OPENPIX:MOVEMENT_FAILED), record the reason and establish a retry policy (no immediate retry — wait for analysis).
4. Always validate the balance beforehand (recommended for batch payout flows).
5. Log correlationID, value, destinationAlias, recipient internal taxID for auditing.
6. Backend-only.

Code Examples

Vanilla JavaScript (fetch)

const response = await fetch("https://api.woovi.com/api/v1/transfer", {
  method: "POST",
  headers: {
    "Authorization": process.env.WOOVI_APP_ID,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    correlationID: "refund-order-123",
    value: 2500,
    destinationAlias: "31324227036",
    destinationAliasType: "CPF",
    comment: "Refund for order #123"
  })
});
const data = await response.json();

Axios — batch payout

async function executeBatchPayout(payouts) {
  const results = [];
  for (const p of payouts) {
    try {
      const { data } = await axios.post(
        "https://api.woovi.com/api/v1/transfer",
        {
          correlationID: p.id,                  // stable idempotency key
          value: p.valueCents,
          destinationAlias: p.pixKey,
          destinationAliasType: p.keyType,
          comment: p.comment ?? `Payout ${p.id}`
        },
        { headers: { Authorization: process.env.WOOVI_APP_ID } }
      );
      results.push({ id: p.id, status: "ok", data });
    } catch (err) {
      results.push({ id: p.id, status: "error", error: err.response?.data });
    }
  }
  return results;
}

Node.js / Express — refund endpoint

app.post("/refund", async (req, res) => {
  const order = await db.orders.findById(req.body.orderId);
  if (!order || order.status !== "PAID") {
    return res.status(400).json({ error: "Invalid order for refund" });
  }

  try {
    const { data } = await woovi.post("/transfer", {
      correlationID: `refund-${order._id}`,
      value: order.value,
      destinationAlias: order.payerPixKey,
      destinationAliasType: order.payerPixKeyType,
      comment: `Refund for order ${order._id}`
    });

    await db.orders.updateOne(
      { _id: order._id },
      { $set: { refundStatus: "PROCESSING", refundCorrelationID: data.transfer.correlationID } }
    );

    res.json(data);
  } catch (err) {
    res.status(500).json({ error: err.response?.data ?? err.message });
  }
});

Expected API Response

{
  "transfer": {
    "correlationID": "refund-order-123",
    "value": 2500,
    "destinationAlias": "31324227036",
    "destinationAliasType": "CPF",
    "comment": "Refund for order #123",
    "status": "PROCESSING",
    "createdAt": "2026-04-30T19:00:00.000Z"
  }
}

Expected Output Format

1. Idempotent transfer function.
2. Support for batch payout with individual error handling.
3. Webhook listener to confirm/reject.
4. Minimum auditing: structured log with correlationID, value, destinationAlias, status.