Skip to main content

Prompt — Woovi Subaccounts and Pix Split Integration

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 create subaccounts (sub-accounts) and perform Pix splits between the main account and subaccounts — an essential flow for marketplaces, SaaS platforms, franchises, multi-seller platforms, and White Labels.

Critical Rule​

Always generate code based on the examples below. A subaccount in Woovi is represented by the Pix key of the secondary recipient. All value splits are done in cents (integers) and the sum of the splits cannot exceed the total charge value.

Technical Specification​

Subaccounts​

  • Create: POST https://api.woovi.com/api/v1/subaccount
  • List: GET https://api.woovi.com/api/v1/subaccount
  • Detail: GET https://api.woovi.com/api/v1/subaccount/{pixKey}
  • Withdraw to holder account: POST https://api.woovi.com/api/v1/subaccount/{pixKey}/withdraw
  • Headers: Authorization: <APP_ID>, Content-Type: application/json

Body — create subaccount​

FieldTypeRequiredDescription
namestringyesSubaccount name (seller, merchant, partner)
pixKeystringyesPix withdrawal key of the subaccount holder

Charge Split​

Add the splits field to the body of POST /charge:

{
  "correlationID": "uuid",
  "value": 10000,
  "splits": [
    { "value": 7000, "pixKey": "[email protected]", "splitType": "SPLIT_SUB_ACCOUNT" },
    { "value": 1500, "pixKey": "[email protected]", "splitType": "SPLIT_SUB_ACCOUNT" }
  ]
}

The difference between the total value and the sum of splits stays in the main account (platform fee).

Split Types (splitType)​

  • SPLIT_SUB_ACCOUNT — splits to a Woovi subaccount (100% internal recipient).
  • SPLIT_PARTNER — splits to an external Woovi partner (see partner.md).

Implementation Rules​

  1. Create the subaccount before using it in a split — otherwise POST /charge will fail.
  2. Values in cents (integers) and the sum must be less than or equal to the charge value.
  3. Use a unique correlationID per charge and maintain split traceability (vendorOrderId → correlationID).
  4. The subaccount accumulates balance until the withdrawal (/withdraw) — design a periodic payout job.
  5. The events OPENPIX:SUBACCOUNT_CREATED and OPENPIX:CHARGE_COMPLETED are useful in the webhook.
  6. Backend-only.

Code Examples​

Create subaccount​

await axios.post(
  "https://api.woovi.com/api/v1/subaccount",
  {
    name: "João's Store",
    pixKey: "[email protected]"
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

Charge with split​

const { data } = await axios.post(
  "https://api.woovi.com/api/v1/charge",
  {
    correlationID: crypto.randomUUID(),
    value: 10000, // R$ 100.00
    comment: "Marketplace order #42",
    splits: [
      { value: 7000, pixKey: "[email protected]",  splitType: "SPLIT_SUB_ACCOUNT" }, // seller receives 70
      { value: 1500, pixKey: "[email protected]", splitType: "SPLIT_SUB_ACCOUNT" }  // co-seller receives 15
      // remainder (15) stays as platform fee
    ]
  },
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

Withdraw subaccount balance​

await axios.post(
  `https://api.woovi.com/api/v1/subaccount/${encodeURIComponent("[email protected]")}/withdraw`,
  { value: 7000 }, // optional — if omitted, withdraws the full balance
  { headers: { Authorization: process.env.WOOVI_APP_ID } }
);

Node.js / Express — marketplace​

app.post("/order", async (req, res) => {
  const { items, vendorPixKey, platformFeeBps } = req.body;
  const total = items.reduce((s, i) => s + i.price * i.qty, 0);
  const platformFee = Math.round((total * platformFeeBps) / 10_000);
  const vendorShare = total - platformFee;

  const { data } = await woovi.post("/charge", {
    correlationID: randomUUID(),
    value: total,
    comment: `Order ${req.body.id}`,
    splits: [
      { value: vendorShare, pixKey: vendorPixKey, splitType: "SPLIT_SUB_ACCOUNT" }
    ]
  });
  res.json({ paymentLinkUrl: data.charge.paymentLinkUrl });
});

Expected API Response (create subaccount)​

{
  "subAccount": {
    "name": "João's Store",
    "pixKey": "[email protected]",
    "balance": 0
  }
}

Expected Output Format​

  1. createSubAccount({name, pixKey}) function.
  2. createSplitCharge({total, splits}) function validating that sum(splits) <= total.
  3. Scheduled withdrawal job (subaccount/withdraw) for each subaccount with balance > threshold.
  4. Local table subaccounts (pixKey PK, name, balance, lastWithdrawAt) for reconciliation.
  5. Webhook listener OPENPIX:CHARGE_COMPLETED that credits the subaccount.