payment-idempotency

Enforce idempotency for payment operations using paymentId and requestId guards.

39|9|Updated Mar 16, 2026
One-click install
npx skills add https://github.com/vtex/ai-skills --skill payment-idempotency-vtex
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: payment-idempotency
Source: https://github.com/vtex/ai-skills/tree/main/tracks/payment/skills/payment-idempotency
Command: npx skills add https://github.com/vtex/ai-skills --skill payment-idempotency-vtex

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Prevents duplicate charges by enforcing idempotency across payment operations and handling gateway retries for undefined payments.

Core Features & Use Cases

  • Idempotent Create Payment: Checks for existing paymentId and returns the exact stored response.
  • Stateful Guardrails: Maintains a persistent store of payment state to ensure safe retries and valid transitions.
  • Cancel/Capture/Refund Guardrails: Applies requestId guards to avoid duplicate operations.

Quick Start

Integrate idempotency guards into your Create Payment handler to ensure the same response is returned for repeated paymentId requests.

Frequently Asked Questions about payment-idempotency

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent duplicate charges during payment gateway retries?

To prevent duplicate charges during payment gateway retries, enforce idempotency by using a unique paymentId as the idempotency key for Create Payment requests, returning the exact stored response if duplicates are detected.

What is idempotency in payment processing?

Idempotency in payment processing is a mechanism ensuring consistent results when identical payment requests are retried, preventing duplicate charges by checking for existing payment identifiers and returning stored responses.

How do I implement safe retry strategies for async and sync payment methods?

Implement safe retry strategies for async and sync payment methods by persisting payment state in a durable data store, ensuring valid state transitions and consistent responses across retry attempts.

How do I guard against duplicate Cancel, Capture, and Refund operations?

Guard against duplicate Cancel, Capture, and Refund operations by applying requestId-based guards that check existing payment state before processing, ensuring duplicate operations return consistent results without re-executing.

Do I need a durable data store to enforce idempotent payments?

Yes, a durable data store is required to enforce idempotent payments, as it maintains persistent payment state necessary to identify duplicate requests and return identical stored responses during gateway retries.

What's the best way to handle gateway retries for undefined payments?

The best way to handle gateway retries for undefined payments is to enforce idempotency guards that check for existing paymentId values, persist state durably, and return consistent results for repeated requests.