Create a Checkout
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. The meaning of these properties is explained in the Checkout API Schema tables.
- 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.
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.
POST https://portal.sbx.planpay.com/api/v2/checkout HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YTFiMmMzZDRlNWY2Om5rbDNxeTd2OXJ4MnN3OG16NWZkMWFqMGM2Z2I0ZXBo
{
"merchantId": "8b4f37d2e6a1",
"merchantOrderId": "YCPNY-J6P7VZ",
"currencyCode": "AUD",
"redirectURL": "https://www.yourcompany.com/shopping-cart/outcome?saleId=YCPNY-J6P7VZ",
"items": [
{
"sku": "SKU-31789",
"merchantProductURL": "https://www.yourcompany.com/flight/ZX6658",
"quantity": 2,
"description": "Flight ZX6658 - SYD to LAX",
"costPerItem": 100.00,
"minimumDepositPerItem": {
"unit": "currency",
"value": 10.00
},
"depositRefundable": true,
"redemptionDate": "2022-07-31",
"paymentDeadline": 15,
"refundPolicies": [
{
"type": "percentage_refundable_days_within_redemption_date",
"daysWithinRedemptionDate": 20,
"refundablePercentage": 50
},
{
"type": "percentage_refundable_days_within_redemption_date",
"daysWithinRedemptionDate": 30,
"refundablePercentage": 75
},
{
"type": "percentage_refundable_days_within_redemption_date",
"daysWithinRedemptionDate": 60,
"refundablePercentage": 100
}
]
}
]
}
The base URL of the API will vary depending on the environment for the request. In the example above, the .sbx prefix was included in the URL because this was the sandbox environment. For the production environment, use https://portal.planpay.com/api/v2/checkout without the prefix. Make sure to use the correct URL for your environment.
Interpreting the API response and loading the widget
The API responses fall into the following categories.
| Response category | HTTP status | Response body |
|---|---|---|
| Success | 200+ | Checkout object |
| Validation failure | 400+ | Error response |
| Service failure | 500+ | Error response |
If the API response is success or validation failure (i.e., < 500), you SHOULD attempt to display the widget. A simplified response example is shown below.
HTTP/1.1 201 OK
Content-Type: application/json
{
"id": "n1083c79a35b",
// ...other properties
}
The id in the response example above is the unique checkout ID that must be used when loading the checkout widget.
Deposits and refund policies
When a customer books a service or product, the merchant may require a deposit to secure the reservation. In some cases, this deposit may be non-refundable. The refundability of the deposit can be determined by the depositRefundable parameter in the request to create the checkout. In addition to the deposit, the merchant may also define refund policies that determine how much of the total paid amount is refundable in case of a cancellation. This section covers how these two mechanisms interact, and how the applicable refund policy is determined based on the current time and the daysWithinRedemptionDate parameter.
If depositRefundable is false in the request to create the checkout, the non-refundable amount will be whichever is greater, the non-refundable amount from the deposit or the non-refundable amount according to the policy in effect. Any remaining paid amount would be refunded to the customer buy by default, or the merchant can optionally override these settings depending on the scenario.
Suppose a merchant defines the following refund policies:
- Policy A: 75% refundable to customer within 60 days
- Policy B: 50% refundable to customer within 30 days
If a customer requests a refund 40 days before the redemption date, Policy A will be in effect because the current time is within the 60-day window but before the 30 day window. On the other hand, if the customer requests a refund 20 days before the redemption date, Policy B will be in effect because the current time is within the 30-day window. This assumes that the non-refundable amount according to the applicable policy is less than any non-refundable deposit amount.
The applicable policy is always determined based on the smallest daysWithinRedemptionDate that is greater than or equal to the current time.
Refund Policy Schedule
This decision tree shows the refund policy schedule for the scenario described on this page.
Non-Refundable Amount Decision Tree
Learn how to cancel and refund a plan in our training video Processing Cancellations and Refunds.