# payment-provider-protocol

Assists with building and debugging VTEX Payment Provider Protocol connectors. Enforces endpoint routing, payload schemas, and response rules for homologation.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1000 installs · ★ 46
- 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-provider-protocol/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/payment-provider-protocol

## What it does

This skill guides the agent when assembling payment middleware for the VTEX Gateway. It enforces all six mandatory endpoints: the manifest, payment creation, cancellation, settlement, refunds, and inbound actions. Three onboarding endpoints for authentication remain optional.

All traffic must go through port 443 over HTTPS with TLS 1.2. VTEX expects responses under 5 seconds during test homologation, while production allows up to 20 seconds. Omitting fields like `delayToAutoSettle` or `authorizationId` causes deserialization failures in the gateway.

The gateway initiates all requests directly. For credit card processing, the service requires PCI-DSS compliance or the VTEX Secure Proxy. Concerns like idempotency and async webhooks are handled by separate skills.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills payment-provider-protocol
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill payment-provider-protocol -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-provider-protocol/SKILL.md

## When to use it
- implement mandatory VTEX PPP payment endpoints
- pass VTEX Payment Provider homologation test suite
- format `CreatePayment` responses with required delay fields
- declare supported payment methods inside the manifest router

## Example prompts
- Generate an Express router implementing all six required VTEX PPP endpoints
- Check our `/payments` response handler against VTEX payload requirements
- Draft a GET `/manifest` endpoint declaring split payment support

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 38 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