v50

latestOpenAPI 3.0.0raw.githubusercontent.com2026-04-202547455.8 KB

Transaction process

Start a new transaction

This request is the first step to create a new transaction.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources 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:

Product	Category	Resource
PCI Gateway	Payment-Make Payments	Process payments

There are no applicable predefined roles for this resource list. You must create a custom 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.

❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.

post/api/pvt/transactions

Headers

Content-Typestring required

Example:application/json

Type of the content being sent.

Acceptstring required

Example:application/json

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Request body

valuenumber required

Transaction value. The value must be described without using separation for decimals, e.g. for a transaction with a value equal to 201.50, send 20150.

referenceIdstring required

Identification number that relates the transaction to a purchase order.

channelstring required

Store where the transaction was initiated.

urnstring nullable

URN information.

salesChannelstring required

Sales channel information.

Example request

{
  "value": 20000,
  "referenceId": "1234567",
  "channel": "cosmetics2",
  "urn": "urn:amazon:webservices:clientvpn",
  "salesChannel": "1"
}

Response

idstring required

Transaction identification.

transactionIdstring required

Transaction identification (same value of the id field).

referenceKeystring required

Identification number that relates the transaction to a purchase order. It can be also used for anti-fraud to identify the transaction.

timeoutStatus0 | 1 | 2 | 3 | 4 required

Field that represents the possible transaction timeout statuses. Possible statuses and meanings: 0 = NotStarted, 1 = CancellingOrFinishing, 2 = CancellingOrFinishingByTimeout, 3 = CancelledOrFinished and 4 = TriesExceeded.

totalRefundsnumber required

Total refunded transaction amount.

statusstring required

Transaction status.

valuenumber required

Transaction value.

receiverUristring nullable required

Receiver URI information.

startDatestring required

Transaction start date.

authorizationTokenstring nullable required

Transaction authorization token.

authorizationDatestring nullable required

Transaction authorization date.

commitmentTokenstring nullable required

Transaction completion token.

commitmentDatestring nullable required

Transaction completion date.

refundingTokenstring nullable required

Transaction refund token.

refundingDatestring nullable required

Transaction refund date.

cancelationTokenstring nullable required

Transaction cancellation token.

cancelationDatestring nullable required

Transaction cancellation date.

ipAddressstring nullable required

IP address information.

sessionIdstring nullable required

Session identification.

macIdstring nullable required

Random UUID V4 generated when the Request Capture receives a session that does not contain the macID already set. This value is set to the cookie VtexRCMacIdv7. The cookie has 1 year of expiration.

vtexFingerprintstring nullable required

VTEX fingerprint information.

chargebackstring nullable required

Chargeback information.

whiteSignaturestring nullable required

White signature (anti-fraud list) information.

ownerstring required

Responsible for transaction request.

orderIdstring nullable required

Order identitication.

userAgentstring nullable required

HTTP client used in the transaction.

acceptHeaderstring nullable required

Type of content accepted in the transaction request header.

antifraudTidstring nullable required

Anti-fraud transaction identification.

antifraudResponsestring nullable required

Anti-fraud response information.

antifraudReferencestring nullable required

Anti-fraud reference information.

antifraudAffiliationIdstring nullable required

Anti-fraud affiliation identification.

channelstring required

Store where the transaction was initiated.

salesChannelstring required

Sales channel information.

urnstring nullable required

URN information.

softDescriptorstring nullable required

Custom field for a transaction that can be displayed on the customer's invoice.

markedForRecurrenceboolean required

Indicates whether the payment transaction should be recurring.