payment-async-flow — Claude Code skill for VTEX async payments
Rules for VTEX payment connector code: Boleto, Pix, bank redirects, callbackUrl handling and signature validation.
npx skills add vtex/skills --skill payment-async-flow -a claude-codeWhat payment-async-flow does
The skill kicks in when a connector takes a payment that does not settle right away: Boleto Bancário, Pix, bank transfers, redirect-based auth. Create Payment has to answer status: "undefined", and the final status arrives later through callbackUrl. Return "approved" too early and the order ships unpaid; return "denied" and you cancel a payment the customer might still finish.
Two callbackUrl modes are covered. Without VTEX IO the URL is a notification endpoint — you POST the updated status with X-VTEX-API-AppKey and X-VTEX-API-AppToken headers. With VTEX IO it is a retry endpoint: a POST with no payload makes the Gateway call authorize() again. Keep the X-VTEX-signature query parameter in the callbackUrl untouched. The skill also spells out delayToCancel: 900 to 3600 seconds for Pix, matching QR code expiry, and the invoice due date for Boleto.
One constraint catches people out: inboundRequestsUrl is server-to-server POST only and does not support browser GET redirects. PayPal or 3DS flows need a custom public route. PPP contracts, paymentId/requestId idempotency, PCI handling and POS terminal payments live in separate skills in the same set.
What it helps with
- return
undefinedfor a payment that confirms later - receive status updates through
callbackUrl - validate
X-VTEX-signatureon requests from the Gateway - set
delayToCancelto the Pix QR or Boleto due date - add a public route for the browser return after 3DS
Example prompts for the agent
- Implement Pix in the connector: Create Payment returns undefined and the status arrives via callbackUrl
- Check that we keep X-VTEX-signature in callbackUrl and compute delayToCancel correctly for Boleto
- We need a browser redirect after 3DS — inboundRequestsUrl won't work, suggest a public route
How to install payment-async-flow
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-async-flow -a claude-code2Manually: put the files in place
~/.claude/skills/payment-async-flow/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/payment-async-flow/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-async-flow -a codex2Manually: put the files in place
.agents/skills/payment-async-flow/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-async-flow -a cursor2Manually: put the files in place
.cursor/skills/payment-async-flow/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills payment-async-flow2Manually: put the files in place
.github/skills/payment-async-flow/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-async-flow -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/payment-async-flowManually: put the files in place
.devin/skills/payment-async-flow/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-async-flow -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about payment-async-flow
How do I install payment-async-flow in Claude?
Run npx skills add vtex/skills --skill payment-async-flow -a claude-code. The skill lands in ~/.claude/skills/payment-async-flow/SKILL.md.
What does payment-async-flow do?
It sets the rules for async payments in a VTEX connector: returning undefined, handling callbackUrl, validating the signature and computing delayToCancel.
Why can't I return approved right away?
The Gateway reads that as collected money and releases the order for fulfillment. If the customer never pays, the merchant ships for free.
