payment-ppp-pos — Claude Code skill: what it does, how to install
payment-ppp-pos guides creation and debugging of VTEX Payment Provider Protocol connectors for physical POS terminals in VTEX Sales App.
no license 252 installs ★ 47 updated 2026-10-14
npx skills add vtex/skills --skill payment-ppp-pos -a claude-codeWhat payment-ppp-pos does
This skill guides the implementation of POS integrations under the VTEX Payment Provider Protocol. It covers manifest methods like Venda Direta Credito and Venda Direta Debito, asynchronous authorization flows, and the two-phase Payment App challenge.
State transitions drive the authorize() logic. The gateway never receives customer card information for in-store transactions, so card structures stay null and Secure Proxy remains untouched. The flow yields an undefined status while awaiting confirmation from vtex.terminal-connector-app and vtex.challenge-wait-for-confirmation.
Runtime targets change callback behavior: standalone endpoints expect final details posted to callbackUrl, while VTEX IO deployments trigger retries using empty payloads.
What it helps with
- build a POS connector for VTEX Sales App via Payment Provider Protocol
- support Venda Direta Credito and Venda Direta Debito methods
- wire the two-phase challenge using official terminal apps
- format completion payloads containing cardBrand, firstDigits, and lastDigits
Example prompts for the agent
- Generate the authorize state machine for a VTEX Sales App POS connector
- Configure vtex.terminal-connector-app and vtex.challenge-wait-for-confirmation in our PPF app
- Review our callbackUrl notification handling for standalone PPP POS
How to install payment-ppp-pos
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-ppp-pos -a claude-code2Manually: put the files in place
~/.claude/skills/payment-ppp-pos/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/payment-ppp-pos/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-ppp-pos -a codex2Manually: put the files in place
.agents/skills/payment-ppp-pos/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-ppp-pos -a cursor2Manually: put the files in place
.cursor/skills/payment-ppp-pos/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills skills/payment-ppp-pos2Manually: put the files in place
.github/skills/payment-ppp-pos/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-ppp-pos -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/payment-ppp-posManually: put the files in place
.devin/skills/payment-ppp-pos/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill payment-ppp-pos -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-ppp-pos
How to install payment-ppp-pos in Claude Code?
Run npx skills add vtex/skills --skill payment-ppp-pos -a claude-code. The file will be placed at ~/.claude/skills/payment-ppp-pos/SKILL.md.
What does payment-ppp-pos do?
It provides architectural rules and code patterns for building VTEX PPP connectors tailored to card-present POS operations.
Why are card details null during Create Payment?
POS transactions handle the physical card outside the gateway, leaving card inputs null and avoiding Secure Proxy calls entirely.