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.

For more information, access the Get cart information by ID guide.

Place a new order via the Place order from an existing cart endpoint, providing the following information in the request body:

• referenceId: orderFormId obtained in the previous step, serving as the unique identifier (ID) of the orderForm associated with the shopping cart from which the order will be created.
• 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).
• value: total value of the order without separating cents (e.g., $24.99 is represented by 2499).
• referenceValue: reference value of the order, without separating cents (e.g., $24.99 is represented by 2499). This is used for calculating interest, if applicable.
• interestValue: interest rate to be applied, if applicable.

Upon receiving a 201 Created response, the request will provide a response body containing the orderForm with comprehensive details of the newly created regular order. Take note of these pieces of information and proceed to Resolving the order payment.

• orderId - ID of the order within VTEX’s Order Management System (OMS). You can find the orderId within each object in the orders array.
• transactionId - ID of the transaction, which can be found within the objects contained in the transactionData.merchantTransactions array.
• addressId - ID of the customer address. If you plan to use the same address for both shipping and billing, get the addressId from the shippingData.address object.

If you face 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 for the finalization of the order's payment. Note that from now on, you have 5 (five) minutes to complete the payment process.

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

  • Use the orderFormId value obtained in the previous step as the orderId query-string parameter.
  • Use the transactionId value obtained in the previous step as a path parameter.
  • Ensure that the request body is based on the paymentData section of your orderForm.
  • In the fields object, use the addressId field to reference an existing address or introduce a new address object for an entirely new address.

If you intend to send saved credit card data, you can use the Send payments with saved credit card endpoint instead.

In this final step, we will process the order.

• Send a request to the Process order endpoint. If the payment is processed without any issues, the order should be successfully placed. Otherwise, a status 500 error 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 without the use of interest in 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.