Skip to main content

Updating Merchant Order ID (Optional)

Why Update the Merchant Order ID?​

After a plan has been created, merchants have the flexibility to update the Merchant Order ID. This is useful when the confirmed order identifier was not known when the PlanPay checkout was initiated.

By updating the Merchant Order ID, merchants can accurately associate the plan with the corresponding order in their system, enabling seamless tracking and organization.

info

🚀 Please note that this step is optional.

How it Works​

When requesting a checkout session, merchants can include a temporary or placeholder value in the merchantOrderId field. This makes it possible to proceed with the checkout process before payment has been taken. For example, an identifier for some "on hold" inventory could be used when the PlanPay checkout is initiated, without actually creating a new order.

Once the customer completes the checkout and is redirected back to the designated page, the PlanPay Checkout API can be utilized to query the deposit status, create any required orders (if applicable), and display any relevant messages to the customer, as described in the Checkout Verification Process documentation.

At this point, the merchantOrderId of the plan can be updated with an appropriate order ID. This update ensures accurate tracking of orders within the PlanPay customer and merchant portals, facilitating streamlined post-checkout processes.

Updating the Merchant Order ID​

Below is an example of how to create a PlanPay checkout through an API request. Keep the following in mind:

  • The checkout has been created using the development sandbox endpoint for the checkout API.
  • All required properties have been filled with example data.
  • An Authorization header is included in the request, following the instructions provided in the API keys section.
  • Please note that this is just an example, and many of the properties shown are optional. For a full list of available configurations, see the checkout schema tables.
info

Check out the Authentication and Authorization section to learn how to generate the Authorization header.

Next, let's take a look at an example HTTP request for creating a checkout.

PATCH https://portal.sbx.planpay.com/api/v2/plans/xva42e8c6zhx HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YTFiMmMzZDRlNWY2Om5rbDNxeTd2OXJ4MnN3OG16NWZkMWFqMGM2Z2I0ZXBo

{
  "merchantOrderId": "mycmpny-567-ad82msskgrqk65e5"
}
info

The ID at the end of the above URL is the plan ID, which is returned once a checkout is finalized. It is the same value as the checkout.id as of June 14th, 2023. For older plans, the plan.id value can be found in the response body during the Checkout Verification Process.

The merchantOrderId can be set to any relevant ID of the merchant's choosing.

caution

Make sure to use the PATCH HTTP verb for this request, not POST.

The response will look like the following.

HTTP/1.1 201 OK
Content-Type: application/json

{
  "planId": "xva42e8c6zhx",
  "merchantOrderId": "mycmpny-567-ad82msskgrqk65e5"
}