Checkout Verification Process

When the customer completes or abandons the PlanPay checkout process, the PlanPay widget will redirect the customer's browser to the redirect URL provided by the merchant's website. The redirect URL includes a planpay_checkout_id query-string parameter, which is the unique identifier for the checkout session.

The merchant's website should then perform a verification process to check the deposit status and completion of the checkout. The purpose of this verification is to ensure that inventory is not allocated until the payment has been accepted by PlanPay.

danger

It's important for merchant websites to perform this verification process to prevent malicious users from exploiting the system by securing inventory without payment. The verification process ensures that the payment has been accepted by PlanPay before inventory is allocated.

To perform the verification, the merchant's website should make a back-end API call to the PlanPay Checkout API using their API key. The back-end API call should use the value of the planpay_checkout_id parameter in the redirect URL to populate the {checkoutId} parameter in the API endpoint:

GET https://portal.sbx.planpay.com/api/v2/checkout/n1083c79a35b
Accept: application/json
Authorization: Basic YTFiMmMzZDRlNWY2Om5rbDNxeTd2OXJ4MnN3OG16NWZkMWFqMGM2Z2I0ZXBo

info

The authentication scheme used by the GET Checkout API call is the same as the one used by the Create Checkout API call, and is described under Authentication and Authorization. Make sure to include the Authorization header in your API request.

If the plan.deposit.status property in the API response has a value of Accepted, it means that the payment has been accepted by PlanPay and the merchant can allocate inventory and send notifications to the customer. If the plan.deposit.status is anything other than Accepted, the request may be spurious, and the merchant's website should display an appropriate error message to the customer.

The response would look something like the following:

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

{
  "id": "n1083c79a35b",
  // ...other properties
  "plan": {
    "id": "8j9k6n4b7a2x",
    "deposit": {
      "amount": 21.0,
      "status": "Accepted" // Indicates the deposit status of the checkout
    },
    "instalments": {
      "amount": 272.73,
      "count": 10,
      "cadence": {
        "frequency": "weekly",
        "on": {
          "dayOfWeek": "Monday"
        }
      }
    },
    "currencyCode": "AUD"
  }
}

This is a JSON response that shows the properties returned by the PlanPay API when a successful GET request is made to retrieve the checkout details. The response includes the following information.

Property Name	Explanation
id	The unique identifier of the checkout session.
plan	An object containing details of the plan associated with the checkout.
plan.id	The unique identifier of the plan.
plan.deposit	An object containing details of the deposit payment.
plan.deposit.amount	The amount of the deposit payment.
plan.deposit.status	The status of the deposit payment, which can be either "accepted" or "rejected".
plan.instalments	An object containing details of the instalment payments.
plan.instalments.amount	The amount of each instalment payment.
plan.instalments.count	The number of instalment payments.
plan.instalments.cadence	An object containing details of the instalment payment frequency.
plan.instalments.cadence.frequency	The frequency of the instalment payments, which can be either "weekly" or "fortnightly".
plan.instalments.cadence.on	An object containing details of the instalment payment due date.
plan.instalments.cadence.on.dayOfWeek	The day of the week on which the instalment payments are due.
plan.currencyCode	The currency code of the payment amounts.

tip

Once you have verified the status of the plan, you can go ahead and allocate inventory or any other back-of-house operations that need to be performed.