The VTEX Payment Provider Protocol API defines the interface that payment providers must implement to integrate with VTEX checkout. It covers authorization, settlement, refund, and void operations, as well as payment method discovery and 3DS authentication flows.
openapi: 3.0.0
info:
title: VTex Payment Provider Protocol API
description: ">ℹ️ The Payment Provider Protocol is a set of definitions to help you integrate your payment processing API into the VTEX platform, including sub-acquirers, acquirers, gateways, and custom payment services. \r\n\r\nTo achieve this, you must implement a web API (REST) following the specifications described in this documentation.\r\n\r\nTo learn more about the Payment Provider Protocol, check our [Help Center article](https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m).\r\n\r\n## Endpoint requirements\r\n\r\n * Must use a standard subdomain/domain name, not an IP address.\r\n * Must be served over HTTPS on port 443 with TLS 1.2 support.\r\n * Must respond in less than 5 seconds when running the tests.\r\n * Must respond in less than 20 seconds when in production.\r\n * Must be [PCI-DSS compliant](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) or use [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to accept branded cards like Visa, Mastercard, Amex, etc.\r\n\r\n## Testing\r\n\r\nYou can perform tests on your payment provider using our [VTEX - Payment Provider Test Suite](https://apps.vtex.com/vtex-payment-provider-test-suite/p).\r\n\r\n>ℹ An extra header `X-VTEX-API-Is-TestSuite` = `true` will be sent for every test suite request, to help you easily identify it and mock any required scenarios.\r\n\r\nFor more details about testing a Payment Provider, check our [Payment Provider Homologation](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-homologation) article.\r\n\r\n## Common parameters in the documentation\r\n\r\n<table>\r\n <tr>\r\n <td><code>{{providerApiEndpoint}}</code></td>\r\n <td>Provider's endpoint for the implementation.</td>\r\n </tr>\r\n <tr>\r\n <td><code>{{X-PROVIDER-API-AppKey}}</code></td>\r\n <td>Unique identifier created by the provider and configured on the provider configuration page (Admin VTEX).</td>\r\n </tr>\r\n <tr>\r\n <td><code>{{X-PROVIDER-API-AppToken}}</code></td>\r\n <td>Unique token created by the provider and configured on the provider configuration page (Admin VTEX).</td>\r\n </tr>\r\n</table> \r\n\r\n## Payment Provider Protocol API Index\r\n\r\n### Payment Flow\r\n\r\n- `GET` [List Payment Provider Manifest](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/manifest)\r\n- `POST` [Create payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments)\r\n- `POST` [Cancel payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/cancellations)\r\n- `POST` [Settle payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/settlements)\r\n- `POST` [Refund payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/refunds)\r\n- `POST` [Inbound request (BETA)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/inbound-request/-action-)\r\n\r\n### Configuration Flow\r\n\r\n- `POST` [Create authorization token](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/authorization/token)\r\n- `GET` [Provider authentication](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/authorization/redirect)\r\n- `GET` [Get credentials](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/authorization/credentials)"
version: '1.0'
servers:
- url: https://{providerApiEndpoint}
description: Payment provider endpoint URL.
variables:
providerApiEndpoint:
description: Payment provider endpoint URL.
default: '{providerApiEndpoint}'
paths:
/manifest:
get:
tags:
- Payment Flow
summary: VTex List Payment Provider Manifest
description: "Exposes the provider manifest, including metadata settings such as payment methods, split configuration, and custom fields.\r\n\r\n> ℹ️ This request is made from VTEX to the payment provider.\r\n\r\n## Available payment methods\r\n\r\n<table>\r\n <tr>\r\n <th>Payment Method</th>\r\n <th>Type</th>\r\n <th>Country</th>\r\n </tr>\r\n <tr>\r\n <td><code>Visa</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Mastercard</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>American Express</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Discover</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>JCB</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Diners</code></td>\r\n <td>Credit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Elo</code></td>\r\n <td>Credit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Hipercard</code></td>\r\n <td>Credit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Aura</code></td>\r\n <td>Credit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Banricompras</code></td>\r\n <td>Credit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Credz</code></td>\r\n <td>Credit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Cabal</code></td>\r\n <td>Credit Card</td>\r\n <td>Argentina, Brazil, Uruguay, Paraguay</td>\r\n </tr>\r\n <td><code>Cartes Bancaires (CB)</code></td>\r\n <td>Credit Card</td>\r\n <td>France</td>\r\n </tr>\r\n <tr>\r\n <td><code>VirtualDebitElo</code></td>\r\n <td>Debit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Visa Electron</code></td>\r\n <td>Debit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Maestro</code></td>\r\n <td>Debit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Mastercard Debit</code></td>\r\n <td>Debit Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Débito Online</code></td>\r\n <td>Debit Card</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Cobranded</code></td>\r\n <td>Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Privatelabels</code></td>\r\n <td>Card</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Promissories</code></td>\r\n <td>Generic</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Cash</code></td>\r\n <td>Generic</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Pix</code></td>\r\n <td>Online Transfer</td>\r\n <td>Brazil</td>\r\n </tr>\r\n <tr>\r\n <td><code>Safetypay</code></td>\r\n <td>Online Transfer</td>\r\n <td>Americas and Europe</td>\r\n </tr>\r\n <tr>\r\n <td><code>BankInvoice</code></td>\r\n <td>Offline/Voucher</td>\r\n <td>Brazil (Boleto Bancário)</td>\r\n </tr>\r\n <tr>\r\n <td><code>FichaDeposito</code></td>\r\n <td>Offline/Voucher</td>\r\n <td>Mexico</td>\r\n </tr>\r\n <tr>\r\n <td><code>Rapipago</code></td>\r\n <td>Offline/Voucher</td>\r\n <td>Argentina</td>\r\n </tr>\r\n <tr>\r\n <td><code>OXXO</code></td>\r\n <td>Offline/Voucher</td>\r\n <td>Mexico</td>\r\n </tr>\r\n <tr>\r\n <td><code>Voucher</code></td>\r\n <td>Offline/Voucher</td>\r\n <td>Mexico</td>\r\
\n </tr>\r\n <tr>\r\n <td><code>Bitcoin</code></td>\r\n <td>Cryptocurrency</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Venda Direta Credito</code></td>\r\n <td>Credit Card (Physical)</td>\r\n <td>Global</td>\r\n </tr>\r\n <tr>\r\n <td><code>Venda Direta Debito</code></td>\r\n <td>Debit Card (Physical)</td>\r\n <td>Global</td>\r\n </tr>\r\n</table> \r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
operationId: Manifest
security: []
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Success-Manifest'
example:
paymentMethods:
- name: Visa
allowsSplit: onCapture
- name: Pix
allowsSplit: disabled
- name: Mastercard
allowsSplit: onCapture
- name: American Express
allowsSplit: onCapture
- name: BankInvoice
allowsSplit: onAuthorize
- name: Privatelabels
allowsSplit: disabled
- name: Promissories
allowsSplit: disabled
customFields:
- name: Merchant's custom field
type: text
- name: Merchant's custom select field
type: select
options:
- text: Field option 1
value: '1'
- text: Field option 2
value: '2'
- text: Field option 3
value: '3'
autoSettleDelay:
minimum: '0'
maximum: '720'
metadataFields:
- MetadataName1
- MetadataName2
deprecated: false
/payments:
post:
tags:
- Payment Flow
summary: VTex Create payment
description: "Creates a new payment and initiates the payment flow.\r\n\r\n> ℹ️ This request is made from VTEX to the payment provider.\r\n\r\nPayment providers must:\r\n\r\n- Execute authorization on payments made through credit/debit card or any synchronized payments;\r\n\r\n- Return the required information to the customer on payments made through bank-issued invoice, redirect, or any async payments.\r\n\r\n >ℹ️ This endpoint has to meet the principle of [idempotence](https://en.wikipedia.org/wiki/Idempotence). When calling this endpoint for the first time of a payment, without a `paymentId`, it should create a new payment. When calling this endpoint for an existing `paymentId`, it should not create another payment, but return the updated status of the existing payment instead.\r\n\r\n## Callbacks (asynchronous flow)\r\n\r\nCallbacks are used for asynchronous payments, which do not receive the final status immediately. At first, an `undefined` status is returned, and the final status will be received from a callback request in the future as `authorized` or `denied`. There are two types of callbacks:\r\n\r\n- **Notification:** If a payment returns with `undefined` status, you are expected to send us a callback/notification to update it later, sending a POST with an updated version of your response (same structure as above) to the `callbackUrl` we have provided.\r\n\r\n- **Retry:** If a payment returns with `undefined` status, you are expected to call the retry endpoint provided by the `callbackUrl` when the processing of the payment is completed, so we make another Create Payment request to update the status with the new value (`authorized` or `denied`).\r\n\r\nCallback requests should be authenticated using a Key and Token which you can [generate from your VTEX partner account License Manager](https://help.vtex.com/en/tutorial/application-keys--2iffYzlvvz4BDMr6WGUtet#generating-app-keys-in-your-account). To do so, `POST` your request passing the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` headers with your credentials. **Note:** do not mix up these credentials with the ones we send on behalf of the merchant when sending our requests.\r\n\r\n>⚠ For integrations not using VTEX IO, use the **Notification** callback. For integrations developed using VTEX IO infrastructure, use the **Retry** callback.\r\n\r\n### Callback URL\r\n\r\nThe `callbackUrl` field contains an URL that the payment provider uses to make a callback and inform our gateway of the final payment status: `approved` or `denied`. \r\n\r\nThis URL has some query parameters, including the `X-VTEX-signature`. This parameter is mandatory and contains a signature token to identify that the request has been generated from VTEX as a security measure. The signature token has at most 32 characters. You can check an example of callback URL with the signature token below:\r\n\r\n```\r\nhttps://gatewayqa.vtexpayments.com.br/api/pvt/payment-provider/transactions/8FB0F111111122222333344449984ACB/payments/A2A9A25B11111111222222333327883C/callback?accountName=teampaymentsintegrations&X-VTEX-signature=R******tk\r\n```\r\n\r\nIn the [Transactions page of the Admin](https://help.vtex.com/en/tutorial/how-to-view-the-orders-details--tutorials_452), the signature token appears masked for security reasons, as in this example: `X-VTEX-signature=Rj******tk`.\r\n\r\nWhen making the callback request, we recommend that payment providers use the callback URL exactly as received, which guarantees that all the parameters are included.\r\n\r\nSee below an example of a payload forwarded along with the callback URL:\r\n\r\n```json\r\n{\r\n \"paymentId\": \"8B3BA2F4352545A8B1C5A215F356A01C\",\r\n \"status\": \"approved\",\r\n \"authorizationId\": \"184520\",\r\n \"nsu\": \"21705348\",\r\n \"tid\": \"21705348\",\r\n \"acquirer\": \"pagmm\",\r\n \"code\": \"0000\",\r\n \"message\": \"Successfully approved transaction\",\r\n \"delayToAutoSettle\": 1200,\r\n \"delayToAutoSettleAfterAntifraud\": 1200,\r\n \"delayToCancel\": 86400,\r\n \"cardBrand\": \"Mastercard\"\
,\r\n \"firstDigits\": \"534696\",\r\n \"lastDigits\": \"6921\",\r\n \"maxValue\": 16.6\r\n}\r\n```\r\n\r\n>ℹ️ The parameter values sent in the callback payload replace the original values informed in the **Create Payment** request.\r\n\r\n>⚠️ If the waiting parameters (`delayToAutoSettle` and `delayToAutoSettleAfterAntifraud`) are not sent with the callback URL, the values for these parameters will be automatically set to 24 hours.\r\n\r\n## Beta features\r\n\r\nThe beta features available for payment providers are:\r\n\r\n- `inboundRequestsUrl`: Allows to forward external requests back to your payment provider implementation, including the configured credentials (`X-VTEX-API-*` headers), and settings.\r\n\r\n>ℹ You can reach out to our team by [opening a ticket](https://help.vtex.com/en/tutorial/opening-tickets-to-vtex-support--16yOEqpO32UQYygSmMSSAM) to know more about any beta features.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
operationId: CreatePayment
parameters:
- $ref: '#/components/parameters/X-PROVIDER-API-AppKey'
- $ref: '#/components/parameters/X-PROVIDER-API-AppToken'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []
requestBody:
content:
application/json:
schema:
type: object
required:
- reference
- orderId
- shopperInteraction
- transactionId
- paymentId
- paymentMethod
- paymentMethodCustomCode
- merchantName
- value
- currency
- installments
- deviceFingerprint
- miniCart
- url
- callbackUrl
- returnUrl
properties:
reference:
type: string
description: Merchant's order reference provided by VTEX Checkout.
example: '618272'
orderId:
type: string
description: Merchant's order identifier provided by VTEX Checkout (also called order group).
example: '1072430428324'
shopperInteraction:
type: string
description: 'Indicates which system the buyer interacted with (examples: ecommerce, instore, subscription).'
example: ecommerce
verificationOnly:
type: boolean
description: Indicates whether this payment is just to validate the buyer's payment method information (for instance, validate the credit card information).
example: false
transactionId:
type: string
description: VTEX transaction ID related to this payment.
example: 2F023FD5A72A49D48A8633252B7CCBD6
paymentId:
type: string
description: VTEX payment ID that can be used as unique identifier.
example: 01693EB95BE443AC85874E395CD91565
paymentMethod:
type: string
description: The payment method chosen for this payment. It must be one of the available payment methods offered by the provider, which can be obtained from the [List Payment Provider Manifest endpoint](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/manifest).
example: Diners
paymentMethodCustomCode:
type: string
description: Configurable for Cobranded and Privatelabels payment methods.
nullable: true
example:
merchantName:
type: string
description: VTEX merchant name that will receive the payment.
example: mystore
value:
type: number
description: Value amount of the payment.
example: 31.9
referenceValue:
type: number
description: Value amount of the payment without interest applied. This value is the same as the "value" field when "installmentsInterestRate" is 0.0.
example: 31.9
currency:
type: string
description: Currency code (ISO 4217 alpha-3).
example: BRL
installments:
type: number
description: Number of installments.
example: 1
installmentsInterestRate:
type: number
description: The interest rate.
example: 0
installmentsValue:
type: number
description: The value of each installment.
example: 31.9
deviceFingerprint:
type: string
description: A hash that represents the device used to initiate the payment.
example: '75076388'
ipAddress:
type: string
description: The IP Address of the buyer.
example: 187.105.111.65
card:
type: object
description: Card information used for payment. This parameter is required only with card payment methods (credit, debit or co-branded).
required:
- holder
- number
- csc
- expiration
properties:
holder:
type: string
description: Card holder name.
example: John Doe
nullable: true
holderToken:
type: string
description: A token representing the card holder (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: '#vtex#token#d799bae#csc#'
number:
type: string
description: Card number.
example: 364901****2661
nullable: true
csc:
type: string
description: Card security code.
example: '***'
nullable: true
bin:
type: string
description: First six digits of the card number (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: '364901'
numberToken:
type: string
description: A token representing the card number (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: '#vtex#token#d799bae#number#'
numberLength:
type: number
description: The number of characters in the card number (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: 16
cscToken:
type: string
description: A token representing the card security code (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: '#vtex#token#d799bae#csc#'
cscLength:
type: number
description: The number of characters in the Card Security Code (this field is absent in case the provider does not use the [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy)).
example: 3
expiration:
type: object
description: Information about card expiration.
required:
- month
- year
properties:
month:
type: string
description: Card expiration month (2-digits).
example: '12'
nullable: true
year:
type: string
description: Card expiration year (4-digits).
example: '2020'
nullable: true
document:
type: string
description: Card holder's document.
example: '39295416023'
paymentOrigin:
type: string
description: Identifies the type of wallet used in the payment. Please contact our [VTEX Support](https://help.vtex.com/support) to enable this field in your account.
example: Google Pay
cryptogram:
type: string
description: 3DS cryptogram information (available only for payments transactions with DPAN cards). Please contact our [VTEX Support](https://help.vtex.com/support) to enable this field in your account.
example: /gAAAAAAAbQHWutaqaYsQLsAAAA=
eci:
type: string
description: '[Electronic Commerce Indicator](https://support.midtrans.com/hc/en-us/articles/204161150-What-is-ECI-on-3DS-protocol-). This value indicates the result of the authentication attempt on transactions enforced by the 3DS (available only for payments transactions with DPAN cards). Please contact our [VTEX Support](https://help.vtex.com/support) to enable this field in your account.'
example: '05'
miniCart:
type: object
description: Minicart information.
required:
- shippingValue
- taxValue
- buyer
- shippingAddress
- billingAddress
- items
properties:
shippingValue:
type: number
description: Total shipping value.
example: 2
taxValue:
type: number
description: Total tax value.
example: 1
buyer:
type: object
description: Buyer information.
required:
- firstName
- lastName
- document
- documentType
- email
- phone
properties:
id:
type: string
description: Buyer's unique identifier.
example: c1245228-1c68-11e6-94ac-0afa86a846a5
firstName:
type: string
description: Buyer's first name.
example: John
lastName:
type: string
description: Buyer's last name.
example: Doe
document:
type: string
description: Buyer's document number.
example: '01234567890'
documentType:
type: string
description: Buyer's document type.
example: cpf
email:
type: string
description: Buyer's email.
example: [email protected]
phone:
type: string
description: Buyer's phone number.
example: '+5521999999999'
isCorporate:
type: boolean
description: Indicates whether or not the buyer is corporate. If `true`, the fields `corporateName`, `tradeName` and `corporateDocument` are required.
example: false
corporateName:
type: string
description: Buyer's corporate name. This field is required if `isCorporate` is `true`.
example: VTEX
nullable: true
tradeName:
type: string
description: Buyer's trade name. This field is required if `isCorporate` is `true`.
example: VTEX
nullable: true
corporateDocument:
type: string
description: Buyer's corporate document number. This field is required if `isCorporate` is `true`.
example: '123456789'
nullable: true
createdDate:
type: string
description: Date when the buyer's profile was created in yyyy-MM-ddTHH:mm:ss format.
example: '2020-02-18T18:17:45'
shippingAddress:
type: object
description: Information about the address where the purchase will be delivered.
required:
- country
- street
- number
- neighborhood
- postalCode
- city
- state
properties:
country:
type: string
description: Shipping address country code (ISO 3166 alpha-3).
example: BRA
street:
type: string
description: Shipping address street.
example: Praia de Botafogo St.
number:
type: string
description: Shipping address number.
example: '300'
complement:
type: string
description: Shipping address complement.
example: 3rd Floor
neighborhood:
type: string
description: Shipping address neighborhood.
example: Botafogo
postalCode:
type: string
description: Shipping address postal code.
example: '22250040'
city:
type: string
description: Shipping address city.
example: Rio de Janeiro
state:
type: string
description: Shipping address state/province.
example: RJ
billingAddress:
type: object
description: Buyer's billing address information.
required:
- country
- street
- number
- neighborhood
- postalCode
- city
- state
properties:
country:
type: string
description: Billing address country code (ISO 3166 alpha-3).
example: BRA
street:
type: string
description: Billing address street.
example: Brigadeiro Faria Lima Avenue
number:
type: string
description: Billing address number.
example: '4440'
complement:
type: string
description: Billing address complement.
example: 10th Floor
neighborhood:
type: string
description: Billing address neighborhood.
example: Itaim Bibi
postalCode:
type: string
description: Billing address postal code.
example: '04538132'
city:
type: string
description: Billing address city.
example: São Paulo
state:
type: string
description: Billing address sta
# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-payment-provider-protocol-openapi-original.yml