PPP Applied to POS (VTEX Sales App)

When this skill applies

Use this skill when the task is to create, extend, or debug a payment connector that charges a physical card on a POS terminal from VTEX Sales App.

The user mentions PPP + POS, POS connector, in-store payments, Sales App card payments, payment terminal, or
```
Venda Direta Credito
```
/
```
Venda Direta Debito
```
The source of truth is Payment Provider Protocol for Point of Sale (POS)
The goal is to remove the "implement from scratch" barrier: clone the official PPF example from Payment Provider Framework Getting started, or overlay POS on existing PPP — not generate a generic ecommerce connector

Load companions when the step needs them. Do not dump all three into the first reply.

Companion	Load when
generation.md	The user asked to create a POS connector. Ask the four questions, then implement in the listed order.
ppf-scaffold.md	Hosting is VTEX IO / PPF. Copy overlay files onto the official PPF example app.
examples.md	You need expected JSON, the state machine table, or IO retry vs standalone notification.

The hard constraints below override ecommerce PPP and PCI habits. If a generated file violates one, STOP and fix it before writing more files.

Do not use this skill as the default choice for:

Ecommerce PPP endpoints, manifests, and homologation shapes with no POS methods — use
```
payment-provider-protocol
```

IO connector wiring (

PaymentProvider

configuration.json

this.retry

) — use

payment-provider-framework

together with this skill

Pix, Boleto, or browser-redirect async methods — use
```
payment-async-flow
```
Ecommerce card data and Secure Proxy — use
```
payment-pci-security
```
Sales App cart, PDP, or menu UI extensions — use
```
sales-app-extensibility
```

Decision rules

Prefer VTEX IO / PPF unless the partner already hosts PPP middleware. Clone the official example app from the Payment Provider Framework guide and overlay POS; do not start from an empty Express app.
POS payments are still PPP. Implement the six payment-flow endpoints, then overlay the POS rules in this skill.
```
authorize()
```
is a state machine. It never waits on the POS. It only returns the current phase. The connector answers Create Payment; it does not push the Gateway between phases. After the terminal app closes, VTEX Sales App triggers a Gateway callback that issues Create Payment (POS guide step 8). Wait for confirmation then polls the Gateway, which issues more Create Payment (step 9). Do not POST
```
callbackUrl
```
until the processor reports a final status — retry-on-pending is unnecessary and adds about 1 second per authorize.

Stored phase	Who drives the next Create Payment	Create Payment returns
(none yet)	Sales App checkout → Gateway (step 3)	Persist `identify-terminal` ; `undefined` + `vtex.terminal-connector-app`
`identify-terminal` (no serial)	Gateway / Sales App	Same terminal app until `submitUrl` stores a serial
`identify-terminal` (serial stored)	Sales App after the terminal app closes (step 8)	Start the processor charge once; `undefined` + `vtex.challenge-wait-for-confirmation`
`await-pos`	Wait for confirmation polling (step 9)	Same wait app; no second charge; no retry POST
`approved` / `denied`	Wait app / Sales App after IO retry	Final status + `cardBrand` + `firstDigits` + `lastDigits`

```
Venda Direta Credito
```
and
```
Venda Direta Debito
```
are asynchronous card-present methods. Return
```
status: "undefined"
```
and resolve later via
```
callbackUrl
```
. Do not treat them as sync Visa/Mastercard authorizations.
Branch on
```
paymentMethod
```
. On PPF, use
```
isDirectSaleAuthorization
```
from
```
@vtex/payment-provider
```
(canonical
```
DirectSale
```
names, and the narrowed type has no
```
card
```
/
```
secureProxyUrl
```
). On standalone HTTP, compare to those same ASCII strings. A connector may support ecommerce and POS.
The Gateway does not receive the shopper's card for POS. All
```
card
```
fields arrive as
```
null
```
. Do not call Secure Proxy on this path.
Use VTEX's ready-made Payment Apps unless the partner has a documented reason to build a custom one:
- Identify the terminal:
```
vtex.terminal-connector-app
```
- Wait for the POS result:
```
vtex.challenge-wait-for-confirmation
```
Do not use
```
vtex.challenge-terminal-connector-app
```
. That name appears as a flow-diagram example in the POS guide; the implementation contract and the published app are
```
vtex.terminal-connector-app
```
.
```
paymentAppData.payload
```
is a serialized JSON string, not a nested object. On PPF, build pending responses with
```
Authorizations.pending
```
so that is a compile error. Do not close those objects with
```
as AuthorizationResponse
```
— that cast hides the mistake.
```
cardBrand
```
,
```
firstDigits
```
, and
```
lastDigits
```
are required by the POS guide but are not on the SDK response types (checked on
```
@vtex/payment-provider
```
1.4.0 and 1.8.0); the final approved/denied response is the one place a cast is justified.
Communication between the payment processor and the physical POS is outside VTEX. The connector only identifies the terminal, starts the processor transaction, and reports
```
approved
```
or
```
denied
```
to the Gateway.
Without VTEX IO,
```
callbackUrl
```
is a notification endpoint: POST the final status (include POS card fields). With VTEX IO,
```
callbackUrl
```
is a retry endpoint: persist state, then POST it with an empty body. Inside a
```
PaymentProvider
```
method use
```
this.retry(request)
```
. From a
```
service.json
```
extra route use
```
new Payments(ctx.vtex).retry(callbackUrl)
```
— same client as
```
this.retry
```
(gateway-retry metric, IO tracing, configured timeout). Do not POST
```
status
```
/
```
cardBrand
```
on IO. Return the final status plus POS card fields on the next Create Payment /
```
authorize()
```
.
POS serial collection and the processor webhook are extra public routes, not PPP inbound-request. The official example's
```
this.callback(req, resp)
```
is Test Suite only.
```
delayToCancel
```
must be greater than or equal to
```
secondsWaiting
```
.
Every connector endpoint must respond in under 20 seconds in production (under 5 seconds during the Payment Provider Test Suite).
This skill can generate connector code and a test checklist. It cannot replace a real POS, a Sales App device, a configured test account, or homologation.

Hard constraints

Code samples use example identifiers (

PartnerPos

partnername

connector-partnerpos

provider.example.com

) and example numbers (

SECONDS_WAITING = 600

firstDigits

lastDigits

such as

). Replace them with the partner's connector name, public hosts, timeouts, and processor card fragments.

is not a VTEX-required default; the rule is

delayToCancel >= secondsWaiting

. Example BIN/last-four values are truncated fragments, not a PAN.

Constraint: Manifest must declare the POS payment methods by exact API name

GET

/manifest

(and PPF

paymentProvider/configuration.json

paymentMethods

) MUST include

Venda Direta Credito

and/or

Venda Direta Debito

with the exact ASCII names from the POS guide. Admin labels with accents (

Venda Direta Crédito

Venda Direta Débito

) are display names only.

Why this matters The Gateway and Sales App payment conditions bind to these method names. If the manifest only lists

Visa

Mastercard

, merchants cannot configure POS. If the connector invents a name such as

"POS Credit"

, Admin and Sales App will not attach the in-store flow.

Detection If the task is POS and

paymentMethods

lacks

Venda Direta Credito

Venda Direta Debito

, STOP and add them before generating other code.

Correct

json

{
  "paymentMethods": [
    { "name": "Venda Direta Debito", "allowsSplit": "onCapture" },
    { "name": "Venda Direta Credito", "allowsSplit": "onCapture" }
  ]
}

Wrong

json

{
  "paymentMethods": [
    { "name": "Visa", "allowsSplit": "onCapture" },
    { "name": "Mastercard", "allowsSplit": "onCapture" },
    { "name": "POS Credit", "allowsSplit": "onCapture" }
  ]
}

Constraint: Detect POS from

paymentMethod

and never read card PAN from the Gateway

For

Venda Direta Credito

and

Venda Direta Debito

, Create Payment sends

card.holder

card.number

card.csc

card.expiration

card.document

, and

card.token

null

. The connector MUST NOT require those fields, MUST NOT call Secure Proxy, and MUST NOT decline the payment because card data is missing.

On PPF, branch with

isDirectSaleAuthorization

from

@vtex/payment-provider

. That guard uses the SDK

DirectSale

names (exact ASCII), and

DirectSaleAuthorization

has no

card

and no

secureProxyUrl

— so

authorization.card

is a compile error after the narrow. Do not hand-roll

POS_METHODS

(authorization as any).paymentMethod

. On standalone HTTP, compare

paymentMethod

to those same two strings.

callbackUrl

and

value

are already on

Authorization

; do not cast them.

Why this matters The shopper pays on the physical terminal. Treating POS as an ecommerce card authorization fails the charge, or worse, invents Secure Proxy calls with empty tokens. A hand-rolled accented string fails at the Gateway instead of at compile time.

Detection If POS authorize logic reads

card.number

secureProxyUrl

or returns

denied

when

card

is null, STOP and split POS from ecommerce. If PPF code uses

as any

to read

paymentMethod

callbackUrl

, or

value

, STOP and use the typed fields / guard.

Correct

typescript

import {
  isDirectSaleAuthorization,
  AuthorizationRequest,
} from "@vtex/payment-provider";

async function authorize(request: AuthorizationRequest) {
  if (isDirectSaleAuthorization(request)) {
    return authorizePos(request);
  }

  return authorizeEcommerce(request);
}

Wrong

typescript

async function authorize(request: CreatePaymentRequest) {
  if (!request.card?.number) {
    return { status: "denied", message: "Missing card number" };
  }

  return secureProxy.charge(request.card, request.secureProxyUrl);
}

Constraint: First Create Payment response must open the terminal Payment App

When the connector has not yet received the POS serial number for this

paymentId

, Create Payment MUST return

status: "undefined"

and

paymentAppData

for

vtex.terminal-connector-app

payload

MUST be a JSON string with

submitUrl

, the HTTPS endpoint that receives

{"serialNumber": "12345"}

Replace the host in examples with the partner's real public URL. Persist

callbackUrl

and

paymentId

before responding.

On PPF, return

Authorizations.pending(authorization, { delayToCancel, paymentAppData })

AppData.payload

Maybe<string>

, so an object payload is a compile error. Do not wrap that object in

as AuthorizationResponse

Why this matters Without this response, Sales App never opens the camera/barcode challenge, so the processor never learns which terminal to use. A nested

payload

object is not injected into the Payment App. A whole-response cast turns that compile error off.

Detection If the first POS response is

approved

denied

, omits

paymentAppData

, uses

vtex.challenge-terminal-connector-app

, sets

payload

as an object, or uses

as AuthorizationResponse

on a pending body, STOP and fix.

Correct

typescript

import { Authorizations } from "@vtex/payment-provider";

const SECONDS_WAITING = 600;

async function authorizePos(request: CreatePaymentRequest) {
  const existing = await store.get(request.paymentId);

  if (!existing) {
    await store.save(request.paymentId, {
      phase: "identify-terminal",
      status: "undefined",
      callbackUrl: request.callbackUrl,
      paymentMethod: request.paymentMethod,
      value: request.value,
    });

    return Authorizations.pending(request, {
      acquirer: "PartnerPos",
      code: "POS_IDENTIFY_TERMINAL",
      message: "Identify the POS terminal",
      delayToAutoSettle: 21600,
      delayToAutoSettleAfterAntifraud: 1800,
      delayToCancel: SECONDS_WAITING,
      paymentAppData: {
        appName: "vtex.terminal-connector-app",
        payload: JSON.stringify({
          submitUrl: `https://provider.example.com/pos/serial/${request.paymentId}`,
        }),
      },
    });
  }

  return continuePos(request, existing);
}

Wrong

typescript

return {
  paymentId: request.paymentId,
  status: "approved",
  paymentAppData: {
    appName: "vtex.challenge-terminal-connector-app",
    payload: {
      submitUrl: "https://provider.example.com/pos/serial",
    },
  },
};

Constraint: After the serial number, wait with

vtex.challenge-wait-for-confirmation

When

submitUrl

receives

{"serialNumber": "..."}

, the connector MUST associate that serial with

paymentId

(POS guide step 7). Do not start the POS charge in that handler.

The next Create Payment — driven by Sales App after the terminal app closes (step 8) — MUST start the processor charge once, then return

status: "undefined"

plus

vtex.challenge-wait-for-confirmation

with payload

{"secondsWaiting": <int>}

(steps 8.b–8.d). Later polls (step 9) MUST NOT start another charge and MUST NOT POST

callbackUrl

Do not start the POS charge before the serial number exists, and do not start it from the first

authorize()

(no serial yet).

secondsWaiting

is how long the Wait for confirmation app polls.

delayToCancel

(seconds, Create Payment response) is how long the Gateway keeps the payment

undefined

before calling Cancel. Set

delayToCancel >= secondsWaiting

Why this matters Starting the terminal before it is identified charges the wrong device or none. Starting the charge in

submitUrl

diverges from the published sequence (8.b starts the payment, 8.c confirms it started, 8.d returns the wait app). If

delayToCancel

is shorter than

secondsWaiting

, the Gateway cancels while Sales App is still waiting. If Create Payment starts a new processor charge on every poll, the shopper is charged twice.

Detection If Wait for confirmation is returned before a serial is stored, if

startPosCharge

runs in the serial handler or on every poll, if

secondsWaiting

is missing, or if

delayToCancel < secondsWaiting

, STOP.

Correct

typescript

async function onSerialNumber(paymentId: string, serialNumber: string) {
  const payment = await store.get(paymentId);
  if (!payment || payment.phase !== "identify-terminal") {
    return;
  }

  await store.save(paymentId, {
    ...payment,
    serialNumber,
  });
}

function waitingResponse(request: CreatePaymentRequest) {
  return Authorizations.pending(request, {
    acquirer: "PartnerPos",
    code: "POS_WAITING",
    message: "Waiting for POS confirmation",
    delayToAutoSettle: 21600,
    delayToAutoSettleAfterAntifraud: 1800,
    delayToCancel: SECONDS_WAITING,
    paymentAppData: {
      appName: "vtex.challenge-wait-for-confirmation",
      payload: JSON.stringify({ secondsWaiting: SECONDS_WAITING }),
    },
  });
}

Wrong

typescript

async function authorizePos(request: CreatePaymentRequest) {
  await processor.startPosCharge({ paymentId: request.paymentId });

  return {
    paymentId: request.paymentId,
    status: "undefined",
    delayToCancel: 30,
    paymentAppData: {
      appName: "vtex.challenge-wait-for-confirmation",
      payload: JSON.stringify({ secondsWaiting: 600 }),
    },
  };
}

Constraint: Approve or deny only through the mandatory callback, including POS card fields

The processor, not VTEX, reads the physical card. When it reports a final result, the connector MUST notify the Gateway. POS cannot be approved or denied without this callback. Include:

```
status
```
:
```
"approved"
```
or
```
"denied"
```
```
cardBrand
```
```
firstDigits
```
(first six digits / BIN)
```
lastDigits
```
(last four digits)

Those three card fields are required for merchant reconciliation. They come from the processor after the terminal reads the card — not from the original Create Payment

card

object.

Do not log or store the full PAN.

firstDigits

lastDigits

are the allowed fragments.

Why this matters Without notifying the Gateway, Sales App stays on Wait for confirmation until timeout, then cancels. Missing BIN/last-four breaks financial reports even when the charge succeeded on the terminal. On IO, posting a standalone notification body to

callbackUrl

does not complete the flow — the Gateway expects a bodiless retry POST, then a new

authorize()

Detection If POS code returns

approved

on the first Create Payment, STOP. If PPF code

fetch

callbackUrl

with

status

cardBrand

in the body, STOP and use

Payments.retry

this.retry

. If a Service route calls

this.retry

(there is no

this

), STOP and use

new Payments(ctx.vtex).retry(stored.callbackUrl)

. If pending

authorize()

POSTs

callbackUrl

to "nudge" the Gateway, STOP. If standalone code omits the three card fields on the notification POST, STOP.

Correct (PPF extra route — typical processor webhook)

typescript

import { Payments } from "@vtex/payment-provider";

await vbase.saveJSON("pos", paymentId, {
  status: "approved",
  cardBrand: event.cardBrand,
  firstDigits: event.firstDigits,
  lastDigits: event.lastDigits,
  authorizationId: event.authorizationId,
  nsu: event.nsu,
  tid: event.tid,
});

await new Payments(ctx.vtex).retry(callbackUrl);

Correct (inside a
PaymentProvider
method only)

typescript

return this.retry(authorization);

The next

authorize()

MUST return

status

cardBrand

firstDigits

, and

lastDigits

from the persisted record. See examples.md for the standalone notification payload.

Wrong

typescript

async function authorizePos(request: CreatePaymentRequest) {
  return {
    paymentId: request.paymentId,
    status: "approved",
    message: "Assume the terminal will succeed",
  };
}

// Also wrong on VTEX IO: notification payload to callbackUrl
await fetch(authorization.callbackUrl, {
  method: "POST",
  body: JSON.stringify({
    paymentId: request.paymentId,
    status: "approved",
    cardBrand: "Visa",
    firstDigits: "411111",
    lastDigits: "1111",
  }),
});

Constraint: Keep Create Payment idempotent and answers under 20 seconds

Create Payment for a given

paymentId

MUST return the current stored phase and status. It MUST NOT create a second processor transaction. Polling from Wait for confirmation will call Create Payment many times while status is still

undefined

. Those calls can overlap (different

requestId

, same

paymentId

) — a sequential get-then-save can create two records or drop a phase update.

On PPF, persist with

getRawJSON

(capture

etag

) then

saveJSON(..., ifMatch)

. On 412, re-read and continue from the stored document. Pair with

payment-idempotency

. Do not put unique per-request fields (random

tid

requestId

) on the first identify-terminal write.

VBase composes the metadata bucket as

{vendor}.{appName}.{bucket}

and rejects names longer than 50 characters (

400 Metadata bucket name too large

). Use a short bucket such as

pos

. The skill placeholders (

partnername.connector-partnerpos

) fit

pos-payments

; a longer real

vendor.appName

does not.

Do not wait for the shopper to finish on the POS inside the HTTP handler. Compare-and-set

identify-terminal

→

await-pos

, start the processor charge only as the winner of that write, and return. Password retries and insufficient-funds handling stay between the processor and the POS.

Why this matters The Gateway treats a >20s response as failure. Duplicate POS charges happen when each poll hits the acquirer again. Overlapping first writes for one

paymentId

return inconsistent

tid

s and break PPP idempotency. A long VBase bucket fails on the first Create Payment with an opaque 400.

Detection If the handler

await

s the terminal result, calls

processor.startPosCharge

when

phase

is already

await-pos

or final, uses

getJSON

saveJSON

with no

etag

, or uses a VBase bucket that makes

{vendor}.{appName}.{bucket}

longer than 50 characters, STOP.

Correct

typescript

const POS_BUCKET = "pos";

async function savePos(vbase: VBase, paymentId: string, record: PosRecord, etag?: string) {
  try {
    await vbase.saveJSON(POS_BUCKET, paymentId, record, undefined, etag);
    return true;
  } catch (err) {
    const status = (err as any).response && (err as any).response.status;
    if (status === 412) {
      return false;
    }
    throw err;
  }
}

async function continuePos(
  vbase: VBase,
  request: CreatePaymentRequest,
  existing: PosRecord,
  etag?: string
) {
  if (existing.status === "denied") {
    return {
      ...Authorizations.deny(request, {
        acquirer: "PartnerPos",
        code: existing.code,
        message: existing.message,
        tid: existing.tid,
        delayToCancel: SECONDS_WAITING,
      }),
      cardBrand: existing.cardBrand,
      firstDigits: existing.firstDigits,
      lastDigits: existing.lastDigits,
    } as AuthorizationResponse;
  }

  if (existing.status === "approved") {
    return {
      ...Authorizations.approve(request, {
        authorizationId: existing.authorizationId as string,
        nsu: existing.nsu,
        tid: existing.tid as string,
        acquirer: "PartnerPos",
        code: existing.code,
        message: existing.message,
      }),
      delayToCancel: SECONDS_WAITING,
      cardBrand: existing.cardBrand,
      firstDigits: existing.firstDigits,
      lastDigits: existing.lastDigits,
    } as AuthorizationResponse;
  }

  if (existing.phase === "await-pos") {
    return waitingResponse(request);
  }

  if (existing.serialNumber && existing.phase === "identify-terminal") {
    const won = await savePos(
      vbase,
      request.paymentId,
      { ...existing, phase: "await-pos" },
      etag
    );
    if (won) {
      await processor.startPosCharge({
        paymentId: request.paymentId,
        serialNumber: existing.serialNumber,
        amount: existing.value,
      });
    }
    return waitingResponse(request);
  }

  return Authorizations.pending(request, {
    acquirer: "PartnerPos",
    code: "POS_IDENTIFY_TERMINAL",
    message: "Identify the POS terminal",
    delayToCancel: SECONDS_WAITING,
    paymentAppData: {
      appName: "vtex.terminal-connector-app",
      payload: JSON.stringify({
        submitUrl: `https://provider.example.com/pos/serial/${request.paymentId}`,
      }),
    },
  });
}

Wrong

typescript

async function authorizePos(request: CreatePaymentRequest) {
  const result = await processor.startPosCharge(request);
  await processor.waitUntilCardFinished(result, { timeoutMs: 120000 });
  return { paymentId: request.paymentId, status: result.status };
}

Constraint: Collect the POS serial on a public custom route, not inbound-request

vtex.terminal-connector-app

POSTs

{"serialNumber":"..."}

submitUrl

. That URL MUST be a public HTTPS endpoint the Payment App can call. On PPF, declare it in

service.json

routes

and pass it into

PaymentProviderService

. Do not use

POST /payments/{paymentId}/inbound-request/{action}

for this step.

Why this matters Inbound-request is Gateway-initiated. The terminal app posts from the Sales App device. If

submitUrl

is an inbound path, the serial never arrives and the POS charge never starts.

Detection If

submitUrl

contains

/inbound

, STOP. If PPF has no extra

service.json

route for serial collection, STOP.

Correct

json

{
  "routes": {
    "posSerial": {
      "path": "/_v/partnerpos/pos/serial/:paymentId",
      "public": true
    }
  }
}

Wrong

json

{
  "submitUrl": "https://account.myvtex.com/_v/api/my-connector/payments/PAY1/inbound/serial"
}

Preferred pattern

Follow generation.md in order. For PPF, overlay POS on the official example app from the Payment Provider Framework guide using ppf-scaffold.md. Compare IO vs standalone payloads in examples.md.

text

Sales App checkout
  → Gateway POST /payments (Venda Direta Credito|Debito, card = null)
  → authorize(): undefined + vtex.terminal-connector-app (submitUrl)
  → POST submitUrl {"serialNumber":"..."}   (public custom route; store serial only)
  → Sales App closes the terminal app and calls the Gateway (connector does not retry)
  → authorize(): start processor charge once, then undefined + vtex.challenge-wait-for-confirmation
  → Wait for confirmation polls authorize() (still undefined; no second charge; no retry POST)
  → Processor webhook
       PPF: persist + Payments.retry(callbackUrl) / this.retry inside PaymentProvider
       Standalone: POST notification payload (status + card fragments)
  → authorize() returns approved|denied + cardBrand/firstDigits/lastDigits
  → Sales App places the order

Common failure modes

Generating an ecommerce PPP connector (Visa/Mastercard + Secure Proxy) when the user asked for PPP + POS.
Omitting
```
Venda Direta Credito
```
/
```
Venda Direta Debito
```
from the manifest, or using accented Admin labels as API names.
Returning
```
approved
```
before the terminal finishes, or waiting inside Create Payment for the card to be inserted.

Using

vtex.challenge-terminal-connector-app

instead of

vtex.terminal-connector-app

Sending
```
paymentAppData.payload
```
as an object instead of
```
JSON.stringify(...)
```
, or hiding that with
```
as AuthorizationResponse
```
on a pending body.
Setting
```
delayToCancel
```
below
```
secondsWaiting
```
, so the Gateway cancels a payment the Wait app is still polling.
Starting the POS charge in the
```
submitUrl
```
handler (POS guide step 8.b starts it on the following Create Payment).
Starting a new POS charge on every Create Payment poll (broken idempotency).
POSTing
```
callbackUrl
```
on pending responses to "nudge" the Gateway. Sales App and Wait for confirmation already drive Create Payment.
Using
```
getJSON
```
+
```
saveJSON
```
with no
```
etag
```
while Create Payment calls overlap for one
```
paymentId
```
.
Using a VBase bucket that makes
```
{vendor}.{appName}.{bucket}
```
longer than 50 characters (default to
```
pos
```
).
Skipping the Gateway callback, or omitting
```
cardBrand
```
,
```
firstDigits
```
, and
```
lastDigits
```
.
On VTEX IO: POSTing a standalone notification payload (
```
status
```
+ card fields) to
```
callbackUrl
```
instead of a bodiless
```
Payments.retry
```
/
```
this.retry
```
.
Copying the example's Test Suite
```
this.callback(req, resp)
```
as the POS processor webhook.

Calling

this.retry

from a

service.json

extra route (no

PaymentProvider

this

). Use

new Payments(ctx.vtex).retry(callbackUrl)

there.

Putting
```
submitUrl
```
on PPP inbound-request instead of a public custom route.
Applying
```
payment-pci-security
```
Secure Proxy to POS authorize because "it is a card payment".
Building a Sales App cart/PDP extension instead of a payment connector.
Starting from an empty Express app when the partner can use PPF / the official example app.

Review checklist

For PPF, was the app overlaid on the official PPF example (or an existing PPF connector), not an empty HTTP server?

Does

/manifest

(and IO

configuration.json

) declare

Venda Direta Credito

and/or

Venda Direta Debito

with those exact names?

Does authorize branch with
```
isDirectSaleAuthorization
```
(PPF) or the exact ASCII method names (standalone), and skip Gateway card PAN / Secure Proxy for POS?

Is the first POS response

Authorizations.pending

vtex.terminal-connector-app

with string

payload.submitUrl

(no whole-response cast)?

Is
```
submitUrl
```
a public custom route (
```
service.json
```
) that accepts
```
{"serialNumber": "..."}
```
and is not inbound-request?
Does
```
submitUrl
```
only persist the serial (step 7), and does the next Create Payment start the processor charge once (step 8.b)?

Is the waiting response

undefined

vtex.challenge-wait-for-confirmation

with

secondsWaiting

Is
```
delayToCancel >= secondsWaiting
```
, and does every endpoint respond in under 20 seconds?
Are overlapping Create Payment calls for the same
```
paymentId
```
safe (
```
getRawJSON
```
+
```
ifMatch
```
, no second POS charge, no retry-on-pending)?
Is the PPF VBase bucket short enough that
```
{vendor}.{appName}.{bucket}
```
is ≤ 50 characters (use
```
pos
```
)?
PPF: processor webhook persists card fragments then
```
Payments.retry(callbackUrl)
```
(or
```
this.retry
```
inside
```
PaymentProvider
```
)? Next
```
authorize()
```
returns the card fragments (cast only that final response)?
Standalone: notification POST includes
```
status
```
,
```
cardBrand
```
,
```
firstDigits
```
,
```
lastDigits
```
?
Is Cancel implemented so Gateway timeout can abort an
```
undefined
```
POS payment?
Has the partner been told they still need a Sales App device, POS terminal, test account, payment conditions, and homologation?

Testing prerequisites (cannot be automated by the skill)

VTEX often provides a preconfigured store for connector testing. To configure a store manually:

Install the connector (PPF: follow the Payment Provider Framework install steps).
Register a Gateway affiliation for the connector.
Create payment conditions Venda Direta Crédito and/or Venda Direta Débito on that affiliation.
Show those methods on Sales App (
```
checkout-instore-custom.js
```
). Standard condition IDs are
```
44
```
(debit) and
```
45
```
(credit); confirm on the Admin Payment Conditions page.
Install VTEX Sales App on a device and complete a purchase on a real or certified test POS.
Run the Payment Provider Test Suite, including async approved/denied cases, then open a homologation ticket when required.

Related skills

Companions for this skill:

generation.md — Questions to ask, clone-the-example workflow, implementation order
ppf-scaffold.md — Overlay files for the official PPF example app
examples.md — Partner prompts and IO vs standalone payloads

Other payment / Sales App skills:

```
payment-provider-protocol
```
— Mandatory PPP endpoints and response shapes; use together with this skill
```
payment-provider-framework
```
— Use when the POS connector is a VTEX IO app
```
payment-async-flow
```
— Generic
```
undefined
```
+
```
callbackUrl
```
rules; POS adds Payment Apps and card-fragment callbacks on top
```
payment-idempotency
```
—
```
paymentId
```
must not create a second POS charge; Create Payment for one id can overlap (etag /
```
ifMatch
```
)
```
payment-pci-security
```
— Ecommerce card-not-present only; do not apply Secure Proxy to POS authorize
```
sales-app-extensibility
```
— Sales App UI extensions; not the POS payment connector

Reference

Payment Provider Protocol for Point of Sale (POS) - VTEX Sales App — Manifest methods, two-phase Payment Apps, timeouts, callback card fields, testing
Payment App —
```
paymentAppData.appName
```
and
```
payload
```
contract
Payment Provider Framework — Clone the official example app (Getting started), IO connector implementation,
```
this.retry
```
, extra routes
Payment Provider Protocol (Help Center) — Callback URL, notification payload including
```
cardBrand
```
/
```
firstDigits
```
/
```
lastDigits
```
Define payment methods displayed on VTEX Sales App — Sales App payment condition filters (
```
44
```
debit,
```
45
```
credit)
Payment provider homologation — Test Suite and publishing
Registering gateway affiliations — Affiliation setup for tests
Configuring payment conditions — Admin conditions for Venda Direta

payment-ppp-pos

NPX Install

Tags

SKILL.md Content

PPP Applied to POS (VTEX Sales App)

When this skill applies

Decision rules

Hard constraints

Constraint: Manifest must declare the POS payment methods by exact API name

Constraint: Detect POS from
`paymentMethod`
and never read card PAN from the Gateway

Constraint: First Create Payment response must open the terminal Payment App

Constraint: After the serial number, wait with
`vtex.challenge-wait-for-confirmation`

Constraint: Approve or deny only through the mandatory callback, including POS card fields

Constraint: Keep Create Payment idempotent and answers under 20 seconds

Constraint: Collect the POS serial on a public custom route, not inbound-request

Preferred pattern

Common failure modes

Review checklist

Testing prerequisites (cannot be automated by the skill)

Related skills

Reference