# payment-ppp-pos

payment-ppp-pos guides creation and debugging of VTEX Payment Provider Protocol connectors for physical POS terminals in VTEX Sales App.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 252 installs · ★ 47 repo stars
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/payment-ppp-pos/SKILL.md
- Updated: 2026-10-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/payment-ppp-pos

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-ppp-pos -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/payment-ppp-pos/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/payment-ppp-pos/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-ppp-pos -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/payment-ppp-pos/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-ppp-pos -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/payment-ppp-pos/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills skills/payment-ppp-pos
```

2. **Manually: put the files in place**
- File: `.github/skills/payment-ppp-pos/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-ppp-pos -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/payment-ppp-pos
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/payment-ppp-pos/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-ppp-pos -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/payment-ppp-pos/SKILL.md

## When to use it
- 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
- 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

## Similar
- [Kash — POS, Invoicing, CRM & Webshop](https://affpapa.org/en/nevibecode/mcp/kash-pos-invoicing-crm-webshop.md) — MCP server · 2880 installs
- [shopify-pos-ui](https://affpapa.org/en/nevibecode/skills/shopify-pos-ui.md) — skill · 2 installs
- [sumup](https://affpapa.org/en/nevibecode/plugins/sumup.md) — plugin · ★ 7 repo stars
- [payment-testing](https://affpapa.org/en/nevibecode/skills/payment-testing.md) — skill · 1300 installs
- [payment-gateway-integration](https://affpapa.org/en/nevibecode/skills/payment-gateway-integration.md) — skill · 531 installs
- [payment-integration](https://affpapa.org/en/nevibecode/skills/payment-integration.md) — skill · 361 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 46 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
