payment-async-flow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Asynchronous Payment Flows & Callbacks

异步支付流程与回调

When this skill applies

适用场景

Use this skill when:

Implementing a payment connector that supports Boleto Bancário, Pix, bank transfers, or redirect-based flows
Working with any payment method where the acquirer does not return a final status synchronously
Handling
```
callbackUrl
```
notification or retry flows
Managing the Gateway's 7-day automatic retry cycle for
```
undefined
```
status payments

Do not use this skill for:

PPP endpoint contracts and response shapes — use
```
payment-provider-protocol
```
```
paymentId
```
/
```
requestId
```
idempotency and state machine logic — use
```
payment-idempotency
```
PCI compliance and Secure Proxy card handling — use
```
payment-pci-security
```

在以下场景使用本指南：

实现支持Boleto Bancário、Pix、银行转账或跳转式流程的支付连接器
对接收单机构无法同步返回最终状态的任意支付方式
处理
```
callbackUrl
```
通知或重试流程
管理网关针对
```
undefined
```
状态支付的7天自动重试周期

本指南不适用于以下场景：

PPP端点约定与响应格式 — 请参考
```
payment-provider-protocol
```
```
paymentId
```
/
```
requestId
```
幂等性与状态机逻辑 — 请参考
```
payment-idempotency
```
PCI合规与安全代理卡处理 — 请参考
```
payment-pci-security
```

Decision rules

决策规则

If the acquirer cannot return a final status synchronously, the payment method is async — return
```
status: "undefined"
```
.
Common async methods: Boleto Bancário (
```
BankInvoice
```
), Pix, bank transfers, redirect-based auth.
Common sync methods: credit cards, debit cards with instant authorization.
Without VTEX IO: the
```
callbackUrl
```
is a notification endpoint — POST the updated status with
```
X-VTEX-API-AppKey
```
/
```
X-VTEX-API-AppToken
```
headers.
With VTEX IO: the
```
callbackUrl
```
is a retry endpoint — POST to it (no payload) to trigger the Gateway to re-call POST
```
/payments
```
.
Always preserve the
```
X-VTEX-signature
```
query parameter in the
```
callbackUrl
```
— never strip or modify it.
For asynchronous methods,
```
delayToCancel
```
MUST reflect the actual validity of the payment method, not the 7‑day internal Gateway retry window:
- Pix: between 900 and 3600 seconds (15–60 minutes), aligned with QR code expiration.
- BankInvoice (Boleto): aligned with the invoice due date / payment deadline configured in the provider.
- Other async methods: aligned with the provider's documented expiry SLA.

如果收单机构无法同步返回最终状态，则该支付方式为异步方式 — 返回
```
status: "undefined"
```
。
常见异步支付方式：Boleto Bancário（
```
BankInvoice
```
）、Pix、银行转账、跳转式鉴权。
常见同步支付方式：信用卡、可即时授权的借记卡。
非VTEX IO环境：
```
callbackUrl
```
是通知端点 — 携带
```
X-VTEX-API-AppKey
```
/
```
X-VTEX-API-AppToken
```
请求头POST更新后的状态。
VTEX IO环境：
```
callbackUrl
```
是重试端点 — 向其发送无请求体的POST请求，触发网关重新调用POST
```
/payments
```
接口。
始终保留
```
callbackUrl
```
中的
```
X-VTEX-signature
```
查询参数 — 不得删除或修改。
对于异步支付方式，
```
delayToCancel
```
必须匹配支付方式的实际有效期，而非网关内部7天的重试窗口：
- Pix：900到3600秒（15–60分钟），与二维码有效期保持一致。
- BankInvoice（Boleto）：与供应商配置的账单到期日/支付截止日期保持一致。
- 其他异步支付方式：与供应商文档公布的过期SLA保持一致。

Hard constraints

硬性约束

Constraint: MUST return

undefined

for async payment methods

约束：异步支付方式必须返回

undefined

For any payment method where authorization does not complete synchronously (Boleto, Pix, bank transfer, redirect-based auth), the Create Payment response MUST use

status: "undefined"

. The connector MUST NOT return

"approved"

"denied"

until the payment is actually confirmed or rejected by the acquirer.

Why this matters Returning

"approved"

for an unconfirmed payment tells the Gateway the money has been collected. The order is released for fulfillment immediately. If the customer never actually pays (e.g., never scans the Pix QR code), the merchant ships products without payment. Returning

"denied"

prematurely cancels a payment that might still be completed.

Detection If the Create Payment handler returns

status: "approved"

status: "denied"

for an asynchronous payment method (Boleto, Pix, bank transfer, redirect), STOP. Async methods must return

"undefined"

and resolve via callback.

Correct

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  const asyncMethods = ["BankInvoice", "Pix"];
  const isAsync = asyncMethods.includes(paymentMethod);

  if (isAsync) {
    const pending = await acquirer.initiateAsyncPayment(req.body);

    // Store payment and callbackUrl for later notification
    await store.save(paymentId, {
      paymentId,
      status: "undefined",
      callbackUrl,
      acquirerReference: pending.reference,
    });

    res.status(200).json({
      paymentId,
      status: "undefined",  // Correct: payment is pending
      authorizationId: pending.authorizationId ?? null,
      nsu: pending.nsu ?? null,
      tid: pending.tid ?? null,
      acquirer: "MyProvider",
      code: "PENDING",
      message: "Awaiting customer action",
      delayToAutoSettle: 21600,
      delayToAutoSettleAfterAntifraud: 1800,
      delayToCancel: computeDelayToCancel(paymentMethod, pending),
      paymentUrl: pending.qrCodeUrl ?? pending.boletoUrl ?? undefined,
    });

    return;
  }

  // Synchronous methods (credit card) can return final status
  const result = await acquirer.authorizeSyncPayment(req.body);

  res.status(200).json({
    paymentId,
    status: result.status,  // "approved" or "denied" is OK for sync
    authorizationId: result.authorizationId ?? null,
    nsu: result.nsu ?? null,
    tid: result.tid ?? null,
    acquirer: "MyProvider",
    code: result.code ?? null,
    message: result.message ?? null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

const PIX_MIN_DELAY = 900;   // 15 minutes
const PIX_MAX_DELAY = 3600;  // 60 minutes

function computeDelayToCancel(paymentMethod: string, pending: any): number {
  if (paymentMethod === "Pix") {
    // Use provider QR TTL but clamp to 15–60 minutes
    const providerTtlSeconds = pending.pixTtlSeconds ?? 1800; // default 30 min
    return Math.min(Math.max(providerTtlSeconds, PIX_MIN_DELAY), PIX_MAX_DELAY);
  }

  if (paymentMethod === "BankInvoice") {
    // Example: seconds until boleto due date
    const now = Date.now();
    const dueDate = new Date(pending.dueDate).getTime();
    const diffSeconds = Math.max(Math.floor((dueDate - now) / 1000), 0);
    return diffSeconds;
  }

  // Other async methods: follow provider SLA if provided
  if (pending.expirySeconds) {
    return pending.expirySeconds;
  }

  // Conservative fallback: 24h
  return 86400;
}

Wrong

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod } = req.body;

  // WRONG: Creating a Pix charge and immediately returning "approved"
  // The customer hasn't scanned the QR code yet — no money collected
  const pixCharge = await acquirer.createPixCharge(req.body);

  res.status(200).json({
    paymentId,
    status: "approved",  // WRONG — Pix hasn't been paid yet!
    authorizationId: pixCharge.id,
    nsu: null,
    tid: null,
    acquirer: "MyProvider",
    code: null,
    message: null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

对于任何授权无法同步完成的支付方式（Boleto、Pix、银行转账、跳转式鉴权），创建支付的响应必须使用

status: "undefined"

。在收单机构实际确认或驳回支付之前，连接器不得返回

"approved"

或

"denied"

。

设计原因 为未确认的支付返回

"approved"

会告知网关资金已到账，订单会立即进入发货流程。如果客户最终未完成支付（比如从未扫描Pix二维码），商家就会出现货发了但没收到钱的损失。过早返回

"denied"

则会取消原本可能完成的支付。

检测规则 如果创建支付的处理逻辑为异步支付方式（Boleto、Pix、银行转账、跳转）返回

status: "approved"

或

status: "denied"

，请立即停止开发。异步方式必须返回

"undefined"

，最终状态通过回调更新。

正确示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  const asyncMethods = ["BankInvoice", "Pix"];
  const isAsync = asyncMethods.includes(paymentMethod);

  if (isAsync) {
    const pending = await acquirer.initiateAsyncPayment(req.body);

    // 存储支付信息与callbackUrl，用于后续通知
    await store.save(paymentId, {
      paymentId,
      status: "undefined",
      callbackUrl,
      acquirerReference: pending.reference,
    });

    res.status(200).json({
      paymentId,
      status: "undefined",  // 正确：支付处于待处理状态
      authorizationId: pending.authorizationId ?? null,
      nsu: pending.nsu ?? null,
      tid: pending.tid ?? null,
      acquirer: "MyProvider",
      code: "PENDING",
      message: "等待用户操作",
      delayToAutoSettle: 21600,
      delayToAutoSettleAfterAntifraud: 1800,
      delayToCancel: computeDelayToCancel(paymentMethod, pending),
      paymentUrl: pending.qrCodeUrl ?? pending.boletoUrl ?? undefined,
    });

    return;
  }

  // 同步支付方式（信用卡）可以返回最终状态
  const result = await acquirer.authorizeSyncPayment(req.body);

  res.status(200).json({
    paymentId,
    status: result.status,  // 同步方式返回"approved"或"denied"是合法的
    authorizationId: result.authorizationId ?? null,
    nsu: result.nsu ?? null,
    tid: result.tid ?? null,
    acquirer: "MyProvider",
    code: result.code ?? null,
    message: result.message ?? null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

const PIX_MIN_DELAY = 900;   // 15分钟
const PIX_MAX_DELAY = 3600;  // 60分钟

function computeDelayToCancel(paymentMethod: string, pending: any): number {
  if (paymentMethod === "Pix") {
    // 使用供应商提供的二维码有效期，限制在15-60分钟区间内
    const providerTtlSeconds = pending.pixTtlSeconds ?? 1800; // 默认30分钟
    return Math.min(Math.max(providerTtlSeconds, PIX_MIN_DELAY), PIX_MAX_DELAY);
  }

  if (paymentMethod === "BankInvoice") {
    // 示例：计算距离Boleto到期日的秒数
    const now = Date.now();
    const dueDate = new Date(pending.dueDate).getTime();
    const diffSeconds = Math.max(Math.floor((dueDate - now) / 1000), 0);
    return diffSeconds;
  }

  // 其他异步支付方式：如果供应商提供了SLA则遵循
  if (pending.expirySeconds) {
    return pending.expirySeconds;
  }

  // 保守兜底：24小时
  return 86400;
}

错误示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod } = req.body;

  // 错误：创建Pix订单后立即返回"approved"
  // 客户还未扫描二维码，资金并未到账
  const pixCharge = await acquirer.createPixCharge(req.body);

  res.status(200).json({
    paymentId,
    status: "approved",  // 错误 — Pix还未完成支付！
    authorizationId: pixCharge.id,
    nsu: null,
    tid: null,
    acquirer: "MyProvider",
    code: null,
    message: null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

Constraint: MUST use callbackUrl from request — never hardcode

约束：必须使用请求中携带的callbackUrl，禁止硬编码

The connector MUST use the exact

callbackUrl

provided in the Create Payment request body, including all query parameters (

X-VTEX-signature

, etc.). The connector MUST NOT hardcode callback URLs or construct them manually.

Why this matters The

callbackUrl

contains transaction-specific authentication tokens (

X-VTEX-signature

) that the Gateway uses to validate the callback. A hardcoded or modified URL will be rejected by the Gateway, leaving the payment stuck in

undefined

status forever. The URL format may also change between environments (production vs sandbox).

Detection If the connector hardcodes a callback URL string, constructs the URL manually, or strips query parameters from the

callbackUrl

, warn the developer. The

callbackUrl

must be stored and used exactly as received.

Correct

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, callbackUrl } = req.body;

  // Store the exact callbackUrl from the request
  await store.save(paymentId, {
    paymentId,
    status: "undefined",
    callbackUrl,  // Stored exactly as received, including query params
  });

  // Return async "undefined" response (see previous constraint)
  res.status(200).json({
    paymentId,
    status: "undefined",
    authorizationId: null,
    nsu: null,
    tid: null,
    acquirer: "MyProvider",
    code: "PENDING",
    message: "Awaiting customer action",
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 86400,
  });
}

// When the acquirer webhook arrives, use the stored callbackUrl
async function handleAcquirerWebhook(req: Request, res: Response): Promise<void> {
  const { paymentReference, status } = req.body;

  const payment = await store.findByAcquirerRef(paymentReference);
  if (!payment) {
    res.status(404).send();
    return;
  }

  const pppStatus = status === "paid" ? "approved" : "denied";

  // Update local state first
  await store.updateStatus(payment.paymentId, pppStatus);

  // Use the EXACT stored callbackUrl — do not modify it
  await fetch(payment.callbackUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-VTEX-API-AppKey": process.env.VTEX_APP_KEY!,
      "X-VTEX-API-AppToken": process.env.VTEX_APP_TOKEN!,
    },
    body: JSON.stringify({
      paymentId: payment.paymentId,
      status: pppStatus,
    }),
  });

  res.status(200).send();
}

Wrong

typescript

// WRONG: Hardcoding callback URL — ignores X-VTEX-signature and environment
async function handleAcquirerWebhook(req: Request, res: Response): Promise<void> {
  const { paymentReference, status } = req.body;
  const payment = await store.findByAcquirerRef(paymentReference);

  // WRONG — hardcoded URL, missing X-VTEX-signature authentication
  await fetch("https://mystore.vtexpayments.com.br/api/callback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      paymentId: payment.paymentId,
      status: status === "paid" ? "approved" : "denied",
    }),
  });

  res.status(200).send();
}

连接器必须使用创建支付请求体中提供的完整

callbackUrl

，包括所有查询参数（

X-VTEX-signature

等）。连接器不得硬编码回调地址，也不得手动拼接地址。

设计原因

callbackUrl

包含交易专属的鉴权令牌（

X-VTEX-signature

），网关会用它验证回调请求的合法性。硬编码或修改过的URL会被网关拒绝，导致支付永远卡在

undefined

状态。同时URL格式在不同环境（生产/沙箱）下也可能发生变化。

检测规则 如果连接器硬编码了回调地址、手动拼接URL，或者删除了

callbackUrl

的查询参数，请警告开发人员。

callbackUrl

必须完全按照接收时的内容存储和使用。

正确示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, callbackUrl } = req.body;

  // 存储请求中携带的完整callbackUrl
  await store.save(paymentId, {
    paymentId,
    status: "undefined",
    callbackUrl,  // 完全按接收内容存储，包括所有查询参数
  });

  // 返回异步"undefined"响应（参考上一个约束）
  res.status(200).json({
    paymentId,
    status: "undefined",
    authorizationId: null,
    nsu: null,
    tid: null,
    acquirer: "MyProvider",
    code: "PENDING",
    message: "等待用户操作",
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 86400,
  });
}

// 收到收单机构webhook时，使用存储的callbackUrl
async function handleAcquirerWebhook(req: Request, res: Response): Promise<void> {
  const { paymentReference, status } = req.body;

  const payment = await store.findByAcquirerRef(paymentReference);
  if (!payment) {
    res.status(404).send();
    return;
  }

  const pppStatus = status === "paid" ? "approved" : "denied";

  // 先更新本地状态
  await store.updateStatus(payment.paymentId, pppStatus);

  // 使用存储的完整callbackUrl — 不要修改
  await fetch(payment.callbackUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-VTEX-API-AppKey": process.env.VTEX_APP_KEY!,
      "X-VTEX-API-AppToken": process.env.VTEX_APP_TOKEN!,
    },
    body: JSON.stringify({
      paymentId: payment.paymentId,
      status: pppStatus,
    }),
  });

  res.status(200).send();
}

错误示例

typescript

// 错误：硬编码回调地址 — 忽略了X-VTEX-signature与环境差异
async function handleAcquirerWebhook(req: Request, res: Response): Promise<void> {
  const { paymentReference, status } = req.body;
  const payment = await store.findByAcquirerRef(paymentReference);

  // 错误 — 硬编码地址，缺少X-VTEX-signature鉴权信息
  await fetch("https://mystore.vtexpayments.com.br/api/callback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      paymentId: payment.paymentId,
      status: status === "paid" ? "approved" : "denied",
    }),
  });

  res.status(200).send();
}

Constraint: MUST be ready for repeated Create Payment calls (idempotent, but status can evolve)

约束：必须支持重复调用创建支付接口（幂等，且状态可更新）

The connector MUST handle the Gateway calling Create Payment (POST

/payments

) with the same

paymentId

multiple times during the retry window. Each call MUST not create a new charge at the acquirer, must return a response based on the locally persisted state for that

paymentId

, and must reflect the current status (

"undefined"

"approved"

, or

"denied"

) which may have changed after a callback.

Idempotency is about side effects on the acquirer: the first call creates the charge, retries MUST NOT call the acquirer again. For async methods, the response status may legitimately evolve from

"undefined"

"approved"

"denied"

, but only because your local store was updated by the webhook.

Why this matters The Gateway retries

POST /payments

for

undefined

payments automatically for up to 7 days. If the connector treats each call as a new payment, it will create duplicate charges at the acquirer. If the connector always returns the original

"undefined"

response without checking for an updated status, the Gateway never learns that the payment was approved, and eventually cancels it.

Detection If the Create Payment handler does not check for an existing

paymentId

before calling the acquirer, or always returns the original response without looking at the current status in storage, the agent MUST stop and guide the developer to implement proper idempotency with status evolution based on stored state only.

Correct

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  // Check for existing payment — may have been updated via callback
  const existing = await store.findByPaymentId(paymentId);
  if (existing) {
    // Do NOT call the acquirer again.
    // Return a response derived from the current stored state.
    res.status(200).json({
      ...existing.response,
      status: existing.status,  // Reflect the latest state: "undefined" | "approved" | "denied"
    });
    return;
  }

  // First time — call the acquirer once
  const asyncMethods = ["BankInvoice", "Pix"];
  const isAsync = asyncMethods.includes(paymentMethod);

  const acquirerResult = await acquirer.authorize(req.body);

  const initialStatus = isAsync ? "undefined" : acquirerResult.status;

  const response = {
    paymentId,
    status: initialStatus,
    authorizationId: acquirerResult.authorizationId ?? null,
    nsu: acquirerResult.nsu ?? null,
    tid: acquirerResult.tid ?? null,
    acquirer: "MyProvider",
    code: acquirerResult.code ?? null,
    message: acquirerResult.message ?? null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: isAsync
      ? computeDelayToCancel(paymentMethod, acquirerResult)
      : 21600,
    ...(acquirerResult.paymentUrl
      ? { paymentUrl: acquirerResult.paymentUrl }
      : {}),
  };

  await store.save(paymentId, {
    paymentId,
    status: initialStatus,
    response,
    callbackUrl,
    acquirerReference: acquirerResult.reference,
  });

  res.status(200).json(response);
}

Wrong

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId } = req.body;

  // WRONG: No idempotency — every retry hits the acquirer again
  const result = await acquirer.authorize(req.body);

  res.status(200).json({
    paymentId,
    status: result.status,
    authorizationId: result.authorizationId ?? null,
    nsu: result.nsu ?? null,
    tid: result.tid ?? null,
    acquirer: "MyProvider",
    code: null,
    message: null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

连接器必须支持网关在重试窗口内使用相同

paymentId

多次调用创建支付接口（POST

/payments

）。每次调用都不得在收单机构侧创建新的订单，必须基于本地存储的

paymentId

状态返回响应，且要返回最新的状态（

"undefined"

、

"approved"

或

"denied"

），状态可能已经通过回调更新。

幂等性针对的是收单机构侧的副作用：首次调用创建订单，重试时绝对不能再次调用收单机构接口。对于异步方式，响应状态可以从

"undefined"

合法更新为

"approved"

或

"denied"

，但前提是本地存储的状态已经被webhook更新过。

设计原因 网关会自动重试

undefined

状态支付的

POST /payments

请求，最长可达7天。如果连接器把每次调用都当成新支付，会在收单机构侧生成重复订单。如果连接器不检查最新状态，始终返回最初的

"undefined"

响应，网关永远不会知道支付已经完成，最终会自动取消订单。

检测规则 如果创建支付处理逻辑在调用收单机构前没有检查是否已存在相同

paymentId

，或者始终返回初始响应而不查询存储的最新状态，必须停止开发，引导开发者实现基于存储状态的、支持状态更新的幂等逻辑。

正确示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  // 检查是否已存在该支付记录 — 状态可能已经被回调更新
  const existing = await store.findByPaymentId(paymentId);
  if (existing) {
    // 不要再次调用收单机构接口
    // 基于当前存储的状态返回响应
    res.status(200).json({
      ...existing.response,
      status: existing.status,  // 反映最新状态："undefined" | "approved" | "denied"
    });
    return;
  }

  // 首次调用 — 仅调用一次收单机构接口
  const asyncMethods = ["BankInvoice", "Pix"];
  const isAsync = asyncMethods.includes(paymentMethod);

  const acquirerResult = await acquirer.authorize(req.body);

  const initialStatus = isAsync ? "undefined" : acquirerResult.status;

  const response = {
    paymentId,
    status: initialStatus,
    authorizationId: acquirerResult.authorizationId ?? null,
    nsu: acquirerResult.nsu ?? null,
    tid: acquirerResult.tid ?? null,
    acquirer: "MyProvider",
    code: acquirerResult.code ?? null,
    message: acquirerResult.message ?? null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: isAsync
      ? computeDelayToCancel(paymentMethod, acquirerResult)
      : 21600,
    ...(acquirerResult.paymentUrl
      ? { paymentUrl: acquirerResult.paymentUrl }
      : {}),
  };

  await store.save(paymentId, {
    paymentId,
    status: initialStatus,
    response,
    callbackUrl,
    acquirerReference: acquirerResult.reference,
  });

  res.status(200).json(response);
}

错误示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId } = req.body;

  // 错误：无幂等处理 — 每次重试都会再次调用收单机构接口
  const result = await acquirer.authorize(req.body);

  res.status(200).json({
    paymentId,
    status: result.status,
    authorizationId: result.authorizationId ?? null,
    nsu: result.nsu ?? null,
    tid: result.tid ?? null,
    acquirer: "MyProvider",
    code: null,
    message: null,
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: 21600,
  });
}

Constraint: MUST align

delayToCancel

with payment validity (not always 7 days)

约束：delayToCancel必须与支付有效期对齐（不要固定为7天）

For asynchronous methods, the

delayToCancel

field in the Create Payment response MUST represent how long that payment is considered valid for the shopper. It defines when the Gateway is allowed to automatically cancel payments that never reached a final status.

Rules:

Pix:
```
delayToCancel
```
MUST be between 900 and 3600 seconds (15–60 minutes). This value MUST match the QR code validity configured on the provider.
BankInvoice (Boleto):
```
delayToCancel
```
MUST be computed from the configured due date / payment deadline (for example, seconds until invoice due date). It MUST NOT be hardcoded to 7 days just to "match" the Gateway's internal retry window.
Other async methods:
```
delayToCancel
```
MUST follow the expiry SLA defined by the provider (hours or days, as applicable). It MUST NEVER exceed the actual validity of the underlying payment from the provider's perspective.

The 7‑day window is an internal Gateway safety limit for retries on

undefined

status. It does not mean every async method should use

delayToCancel = 604800

Why this matters For Pix, using a multi‑day

delayToCancel

keeps orders stuck in "Authorizing" with expired QR codes, creating poor UX and operational noise. For Boleto, cancelling before the real due date loses sales; cancelling much later creates reconciliation risk and "zombie" orders. Misaligned

delayToCancel

breaks the consistency between the provider's notion of a valid payment and when VTEX auto‑cancels the payment.

Detection If the connector always uses

delayToCancel = 604800

for any async method, or sets

delayToCancel

greater than the Pix or Boleto validity window, the agent MUST warn that

delayToCancel

is misconfigured.

Correct

(See the

computeDelayToCancel

function in the "MUST return undefined" example above.)

Wrong

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  const isAsync = ["BankInvoice", "Pix"].includes(paymentMethod);

  if (isAsync) {
    const pending = await acquirer.initiateAsyncPayment(req.body);

    await store.save(paymentId, {
      paymentId,
      status: "undefined",
      callbackUrl,
      acquirerReference: pending.reference,
    });

    res.status(200).json({
      paymentId,
      status: "undefined",
      authorizationId: pending.authorizationId ?? null,
      nsu: pending.nsu ?? null,
      tid: pending.tid ?? null,
      acquirer: "MyProvider",
      code: "PENDING",
      message: "Awaiting customer action",
      delayToAutoSettle: 21600,
      delayToAutoSettleAfterAntifraud: 1800,
      // WRONG: hardcoded 7 days for every async method
      delayToCancel: 604800,
      paymentUrl: pending.qrCodeUrl ?? pending.boletoUrl ?? undefined,
    });

    return;
  }

  // ...
}

对于异步支付方式，创建支付响应中的

delayToCancel

字段必须表示该支付对用户有效的时长，它定义了网关何时可以自动取消从未到达最终状态的支付。

规则：

Pix：
```
delayToCancel
```
必须在900到3600秒之间（15–60分钟），必须与供应商配置的二维码有效期一致。
BankInvoice（Boleto）：
```
delayToCancel
```
必须根据配置的到期日/支付截止日期计算（比如距离账单到期日的秒数）。不得为了“匹配”网关内部的重试窗口就硬编码为7天。
其他异步支付方式：
```
delayToCancel
```
必须遵循供应商定义的过期SLA（根据实际情况可为几小时或几天），绝对不能超过供应商侧支付的实际有效期。

7天窗口是网关针对

undefined

状态重试的内部安全上限，不代表所有异步方式都要设置

delayToCancel = 604800

。

设计原因 对于Pix，设置多天的

delayToCancel

会让订单卡在“授权中”状态，而二维码早已过期，会造成极差的用户体验和运营负担。对于Boleto，早于实际到期日取消会损失销量，晚于到期日取消则会带来对账风险和“僵尸”订单。

delayToCancel

配置不当会打破供应商侧有效支付状态与VTEX自动取消时机的一致性。

检测规则 如果连接器为任意异步支付方式统一设置

delayToCancel = 604800

，或者设置的

delayToCancel

超过了Pix或Boleto的有效期，必须警告

delayToCancel

配置错误。

正确示例

（参考上文“必须返回undefined”示例中的

computeDelayToCancel

函数）

错误示例

typescript

async function createPaymentHandler(req: Request, res: Response): Promise<void> {
  const { paymentId, paymentMethod, callbackUrl } = req.body;

  const isAsync = ["BankInvoice", "Pix"].includes(paymentMethod);

  if (isAsync) {
    const pending = await acquirer.initiateAsyncPayment(req.body);

    await store.save(paymentId, {
      paymentId,
      status: "undefined",
      callbackUrl,
      acquirerReference: pending.reference,
    });

    res.status(200).json({
      paymentId,
      status: "undefined",
      authorizationId: pending.authorizationId ?? null,
      nsu: pending.nsu ?? null,
      tid: pending.tid ?? null,
      acquirer: "MyProvider",
      code: "PENDING",
      message: "等待用户操作",
      delayToAutoSettle: 21600,
      delayToAutoSettleAfterAntifraud: 1800,
      // 错误：所有异步方式都硬编码为7天
      delayToCancel: 604800,
      paymentUrl: pending.qrCodeUrl ?? pending.boletoUrl ?? undefined,
    });

    return;
  }

  // ...
}

Preferred pattern

Common failure modes

常见故障模式

Synchronous approval of async payments — Returning
```
status: "approved"
```
for Pix or Boleto because the QR code or slip was generated successfully. Generating a QR code is not the same as receiving payment. The order ships without money collected.
Ignoring the callbackUrl — Not storing the
```
callbackUrl
```
from the Create Payment request and relying entirely on the Gateway's automatic retries. The retry interval increases over time, causing long delays between payment and order approval. Worst case: the 7-day window expires and the payment is cancelled even though the customer paid.
Hardcoding callback URLs — Constructing callback URLs manually instead of using the one from the request, stripping the
```
X-VTEX-signature
```
parameter. The Gateway rejects the callback and the payment stays stuck in
```
undefined
```
.
No retry logic for failed callbacks — Calling the
```
callbackUrl
```
once and silently dropping the notification on failure. The Gateway never learns the payment was approved, and the payment sits in
```
undefined
```
until the next retry or is auto-cancelled.
Returning stale status on retries — Always returning the original
```
undefined
```
response without checking if the status was updated via callback. The Gateway never sees the
```
approved
```
status and eventually cancels the payment.
Misaligned
delayToCancel
— Using 7 days for Pix, leaving expired QR codes with orders stuck in "Authorizing". Using arbitrary values for Boleto that do not match invoice due dates.

异步支付同步返回通过 — 仅因为Pix二维码或Boleto单据生成成功就返回
```
status: "approved"
```
。生成支付凭证不等于收到付款，会导致商家未收款就发货。
忽略callbackUrl — 不存储创建支付请求中的
```
callbackUrl
```
，完全依赖网关的自动重试。重试间隔会随时间拉长，导致支付完成后订单审批延迟很久。最坏情况：7天窗口过期，即使客户已经付款，支付也会被取消。
硬编码回调地址 — 手动拼接回调地址而不使用请求中提供的地址，删除
```
X-VTEX-signature
```
参数。网关会拒绝回调请求，支付永远卡在
```
undefined
```
状态。
回调失败无重试逻辑 — 仅调用一次
```
callbackUrl
```
，失败后无后续处理。网关永远不会知道支付已完成，支付会停留在
```
undefined
```
状态直到下次重试或被自动取消。
重试时返回过期状态 — 不检查回调是否更新了状态，始终返回最初的
```
undefined
```
响应。网关永远收不到
```
approved
```
状态，最终会取消支付。
delayToCancel配置不当 — 为Pix设置7天有效期，导致二维码过期后订单仍卡在“授权中”。为Boleto设置的有效期与实际账单到期日不匹配。

Review checklist

审核 checklist

Do async payment methods (Boleto, Pix) return
```
status: "undefined"
```
in Create Payment?
Is the
```
callbackUrl
```
stored exactly as received from the request (including all query params)?
Does the webhook handler update local state before calling the
```
callbackUrl
```
?
Is
```
X-VTEX-signature
```
preserved in the
```
callbackUrl
```
when calling it?
Are
```
X-VTEX-API-AppKey
```
and
```
X-VTEX-API-AppToken
```
headers included in notification callbacks (non-VTEX IO)?
Is there retry logic with exponential backoff for failed callback calls?
Does the Create Payment handler check for an existing
```
paymentId
```
, avoid calling the acquirer again for retries, and return a response derived from the current stored state (status may evolve from
```
"undefined"
```
to
```
"approved"
```
/
```
"denied"
```
after callback)?
For Pix, is
```
delayToCancel
```
between 900 and 3600 seconds (15–60 minutes), aligned with QR code validity?
For BankInvoice (Boleto), does
```
delayToCancel
```
reflect the real payment deadline / due date configured in the provider?
For other async methods, is
```
delayToCancel
```
aligned with the provider's documented expiry SLA (and never greater than the actual payment validity)?

异步支付方式（Boleto、Pix）在创建支付时返回
```
status: "undefined"
```
吗？
```
callbackUrl
```
是否完全按照请求中接收的内容存储（包括所有查询参数）？
webhook处理逻辑是否在调用
```
callbackUrl
```
之前先更新本地状态？
调用
```
callbackUrl
```
时是否保留了
```
X-VTEX-signature
```
参数？
通知型回调（非VTEX IO）是否携带了
```
X-VTEX-API-AppKey
```
与
```
X-VTEX-API-AppToken
```
请求头？
回调失败是否有指数退避的重试逻辑？
创建支付处理逻辑是否会检查是否已存在相同
```
paymentId
```
、重试时不重复调用收单机构接口、基于存储的最新状态返回响应（状态可在回调后从
```
"undefined"
```
更新为
```
"approved"
```
/
```
"denied"
```
）？
Pix的
```
delayToCancel
```
是否在900到3600秒之间（15–60分钟），与二维码有效期对齐？
BankInvoice（Boleto）的
```
delayToCancel
```
是否与供应商配置的实际支付截止日/到期日对齐？
其他异步支付方式的
```
delayToCancel
```
是否与供应商文档公布的过期SLA对齐（且永远不超过支付的实际有效期）？

Related skills

Reference

参考资料

Payment Provider Protocol (Help Center) — Detailed explanation of the
```
undefined
```
status, callback URL notification and retry flows, and the 7-day retry window
Purchase Flows — Authorization flow documentation including async retry mechanics and callback URL behavior for VTEX IO vs non-VTEX IO
Implementing a Payment Provider — Endpoint-level implementation guide with callbackUrl and returnUrl usage
Pix: Instant Payments in Brazil — Pix-specific async flow implementation including QR code generation and callback handling
Callback URL Signature Authentication — Mandatory X-VTEX-signature requirement for callback URL authentication (effective June 2024)
Payment Provider Protocol API Reference — Full API specification with callbackUrl field documentation

支付提供商协议（帮助中心） — 详细解释
```
undefined
```
状态、回调URL通知与重试流程、7天重试窗口
购买流程 — 授权流程文档，包含异步重试机制、VTEX IO与非VTEX IO环境下的回调URL行为差异
实现支付提供商 — 端点级实现指南，包含callbackUrl与returnUrl的使用方法
Pix：巴西即时支付 — Pix专属异步流程实现指南，包含二维码生成与回调处理
回调URL签名鉴权 — callbackURL鉴权强制要求X-VTEX-signature（2024年6月生效）
支付提供商协议API参考 — 完整API规范，包含callbackUrl字段说明

payment-async-flow

Original

Translation

Asynchronous Payment Flows & Callbacks

异步支付流程与回调

When this skill applies

适用场景

Decision rules

决策规则

Hard constraints

硬性约束

Constraint: MUST return
`undefined`
for async payment methods

约束：异步支付方式必须返回
`undefined`

Constraint: MUST use callbackUrl from request — never hardcode

约束：必须使用请求中携带的callbackUrl，禁止硬编码

Constraint: MUST be ready for repeated Create Payment calls (idempotent, but status can evolve)

约束：必须支持重复调用创建支付接口（幂等，且状态可更新）

Constraint: MUST align
`delayToCancel`
with payment validity (not always 7 days)

约束：delayToCancel必须与支付有效期对齐（不要固定为7天）

Preferred pattern

推荐实现模式

Common failure modes

常见故障模式

Review checklist

审核 checklist

Related skills

相关指南

Reference

参考资料

payment-async-flow

Original

Translation

Asynchronous Payment Flows & Callbacks

异步支付流程与回调

When this skill applies

适用场景

Decision rules

决策规则

Hard constraints

硬性约束

Constraint: MUST return undefined for async payment methods

约束：异步支付方式必须返回undefined

Constraint: MUST use callbackUrl from request — never hardcode

约束：必须使用请求中携带的callbackUrl，禁止硬编码

Constraint: MUST be ready for repeated Create Payment calls (idempotent, but status can evolve)

约束：必须支持重复调用创建支付接口（幂等，且状态可更新）

Constraint: MUST align delayToCancel with payment validity (not always 7 days)

约束：delayToCancel必须与支付有效期对齐（不要固定为7天）

Preferred pattern

推荐实现模式

Common failure modes

常见故障模式

Review checklist

审核 checklist

Related skills

相关指南

Reference

参考资料

Constraint: MUST return
`undefined`
for async payment methods

约束：异步支付方式必须返回
`undefined`

Constraint: MUST align
`delayToCancel`
with payment validity (not always 7 days)