Send a GET request to the Get current or create a new cart endpoint to retrieve the orderFormId of the shopping cart you intend to use to create an order. The orderFormId is a unique identifier for the orderForm linked to a specific shopping cart.

For more information, refer to the Get cart information by ID guide.

Place a new order via the Place order from an existing cart endpoint, using the shopping cart identification (orderFormId) as a path parameter and providing the following information in the request body:

• referenceId: the same orderFormId value used in the path parameter.
• value: total value of the order in cents (e.g., $24.99 is represented by 2499).
• referenceValue: reference value of the order in cents (e.g., $24.99 is represented by 2499). This is used for calculating interest, if applicable.
• interestValue: interest value to be applied, if applicable.
• savePersonalData: set as true if the shopper's data provided during checkout should be saved for future reference (default is false).
• optinNewsLetter: set as true if the shopper opted to receive the newsletter (default is false).

Upon receiving a 200 OK response, the request will provide a response body containing the orderForm with comprehensive details of the newly created regular order. Note the following details. Then, proceed to Resolving the order payment.

• orderGroup - ID that groups all orders related to the same purchase. For example, when an order is fulfilled by multiple sellers, each seller has its own order ID (v71021570str-01 and v71021570str-02), but they share the same order group ID (v71021570str).
• transactionId - ID of the transaction, which can be found within an object contained in the merchantTransactions array.

If you encounter errors during the request submission, refer to Handling HTTP response errors when placing the order for common error scenarios when placing an order.

Now, we will communicate the necessary payment data to VTEX to finalize the order payment.

Note that from now on (once Step 2 has been completed), you have 5 minutes to submit the payment information (Step 3) and process the order (Step 4). If Steps 3 and 4 are not completed within 5 minutes, the order will be automatically canceled.

• Send a request to the Send payments information endpoint, considering the following:

  • Use the transactionId value from the previous step as both the path parameter and the value for the id field within the transaction object.
  • Set the merchantName field within the transaction object to your account name.
  • Use the orderId value as a query string parameter. This is the same orderGroup obtained in the previous step.
  • Ensure that the request body is based on the paymentData section of your orderForm.
  • In the fields object, you can:
    • Fill in the credit or debit card information (when applicable).
    • Use the addressId field to reference an existing address, or provide a new address object for an entirely new address. This type of information is only required if the shopper's address was not previously entered during checkout.

This request does not return any data in the response body, only a 201 Created success confirmation message.

In this final step, we will process the order.

• Send a request to the Process order endpoint, using the orderGroup value (which is the orderFormId) as a path parameter.

If the payment is processed without any issues, the order should be successfully placed (204 No Content status). Otherwise, a 500 Internal Server Error message might occur.

Note that this process uses the gateway connectors configured in your VTEX environment. Be careful to prevent any unwanted charges or unexpected payment denials.

Message error example (code ORD002): "Invalid order form"

• Issue: The orderFormId information is not valid.
• Troubleshooting:
  • Verify that the orderFormId is correct.
  • Ensure that the orderFormId corresponds to an existing shopping cart.

Message error example (code CHK0016): "Payment value does not match with reference value"

• Issue: The value and referenceValue fields have different values even when no interest is applied to the payment.
• Troubleshooting:
  • Confirm that the provided value and referenceValue align correctly.
  • Check if the interest rate is correctly configured.

Message error example: "The requested URL was not found on the server"

• Issue: The requested URL was not found on the server.
• Troubleshooting: Check if the endpoint used is correct.

Message error example (code ORD005): "The purchase cannot be done without items"

• Issue: The shopping cart (orderFormId) informed in the request does not have any item, making it impossible to create an order.
• Troubleshooting:
  • Verify that the specified shopping cart has items.
  • Confirm that the orderFormId corresponds to a valid and non-empty shopping cart.