skills.rest
exilonX
exilonXCOMMUNITY
Explore all skills by this author →
GitHub

payment-async-flow

Implement asynchronous payment callbacks and redirect handling for payment connectors.

Updated Mar 27, 2026
Search Tags:#Boleto#Pix#redirect flow#VTEX IO#payment callbacks#asynchronous authorization#callbackUrl
One-click install
npx skills add https://github.com/exilonX/ap2 --skill payment-async-flow-exilonx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: payment-async-flow
Source: https://github.com/exilonX/ap2/tree/main/.agents/skills/payment-async-flow
Command: npx skills add https://github.com/exilonX/ap2 --skill payment-async-flow-exilonx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Asynchronous payment methods can return no final approval immediately, causing orders to stall or cancel incorrectly unless your connector correctly handles callback/notification lifecycles and status evolution.

Core Features & Use Cases

  • Correct async handling (status: undefined): Ensures Boleto/Pix/redirect-based flows never prematurely return approved/denied before the acquirer confirms.
  • CallbackUrl integrity & validation: Uses the exact callbackUrl from the Create Payment request (including X-VTEX-signature) and includes required headers for non-VTEX IO notifications.
  • Sync vs async retry behavior: Supports both non-VTEX IO callback notification and VTEX IO retry endpoint patterns, including idempotent Create Payment with evolving status.
  • Redirect-based flow correctness: Avoids using inboundRequestsUrl for browser GET redirects by implementing a custom public route that updates state and triggers Gateway retry.

Quick Start

Use the payment-async-flow skill to implement a Pix/Boleto connector that returns status undefined, stores and reuses the exact callbackUrl for notifications, updates local status on provider webhooks, and triggers Gateway retry or approval accordingly.

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 callbacks for Boleto and Pix in VTEX IO?▼

To handle asynchronous payment callbacks for Boleto and Pix in VTEX IO, your connector must return status "undefined" initially and later update the Gateway order status using the exact callbackUrl provided during the Create Payment request.

Why does my Pix redirect flow return approved before the acquirer confirms the transaction?▼

Your Pix redirect flow returns approved prematurely because the connector is not enforcing status "undefined" for asynchronous methods, which is required to stall order progression until the acquirer sends a final notification.

How to correctly reuse the callbackUrl with X-VTEX-signature for non-VTEX IO payment notifications?▼

To reuse the callbackUrl with X-VTEX-signature for non-VTEX IO payment notifications, store the exact URL and headers from the Create Payment request and include the X-VTEX-signature header when sending the final acquirer outcome to the Gateway.

Can I use inboundRequestsUrl for browser GET redirects in a VTEX IO redirect-based payment flow?▼

No, you cannot use inboundRequestsUrl for browser GET redirects in a VTEX IO redirect-based payment flow; you must create a custom public route to update local state and trigger the Gateway retry mechanism instead.

Do I need to configure delayToCancel based on payment validity for asynchronous payment methods?▼

Yes, you need to configure delayToCancel based on payment validity for asynchronous payment methods to ensure the VTEX Gateway does not incorrectly cancel pending Boleto or bank transfer orders before the acquirer's final authorization arrives.

Related Skills

Explore More Software Engineering Skills→
vtexdocsvtexdocs
39

payment-async-flow

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

Official
Advanced
atournayreatournayre

devops:conflict

Analyzes and interactively resolves Git merge or rebase conflicts step by step.

Community
Advanced
exilonXexilonX

payment-provider-framework

Implement VTEX IO payment connectors with PaymentProviderService and configuration validation.

Community
Advanced
vtexdocsvtexdocs
39

payment-provider-protocol

Implement VTEX Payment Provider Protocol PPP connectors with endpoint contracts and manifest requirements.

Official
Advanced