The VTEX Payments Gateway API provides access to the VTEX payment processing infrastructure. It handles payment transaction management, refunds, chargebacks, payment conditions, and anti-fraud integration for payments processed through VTEX stores.
openapi: 3.0.0
info:
title: VTex Payments Gateway API
description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Payments Gateway API allows you to get payment data and process your store's transactions.\r\n\r\n## Payments Gateway API Index\r\n\r\n### Installments\r\n\r\n- `GET` [Get installments options](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/installments)\r\n\r\n### Configuration\r\n\r\n- `GET` [List all affiliations](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/affiliations)\r\n- `POST` [Insert a new affiliation](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/affiliations)\r\n- `PUT` [Update affiliation by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#put-/api/pvt/affiliations/-affiliationId-)\r\n- `GET` [Get affiliation by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/affiliations/-affiliationId-)\r\n- `GET` [List all payment rules](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/rules)\r\n- `POST` [Insert a new payment rule](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/rules)\r\n- `GET` [Get payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/rules/-ruleId-)\r\n- `PUT` [Update payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#put-/api/pvt/rules/-ruleId-)\r\n- `DELETE` [Delete payment rule by ID](https://developers.vtex.com/docs/api-reference/payments-gateway-api#delete-/api/pvt/rules/-ruleId-)\r\n- `GET` [List all available payment methods](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/merchants/payment-systems)\r\n\r\n### Transaction Process\r\n\r\n- `POST` [1. Starts a new transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions)\r\n- `POST` [2.1 Send payments information public](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pub/transactions/-transactionId-/payments)\r\n- `POST` [2.2 Send payments with saved credit card](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/payments)\r\n- `POST` [3. Send additional data](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/additional-data)\r\n- `PATCH` [3.1 Update additional data (optional)](https://developers.vtex.com/docs/api-reference/payments-gateway-api#patch-/api/pvt/transactions/-transactionId-/additional-data)\r\n- `POST` [Authorize new transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/authorization-request)\r\n- `GET` [Get transaction details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-)\r\n- `GET` [Get payment details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-/payments/-paymentId-)\r\n- `GET` [Get transaction settlement details](https://developers.vtex.com/docs/api-reference/payments-gateway-api#get-/api/pvt/transactions/-transactionId-/settlements)\r\n\r\n### Transaction Flow\r\n\r\n- `POST` [Settle the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/settlement-request)\r\n- `POST` [Refund the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/refunding-request)\r\n- `POST` [Cancel the transaction](https://developers.vtex.com/docs/api-reference/payments-gateway-api#post-/api/pvt/transactions/-transactionId-/cancellation-request)"
version: '1.0'
servers:
- url: https://{accountName}.vtexpayments.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
paths:
/api/pvt/installments:
get:
tags:
- Installments
summary: VTex Get installments options
description: "Returns the best installment options according to the parameters informed in the request.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **View Payment Data** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Installmentsoptions
parameters:
- name: request.value
in: query
description: Value to be divided into installments.
required: true
style: form
schema:
type: integer
example: 10
- name: request.salesChannel
in: query
description: Sales channel identification. Attribute created by the seller in their VTEX store configuration.
required: false
style: form
schema:
type: integer
example: 1
- name: request.paymentDetails[0].id
in: query
description: Payment system identification.
required: false
style: form
schema:
type: integer
example: 2
- name: request.paymentDetails[0].value
in: query
description: Total value paid in installments. If applied in the search, it must be equal to the `request.value` field.
required: false
style: form
schema:
type: integer
example: 10
- name: request.paymentDetails[0].bin
in: query
description: First six digits of the card number.
required: false
style: form
schema:
type: integer
example: 411111
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ValidRequest'
example:
value: 250
installments:
- payment:
id: 72
name:
bin:
value: 250
isDefault: false
self:
href: /api/pvt/payment-systems/72
options:
- ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
quantity: 1
value: 250
interestRate: 0
isExternalInstallmentService:
interestTax: 0
- ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
quantity: 2
value: 125
interestRate: 0
isExternalInstallmentService:
interestTax: 0
- ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
quantity: 3
value: 83.33
interestRate: 0
isExternalInstallmentService:
interestTax: 0
- ruleId: 01a8d68b-9116-4655-83f8-3380f658ec04
quantity: 4
value: 62.5
interestRate: 0
isExternalInstallmentService:
interestTax: 0
- payment:
id: 5
name: ERedeV2 - Visa
bin:
value: 10
isDefault: false
self:
href: /api/pvt/payment-systems/2
options:
- ruleId: 993d4d35-b64d-454d-8108-c560580160e0
quantity: 1
value: 250
interestRate: 0
isExternalInstallmentService:
interestTax:
- payment:
id: 12
name: PayPal - 6U0DTI3M3OKO6R
bin:
value: 10
isDefault: false
self:
href: /api/pvt/payment-systems/12
options:
- ruleId: 9ac0fa1b-dd9d-4549-abb8-e73bbb63c280
quantity: 1
value: 250
interestRate: 0
isExternalInstallmentService:
interestTax:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestValue'
example:
error:
code: '1'
message: Value must be greater than Zero
exception:
deprecated: false
/api/pvt/affiliations:
get:
tags:
- Configuration
summary: VTex List all affiliations
description: "Returns all affiliations (payment and anti-fraud providers) that are already configured in your store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **View Payment Data** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: Affiliations
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
required:
- id
- implementation
- name
- configuration
- isdelivered
- isConfigured
items:
type: object
description: Affiliations information.
properties:
id:
type: string
description: Provider identification.
implementation:
type: string
description: Provider implementation class name.
name:
type: string
description: Provider name.
configuration:
type: array
description: Array containing configuration information fields.
items:
type: object
description: Provider configuration information.
required:
- name
- value
- valueKey
properties:
name:
type: string
description: Configuration parameter name.
value:
type: string
description: Configuration parameter value.
nullable: true
valueKey:
type: string
description: Value key information.
nullable: true
isdelivered:
type: boolean
description: Indicates whether the provider is published and available for use.
isConfigured:
type: boolean
description: Indicates whether the provider is configured.
example:
- id: c4c0d24d-b9b8-468d-af98-916b4ada930d
implementation: Vtex.PaymentGateway.Connectors.CieloV3Connector
name: CieloV3 - 3ds2 prod
configuration:
- name: HowTo
value: https://developercielo.github.io/payment-method-enablement/
valueKey:
- name: MerchantId
value: 56b93f46-2b3a-480f-8f9e-ec8e1fde97c0
valueKey:
- name: MerchantKey
value: '**********'
valueKey:
- name: softDescriptor
value: vtex test
valueKey:
- name: bankInvoiceProvider
value: BancoDoBrasil2
valueKey:
- name: bankDebitProvider
value: BancoDoBrasil
valueKey:
- name: Registered
value: 'true'
valueKey:
- name: use3ds
value: 'true'
valueKey:
- name: EstablishmentCode
value: '1119338171'
valueKey:
- name: MerchantName
value: VTEX
valueKey:
- name: MCC
value: '7372'
valueKey:
- name: ClientId
value: 6b4853d7-44f8-4c58-8d48-811d4cb49e1a
valueKey:
- name: ClientSecret
value: '**********'
valueKey:
- name: BpmpiAuth
value: 'true'
valueKey:
- name: BpmpiAuthNotifyOnly
value: 'false'
valueKey:
- name: BpmpiAuthSuppresschallenge
value: 'false'
valueKey:
- name: useEarlySecurityCapture
value: '0'
valueKey:
- name: autoSettleDelay
value: ''
valueKey:
- name: isProduction
value: 'true'
valueKey:
isdelivered: true
isConfigured: true
- id: 42bc3c4c-f8ca-4be0-870c-edfe263546b6
implementation: Vtex.PaymentGateway.Connectors.VtexGiftCardHub.VtexGiftCardHubConnector
name: Gift Card
configuration:
- name: usesOnlineRefund
value: 'true'
valueKey:
- name: useEarlySecurityCapture
value: '1'
valueKey:
isdelivered: true
isConfigured: true
- id: 1bd6e98e-6986-4ff3-ab58-78a37bd2a2ef
implementation: Vtex.PaymentGateway.Connectors.AdyenConnector
name: Adyen
configuration:
- name: username
value: [email protected]
valueKey:
- name: password
value: '**********'
valueKey:
- name: account
value: VTEXPubliEventos
valueKey:
- name: liveEndpointPrefix
value: 99e86b1244882cda-VtexBR
valueKey:
- name: marketPayAccount
value: ''
valueKey:
- name: marketPayCommission
value: ''
valueKey:
- name: subMerchantId
value: ''
valueKey:
- name: Currency
value: BRL
valueKey:
- name: Brand
value: boletobancario_bradesco
valueKey:
- name: ShopperStatement
value: ''
valueKey:
- name: SoftDescriptor
value: ''
valueKey:
- name: SkinCode
value: ''
valueKey:
- name: LanguageCode
value: pt
valueKey:
- name: expirationDays
value: '7'
valueKey:
- name: HmacKey
value: ''
valueKey:
- name: useMultipleRefund
value: 'false'
valueKey:
- name: use3DS
value: 'true'
valueKey:
- name: threeDSecureMode
value: 3ds2-auth
valueKey:
- name: requireLiabilityShift
value: 'false'
valueKey:
- name: applePay_MerchantId
value: ''
valueKey:
- name: applePay_MerchantCertificate
value:
valueKey:
- name: applePay_MerchantPassword
value: ''
valueKey:
- name: autoSettle
value: '4'
valueKey:
- name: countryCode
value: AT
valueKey:
- name: useEarlySecurityCapture
value: '0'
valueKey:
- name: useAntifraud
value: 'false'
valueKey:
- name: isProduction
value: 'true'
valueKey:
- name: LinkHelp
value: ''
valueKey:
isdelivered: true
isConfigured: true
- id: 400b66d3-bc9a-4eb8-afc0-f32fe63c7121
implementation: Vtex.PaymentGateway.Connectors.BankIssuedInvoiceItauConnector
name: BankInvoice Itau
configuration:
- name: CompanyName
value: TESTE
valueKey:
- name: Document
value: '1111111111111111'
valueKey:
- name: BranchCode
value: '1158'
valueKey:
- name: Account
value: '1160'
valueKey:
- name: ExpiryDays
value: '5'
valueKey:
- name: Instructions
value: xpto
valueKey:
- name: Portfolio
value: '11'
valueKey:
- name: BankAgreement
value: '000111'
valueKey:
- name: TransferorCode
value: a
valueKey:
- name: companyAddress
value: ''
valueKey:
- name: Registered
value: 'true'
valueKey:
- name: configurationTemplate
value: '{"name":"Registered","template":[{"value":"true","configuration":[{"name":"AuthEnvironment","hidden":false},{"name":"EnvironmentType","hidden":false},{"name":"ClientId","hidden":false},{"name":"ClientSecret","hidden":false},{"name":"ItauKey","hidden":false}]}]}'
valueKey:
- name: AuthEnvironment
value: ''
valueKey:
- name: EnvironmentType
value: ''
valueKey:
- name: ClientId
value: ''
valueKey:
- name: ClientSecret
value: ''
valueKey:
- name: ItauKey
value: ''
valueKey:
- name: TransactionExpirationDays
value: '20'
valueKey:
- name: isProduction
value: 'true'
valueKey:
isdelivered: true
isConfigured: true
- id: 1d884ffd-13d7-419e-a487-da55a2205792
implementation: Vtex.PaymentGateway.Connectors.TestConnector
name: Test Connector
configuration:
- name: OperationTime
value: '1000'
valueKey:
- name: applePay_MerchantId
value: ''
valueKey:
- name: applePay_MerchantCertificate
value:
valueKey:
- name: applePay_MerchantPassword
value: ''
valueKey:
- name: SamsungPayServiceId
value: ''
valueKey:
isdelivered: false
isConfigured: true
deprecated: false
post:
tags:
- Configuration
summary: VTex Insert new affiliation
description: "Registers a new affiliation (payment or anti-fraud provider) in your store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-ManageStore | **Manage Store** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: InsertAffiliation
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsertAffiliationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliationResponse'
example:
id: fg8b4ea5-0b24-47dc-971e-2f6635ea1f14
implementation: Vtex.PaymentGateway.Connectors.CieloV3Connector
name: CieloV3 - Test
configuration:
- name: HowTo
value: https://developercielo.github.io/payment-method-enablement/
valueKey:
- name: MerchantId
value: sampleData
valueKey:
- name: MerchantKey
value: '**********'
valueKey:
- name: softDescriptor
value: teste
valueKey:
- name: bankInvoiceProvider
value: Disabled
valueKey:
- name: bankIDebitProvider
value: Disabled
valueKey:
- name: useEarlySecurityCapture
value: '0'
valueKey:
- name: isProduction
value: 'false'
valueKey:
- name: bankDebitProvider
value: Disabled
valueKey:
- name: Registered
value: 'false'
valueKey:
isdelivered: true
isConfigured: true
deprecated: false
/api/pvt/affiliations/{affiliationId}:
put:
tags:
- Configuration
summary: VTex Update affiliation by ID
description: "Updates information about an affiliation (payment or anti-fraud provider) configured in your store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-ManageStore | **Manage Store** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: UpdateAffiliation
parameters:
- $ref: '#/components/parameters/affiliationId'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAffiliationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliationResponse'
example:
id: fg8b4ea5-0b24-47dc-971e-2f6635ea1f14
implementation: Vtex.PaymentGateway.Connectors.CieloV3Connector
name: CieloV3 - Test
configuration:
- name: HowTo
value: https://developercielo.github.io/payment-method-enablement/
valueKey:
- name: MerchantId
value: sampleData_2
valueKey:
- name: MerchantKey
value: '**********'
valueKey:
- name: softDescriptor
value: teste_update
valueKey:
- name: bankInvoiceProvider
value: Disabled
valueKey:
- name: bankIDebitProvider
value: Disabled
valueKey:
- name: useEarlySecurityCapture
value: '0'
valueKey:
- name: isProduction
value: 'false'
valueKey:
- name: bankDebitProvider
value: Disabled
valueKey:
- name: Registered
value: 'false'
valueKey:
isdelivered: true
isConfigured: true
deprecated: false
get:
tags:
- Configuration
summary: VTex Get affiliation by ID
description: "Returns data for a specific affiliation (payment or anti-fraud provider).\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| PCI Gateway | Payment-Make Payments | **View Payment Data** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:/
# --- truncated at 32 KB (237 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-payments-gateway-openapi-original.yml