This guide describes how to develop the middleware that interprets the calls between VTEX and your payment provider.

The Payment Provider Protocol consists of nine endpoints, divided into two sections: Payment Flow and Configuration Flow. The middleware must handle the requests and responses for all these endpoints.

Before you begin, review the Implementation prerequisites in the Payment Provider Protocol article.

The middleware can be developed in any programming language. The following requirements apply:

• The endpoint must be served over HTTPS on port 443 with TLS 1.2 support. Endpoints served over HTTP are not accepted.
• The API must be publicly accessible. Restricted APIs are not accepted during the homologation process.
• The endpoint must use a subdomain or domain name. IP addresses are not accepted.
• The endpoint must respond in less than 5 seconds during homologation tests and less than 20 seconds for any other call.

The following endpoints implement the operations for authorization, cancellation, refund, and settlement.

This endpoint returns the provider's manifest, which contains metadata settings such as payment methods, split configuration, and custom fields.

If you support any type of custom payment, use only the supported method type (Cobranded, Privatelabels, or Promissories) in the "name" field. Do not include the specific name of the custom payment (for example, "Colombian Bank Promissory").

For more information, see the GET List Payment Provider Manifest endpoint documentation.

When a customer completes a purchase at checkout, the provider must create a payment associated with the order. Therefore, the provider must be ready to receive the request body containing the full cart information:

The callbackUrl is used for retry operations in the payment flow. If the provider uses redirect as a payment flow, the returnUrl must also be included so VTEX can redirect the buyer back to checkout after payment.

Both callbackURL and returnURL are generated by VTEX and included in the request payload sent to the provider.

The provider must return the following response:

The delayToAutoSettle and delayToAutoSettleAfterAntifraud parameters define how long the system waits before starting the settlement flow. The delayToCancel parameter works similarly, but triggers the cancellation flow after the timeout.

All three delay values are defined by the provider and must be specified in seconds.

The code and message parameters are optional fields where the provider can include additional information about the transaction. Both values persist through subsequent calls.

For a complete field reference, see the POST Create Payment endpoint documentation.

To cancel a payment created previously, the provider must accept a request containing two fields: paymentId (the identifier of the payment to be canceled) and requestId (the identifier that ensures idempotency).

Idempotency means the same cancellation request can be sent multiple times without changing the result. As described in the Operations section, the cancellation flow can be retried for up to one day until the provider responds.

After completing the cancellation, the provider must return a response like this:

For more details, see the Cancel Payment endpoint documentation.

After a transaction is authorized successfully, the provider can capture the payment. VTEX supports partial settlements.

A payment can be settled in two scenarios:

• When the store invoices the order.
• After the period defined in delayToAutoSettle or delayToAutoSettleAfterAntifraud times out.

The value field is required for the settlement operation.

VTEX sends the following request to settle a payment:

The response value can match the full amount from the request or a smaller amount for a settlement capture:

For more details, see the Capture Payment endpoint documentation.

VTEX supports partial refunds. For example, if a cart contains two items and the store needs to return only one, the refund can cover the amount of that one item instead of the full order amount.

The provider must accept the following request:

Expected response:

The provider can return a value smaller than the requested amount to perform a partial refund.

For more details, see the Refund Payment endpoint documentation.

The Inbound Request endpoint (Beta) enables a direct connection between the VTEX Gateway and the payment provider through a URL. It handles communication with the provider's backend through the gateway, sending the transaction context securely.

Request example:

Expected response:

For more details, see the Inbound Request (Beta) endpoint documentation.

On VTEX, merchants enable connectors through the VTEX Admin. The setup process is similar for all partners. For instructions, see the Register payment and anti-fraud providers article on the Help Center.

The Configuration Flow implements an authentication mechanism that allows the provider to recognize and authorize the merchant's request. The endpoints below generate three credentials — appKey, appToken, and applicationId — that are stored by VTEX, allowing the merchant to enable the connector without manually copying credentials.

This flow is optional and doesn't affect the integration with VTEX. If you don't plan to implement it, skip to the Homologation section.

The request body for this endpoint is:

The applicationId value is always "vtex".

The provider must return an identification token that VTEX uses to redirect the merchant to the provider's application:

For more details, see the Create Authorization Token endpoint documentation.

This endpoint allows the merchant to review the provider's terms and conditions.

Using the token from the previous response, VTEX redirects the merchant to the provider's login page. The response must include an authorizationCode associated with the returnUrl from the first step of the Configuration Flow.

By returning the authorizationCode, the provider grants access to the "vtex" application.

For more details, see the Provider Authentication endpoint documentation.

This endpoint returns the three credential values.

Expected response:

The credentials are stored by VTEX and activated when the merchant enables the connector.

For more details, see the Get Credentials endpoint documentation.