--- title: "Start a new transaction" method: POST path: "/api/pvt/transactions" tags: ["Transaction process"] --- # Start a new transaction `POST /api/pvt/transactions` This request is the first step to create a new transaction. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | PCI Gateway | Payment-Make Payments | **Process payments** | There 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). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations. ## Headers - `Content-Type` string, required - `Accept` string, required ## Request body - 1CreateanewtransactionRequest — New transaction request body information. - `value` number, 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. - `referenceId` string, required — Identification number that relates the transaction to a purchase order. - `channel` string, required — Store where the transaction was initiated. - `urn` string, nullable — [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) information. - `salesChannel` string, required — Sales channel information. ## Response `200` OK - StartTransactionResponse — New transaction response body information. - `id` string, required — Transaction identification. - `transactionId` string, required — Transaction identification (same value of the `id` field). - `referenceKey` string, required — Identification number that relates the transaction to a purchase order. It can be also used for anti-fraud to identify the transaction. - `interactions` Interactions, required — Object containing the reference route of transaction interactions. - `href` string, required — Transaction interaction reference route. - `settlements` Settlements, required — Object containing the reference route of transaction settlements. - `href` string, required — Transaction settlement reference route. - `payments` Payments, required — Object containing the reference route of transaction payments. - `href` string, required — Transaction payment reference route. - `refunds` Refunds, required — Object containing the reference route of transaction refunds. - `href` string, required — Transaction refund reference route. - `cancellations` Cancellations, required — Object containing the reference route of transaction cancellations. - `href` string, required — Transaction cancellation reference route. - `capabilities` Capabilities, required — Object containing the reference route of transaction capabilities. - `href` string, required — Transaction capabilities reference route. - `timeoutStatus` 0 | 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. - `totalRefunds` number, required — Total refunded transaction amount. - `status` string, required — Transaction status. - `value` number, required — Transaction value. - `receiverUri` string, nullable, required — Receiver [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) information. - `startDate` string, required — Transaction start date. - `authorizationToken` string, nullable, required — Transaction authorization token. - `authorizationDate` string, nullable, required — Transaction authorization date. - `commitmentToken` string, nullable, required — Transaction completion token. - `commitmentDate` string, nullable, required — Transaction completion date. - `refundingToken` string, nullable, required — Transaction refund token. - `refundingDate` string, nullable, required — Transaction refund date. - `cancelationToken` string, nullable, required — Transaction cancellation token. - `cancelationDate` string, nullable, required — Transaction cancellation date. - `fields` Field[], required — Field containing transaction information. - `name` string, required — Transaction parameter name. - `value` string, required — Transaction parameter value. - `ipAddress` string, nullable, required — IP address information. - `sessionId` string, nullable, required — Session identification. - `macId` string, nullable, required — Random [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 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. - `vtexFingerprint` string, nullable, required — VTEX fingerprint information. - `chargeback` string, nullable, required — Chargeback information. - `whiteSignature` string, nullable, required — White signature (anti-fraud list) information. - `owner` string, required — Responsible for transaction request. - `orderId` string, nullable, required — Order identitication. - `userAgent` string, nullable, required — HTTP client used in the transaction. - `acceptHeader` string, nullable, required — Type of content accepted in the transaction request header. - `antifraudTid` string, nullable, required — Anti-fraud transaction identification. - `antifraudResponse` string, nullable, required — Anti-fraud response information. - `antifraudReference` string, nullable, required — Anti-fraud reference information. - `antifraudAffiliationId` string, nullable, required — Anti-fraud affiliation identification. - `channel` string, required — Store where the transaction was initiated. - `salesChannel` string, required — Sales channel information. - `urn` string, nullable, required — [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) information. - `softDescriptor` string, nullable, required — Custom field for a transaction that can be displayed on the customer's invoice. - `markedForRecurrence` boolean, required — Indicates whether the payment transaction should be recurring. - `buyer` object, nullable, required — Buyer information. - `firstName` string — Buyer first name. - `lastName` string — Buyer last name. - `documentType` string — Type of the document informed by the buyer. - `document` string — Document informed by the buyer. - `email` string — Buyer email address. - `address` string — Buyer address. - `phone` string — Buyer phone number. ## Changes - **2026-04-20** `7f58d8045a19` — 2 info - api tag `Transaction process` added - api tag `Transaction Process` removed - **2024-06-10** `aca4931fa22b` — 2 info - the endpoint scheme security `VtexIdclientAutCookie` was added to the API - the endpoint scheme security `appKey AND appToken` was added to the API - **2024-02-06** `f2ac9712d7ce` — 1 info - request body became optional - **2024-01-16** `7d66c05ad76f` — 1 breaking - the response property `buyer` became nullable for the status `200` - **2024-01-16** `5f4eed6283ef` — 2 breaking - the response property `acceptHeader` became nullable for the status `200` - the response property `userAgent` became nullable for the status `200` [Full history](https://skmtc.dev/vtex/apis/payments-gateway-api/changes/api/pvt/transactions/post.md) --- [API](https://skmtc.dev/vtex/apis/payments-gateway-api.md) · [All operations](https://skmtc.dev/vtex/apis/payments-gateway-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/payments-gateway-api/revisions/c1c6fd255d0e/schema)