Skip to main content
The Payment Provider Protocol is VTEX’s standardized interface for integrating payment providers into the VTEX ecosystem. It defines a set of HTTP endpoints that payment connectors must implement to process transactions.

​
Overview

The protocol enables payment providers to integrate with VTEX without requiring deep knowledge of the platform’s internal architecture. By implementing the required endpoints, your connector can:
  • Process payment authorizations
  • Handle settlements (captures)
  • Process refunds
  • Cancel transactions
  • Receive inbound notifications
This feature is in BETA stage. For production use, ensure your rollout date is at least 3 months away to allow time for testing and issue resolution.

​
Protocol endpoints

The Payment Provider Protocol defines several required endpoints:
1

Manifest endpoint

Provides metadata about your payment provider, including supported payment methods and configuration fields.
GET /manifest
This endpoint is automatically generated by the paymentProvider builder based on your configuration.json file.
2

Payment methods endpoint

Returns the list of payment methods your connector supports.
GET /payment-methods
Also automatically generated from configuration.json.
3

Authorization endpoint

Processes payment authorization requests.
POST /payments
This is the core endpoint where payment processing logic is implemented.
4

Settlement endpoint

Captures a previously authorized payment.
POST /payments/:paymentId/settlements
5

Cancellation endpoint

Cancels an authorized payment.
POST /payments/:paymentId/cancellations
6

Refund endpoint

Refunds a captured payment.
POST /payments/:paymentId/refunds
7

Inbound endpoint

Receives callbacks from the payment provider.
POST /payments/:paymentId/inbound/hooks

​
Request and response flow

The protocol uses a request-response pattern where VTEX sends payment requests to your connector and expects structured responses.

​
Authorization request example

{
  "reference": "v5195405abc",
  "orderId": "v5195405abc-01",
  "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "paymentMethod": "Visa",
  "paymentMethodCustomCode": null,
  "merchantName": "mystore",
  "value": 4307.23,
  "currency": "BRL",
  "card": {
    "holder": "John Doe",
    "number": "4444333322221111",
    "csc": "123",
    "expiration": {
      "month": "12",
      "year": "2025"
    }
  }
}

​
Authorization response example

{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "status": "approved",
  "tid": "TID1234567890",
  "authorizationId": "AUTH123456",
  "nsu": "NSU1234567",
  "code": "APP123",
  "message": "Payment approved"
}

​
Payment status values

Your connector must return one of these status values:
StatusDescription
approvedPayment was approved immediately
deniedPayment was rejected
pendingPayment is being processed asynchronously
undefinedPayment status cannot be determined
When returning pending status, you must use the retry mechanism to update VTEX with the final status once processing completes.

​
Retry mechanism

Unlike traditional callbacks, VTEX IO connectors use a retry mechanism instead of callbacks. When your connector needs more time to process a payment, it:
  1. Returns a pending status immediately
  2. Calls the retry function with the final result when processing completes
  3. VTEX then calls your authorization endpoint again to get the updated status

​
Example from flow.ts

AsyncApproved: (request, retry) => {
  retry(
    Authorizations.approve(request, {
      authorizationId: randomString(),
      nsu: randomString(),
      tid: randomString(),
    })
  )

  return Authorizations.pending(request, {
    delayToCancel: 1000,
    tid: randomString(),
  })
}
The retry flow ensures your connector responds consistently when VTEX requests the payment status again.

​
Secure proxy

For non-PCI-certified providers, VTEX offers a Secure Proxy to communicate with PCI-certified endpoints.
1

Enable secure proxy

Set usesSecureProxy: true in your configuration.json.
2

Receive secure proxy URL

VTEX includes a secureProxyUrl in authorization requests.
3

Use the proxy for card data

Send tokenized card data through the secure proxy to your PCI-certified endpoint.
public myPCIEndpoint = (cardRequest: CardAuthorization) => {
  return this.http.post(
    'my-pci-endpoint',
    {
      holder: cardRequest.holderToken,
      number: cardRequest.numberToken,
      expiration: cardRequest.expiration,
      csc: cardRequest.cscToken
    },
    {
      headers: {
        Authorization: 'my-pci-endpoint-authorization',
      },
      secureProxy: cardRequest.secureProxyUrl,
    } as RequestConfig
  )
}
VTEX IO apps cannot disable the secure proxy. Only configuration apps deployed outside VTEX IO can set usesSecureProxy: false, and they must be PCI-certified.

​
Testing your connector

The protocol includes a test suite to validate your implementation. Your connector must:
  1. Handle different card numbers that trigger specific flows
  2. Persist authorization responses to respond consistently on retry
  3. Implement all required endpoints correctly
See the Testing guide for detailed information.

​
Official documentation

For the complete protocol specification, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us