Payment Idempotency

Apply when implementing idempotency logic in payment connector code or handling duplicate payment requests. Covers paymentId as idempotency key, payment state machine transitions, retry semantics for cancellation and refund operations, and requestId handling. Use for preventing duplicate charges and ensuring correct Gateway retry behavior across Create Payment, Cancel, Capture, and Refund endpoints.

47 stars 9 forksFinance & Crypto Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add vtex/skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add vtex/skills --skill payment-idempotency
Manual install
git clone --depth 1 https://github.com/vtex/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/exports/opencode/payment-idempotency ~/.claude/skills/payment-idempotency

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Idempotency & Duplicate Prevention

## When this skill applies

Use this skill when:
- Implementing any PPP endpoint handler that processes payments, cancellations, captures, or refunds
- Ensuring repeated Gateway calls with the same identifiers produce identical results without re-processing
- Building a payment state machine to prevent invalid transitions (e.g., capturing a cancelled payment)
- Handling the Gateway's 7-day retry window for `undefined` status payments

Do not use this skill for:
- PPP endpoint response shapes and HTTP methods — use [`payment-provider-protocol`](../payment-provider-protocol/SKILL.md)
- Async callback URL notification logic — use [`payment-async-flow`](../payment-async-flow/SKILL.md)
- PCI compliance and Secure Proxy — use [`payment-pci-security`](../payment-pci-security/SKILL.md)
- POS / Sales App terminal payments (`Venda Direta Credito`, `Venda Direta Debito`, overlapping Create Payment while Wait for confirmation polls) — use [`payment-ppp-pos`](../payment-ppp-pos/SKILL.md) together with this skill

## Decision rules

- Use `paymentId` as the idempotency key for Create Payment — every call with the same `paymentId` must return the same result.
- Use `requestId` as the idempotency key for Cancel, Capture, and Refund operations.
Read the full skill on GitHub

Details

Skill name
payment-idempotency
Repository
vtex/skills
Path
exports/opencode/payment-idempotency/SKILL.md
Repo updated
14 October 2026

FAQ

What does the Payment Idempotency skill do?

Apply when implementing idempotency logic in payment connector code or handling duplicate payment requests. Covers paymentId as idempotency key, payment state machine transitions, retry semantics for cancellation and refund operations, and requestId handling. Use for preventing duplicate charges and ensuring correct Gateway retry behavior across Create Payment, Cancel, Capture, and Refund endpoints.

How do I install the Payment Idempotency skill?

Claude Code plugin: /plugin marketplace add vtex/skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Payment Idempotency popular?

It lives in vtex/skills, which has 47 GitHub stars and 9 forks.

Related skills

Architecture Well Architected Commerce

47

vtex/skills

Apply when scoping, reviewing, or documenting cross-cutting VTEX commerce architecture across storefront, IO, headless, marketplace, payments, or any other VTEX module. Grounds work in the Well-Architected Commerce framework—Technical Foundation (reliability, trust, integrity; security, infrastructure, compliance), Future-proof (innovation, simplicity, efficiency; scalable and adaptable solutions), and Operational Excellence (accuracy, accountability, data-driven improvement; process and customer experience). Routes implementation detail to product tracks (IO caching and paths, Master Data str

Software Development

Faststore Storefront

47

vtex/skills

Core coding rules and workflow for developing VTEX FastStore storefronts. Use when starting any FastStore development task, writing TypeScript/React components, creating section overrides, extending the BFF, or styling. Covers all primary conventions, safety rules, and the development workflow used across every FastStore project.

Productivity & Notes

Headless Bff Architecture

47

vtex/skills

Apply when designing or modifying a BFF (Backend-for-Frontend) layer, middleware, or API proxy for a headless VTEX storefront. Covers BFF middleware architecture, public vs private API classification, VtexIdclientAutCookie management, API key protection, and secure request proxying. Use for any headless commerce project that must never expose VTEX_APP_KEY or call private VTEX APIs from the browser.

Software Development

Payment Pci Security

47

vtex/skills

Apply when handling credit card data, implementing secureProxyUrl flows, or working with payment security and proxy code. Covers PCI DSS compliance, Secure Proxy card tokenization, sensitive data handling rules, X-PROVIDER-Forward-To header usage, custom token creation, and the constraint that Secure Proxy applies only to card authorization (not post-auth operations like cancel, capture, or refund). Use for any payment connector that processes credit, debit, or co-branded card payments to prevent data breaches and PCI violations.

Finance & Crypto

Payment Async Flow

47

vtex/skills

Apply when implementing asynchronous payment methods (Boleto, Pix, bank redirects) or working with callback URLs in payment connector code. Covers undefined status response, callbackUrl notification, X-VTEX-signature validation, sync vs async handling, correct delayToCancel configuration for each async method, and redirect-based flows where inboundRequestsUrl does not support browser GET redirects (requires custom public routes).

Finance & Crypto

Payment Ppp Pos

47

vtex/skills

Apply when implementing a VTEX Payment Provider Protocol connector for Point of Sale (POS) payments on VTEX Sales App. Covers Venda Direta Credito and Venda Direta Debito manifest methods, the two-phase Payment App challenge (terminal connector then wait-for-confirmation), null card data on Create Payment, asynchronous undefined status, timeout pairing of secondsWaiting and delayToCancel, and callback payloads with cardBrand, firstDigits, and lastDigits. Use for building or debugging PPP + POS integrations that charge a physical card on a payment terminal.

Finance & Crypto

Browse the most popular Claude skills, all finance & crypto skills, or write your own with the skills generator.