Payday as a loop over your approved list.
The agent reads the contractor list your team approved and pays each payee over Pix with codespar_pay: to a Pix key, or to bank details when the payee has no key. Each transfer carries its own idempotency key, so a retry returns the first result instead of paying again. Checking keys and tax IDs before the run and reconciling it in your ERP are your systems' part.
One run, one transfer per payee.
An example with demo data: the June run, read from the approved list and paid over Pix, one transfer per contractor, each with its own idempotency key.
- The list is the one your team approved
- One Pix per contractor, each with its own idempotency key
- Reconciling the run in the ERP is your integration
Run the June contractor payroll from the approved list.
24 contractors on the approved list: paying each one over Pix, one transfer per payee.
The conversation is the easy part.
Contractor payroll in LATAM is a monthly ritual: export a spreadsheet, generate a CNAB file, upload it to the bank portal, fix the rejects and reconcile by hand. It works until the same file goes up twice.
Build a CNAB file and upload it to the bank portal every month
The agent pays the approved list over Pix, one transfer per payee
Upload the same file twice and pay twice
Each transfer has an idempotency key; a retry returns the first result
Payees without a Pix key need another process
codespar_pay also pays to bank details when there is no key
Look up each transfer in the bank portal
codespar_pay action=status reads each payment by id
One call per payee, over Pix.
For each contractor on the approved list, the agent calls codespar_pay with method pix, the payee's key (or bank details), the amount in centavos and an idempotency key. action=status reads each payment later. The approved list, any check of keys and tax IDs before the run, and the reconciliation in your ERP are your integration.
Approved contractors
codespar_payOne Pix per payee
codespar_paySame key, first result
codespar_payEach payment by id
codespar_payThe run in your ERP
The approved list enters from your ERP or a sheet. The agent loops over it and calls codespar_pay once per payee: Pix to a key, or to bank details when the payee has none. The idempotency key ties a retry to the first attempt. Payment status is read by id. Checking payees before the run and writing the run back to the ERP are done by your systems, not by CodeSpar.
The code, and what it assumes.
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…) and a Pix // provider connected to the project. The approved list comes from your systems. import { CodeSpar } from "@codespar/sdk"; const session = await new CodeSpar().create("ops_payroll", { preset: "brazilian" }); const approved = [ { id: "c-001", name: "Ana Souza", pixKey: "ana@example.com", amountMinor: 420_000 }, { id: "c-002", name: "Bruno Lima", pixKey: "+5511999990000", amountMinor: 380_000 }, ]; for (const c of approved) { const res = await session.execute("codespar_pay", { action: "pay", method: "pix", recipient: c.pixKey, amount: c.amountMinor, // centavos currency: "BRL", description: `June payroll · ${c.name}`, idempotency_key: `payroll-2026-06-${c.id}`, // a retry returns the first result }); console.log(c.id, res.success); }
Example with the published SDK (@codespar/sdk 0.16.11). Its prerequisites are in the comments. Compiling does not prove the integration: run it in test mode first.
codespar_payPays one Pix per payee, to a key or bank details; idempotency_key prevents a second payment on retry; action=status reads it.
Start with a test key.
Test keys are free. Open the sandbox, connect the providers your project uses and see which tools it can call before you build.