skills.rest
vtexdocs
vtexdocsOFFICIAL
Explore all skills by this author →
WebsiteGitHub

payment-async-flow

Implement asynchronous payment flows with callback-based settling for Boleto and Pix.

39|9|Updated Mar 16, 2026
Search Tags:#async#webhook#payments#retry#callback#vtex
One-click install
npx skills add https://github.com/vtexdocs/ai-skills --skill payment-async-flow
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: payment-async-flow
Source: https://github.com/vtexdocs/ai-skills/tree/main/tracks/payment/skills/payment-async-flow
Command: npx skills add https://github.com/vtexdocs/ai-skills --skill payment-async-flow

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Implement asynchronous payment flows with undefined status handling, ensuring proper callback and retry mechanisms for non-synchronous payments like Boleto and Pix.

Core Features & Use Cases

  • Handles Create Payment responses with status "undefined" for async methods (BankInvoice/Boleto, Pix) and stores the callbackUrl for later notification.
  • Notifies the Gateway via the exact callbackUrl with proper VTEX headers after the acquirer confirms payment, respecting VTEX IO and non-VTEX IO flows.
  • Enforces idempotent Create Payment retries within the 7-day window and updates status in response to callbacks.

Quick Start

Set up an async payment flow for a Boleto or Pix method and verify the callback notification cycle.

Frequently Asked Questions about payment-async-flow

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

FAQPage Schema
How do I handle asynchronous payment flows with undefined status in VTEX?▼

Asynchronous payment flows with undefined status are handled by storing the request's callbackUrl and notifying the Gateway via that exact URL once the acquirer confirms payment. This process properly manages non-synchronous methods like Boleto and Pix.

How do I configure delayToCancel for asynchronous payment retries in VTEX?▼

To configure delayToCancel for asynchronous payment retries, set the value to exactly 604800 seconds. This enforces idempotent Create Payment retries and aligns the flow with the required 7-day retry window.

Does the VTEX IO async payment callback behavior differ from non-VTEX IO flows?▼

Yes, VTEX IO and non-VTEX IO flows dictate different callback behaviors. The Gateway must be notified using the exact callbackUrl provided in the request along with proper VTEX headers after the acquirer confirms the payment.

What is the best way to support Boleto and Pix bank invoice callbacks in VTEX?▼

The best way to support Boleto and Pix callbacks is to return an undefined status during Create Payment, preserve the callbackUrl, and later send the settled status back to the Gateway using the specified VTEX headers.

Why do my idempotent Create Payment retries fail outside the 7-day window?▼

Idempotent Create Payment retries fail outside the 7-day window because the configuration requires delayToCancel to be set to 604800 seconds. Retries must be supported strictly within this timeframe to update status correctly.

Related Skills

Explore More Software Engineering Skills→
exilonXexilonX

payment-async-flow

Implement asynchronous payment callbacks and redirect handling for payment connectors.

Community
Advanced
trohitgtrohitg
356

http-request-skill

Execute HTTP requests with configurable methods, headers, and JSON bodies.

Community
Intermediate
vtexvtex
39

payment-async-flow

Coordinate async payment flows with undefined status, callback URLs, and idempotent Create Payment handling.

Official
Advanced
PriyanshKuniyalPriyanshKuniyal

pci-compliance

Provides PCI DSS guidelines and best practices for secure payment card data handling and system security.

Community
Advanced