Creating an On-Demand Plan

This document provides a comprehensive guide for creating an On-Demand Plan using the PortOne API. An On-Demand Plan allows merchants to charge customers based on their usage or activity without fixed intervals.

API Endpoint

POST https://api.portone.cloud/api/subscription/createPlan

Headers

Header	Type	Required	Description
`Content-Type`	string	Yes	Set to `application/json`.
`X-Portone-Client-Key`	string	Yes	The unique PortOne key for the merchant.
`Authorization`	string	Yes	JWT for authenticating API requests. Learn how to generate the token here.

Request Body Parameters

Below are the required and optional parameters for creating an On-Demand Plan:

General Parameters

Parameter	Type	Required	Description
`portone_key`	string	Yes	The unique PortOne key for the merchant.
`signature_hash`	string	Yes	Signature hash generated as per On-Demand Plan Request Signature Documentation.
`merchant_order_ref`	string	Yes	The unique merchant order reference generated by the merchant.
`source`	string	Yes	The source of plan creation: `default`, `api`, or `checkout`.
`description`	string	No	A description of the plan.
`environment`	string	Yes	Plan environment, either `live` or `sandbox`.
`name`	string	Yes	Name of the plan.
`notes`	array of objects	No	Additional notes related to the plan.

On-Demand Plan-Specific Parameters

Parameter	Type	Required	Description
`currency`	string	Yes	Currency of the plan (e.g., `USD`).
`plan_type`	string	Yes	Type of plan. Set to `ONDEMAND`.

Request Example

On-Demand Plan Request

Request Body:

{
  "portone_key": "PORTONE_KEY",
  "signature_hash": "GENERATED_SIGNATURE",
  "merchant_order_ref": "MerchantRef12345",
  "source": "api",
  "description": "Pay-As-You-Go Subscription Plan",
  "environment": "live",
  "name": "On-Demand Plan",
  "notes": [
    {
      "key": "Plan Note",
      "value": "This is a flexible plan for on-demand usage."
    }
  ],
  "currency": "USD",
  "plan_type": "ONDEMAND"
}

Response

Success Response

{
  "status": "success",
  "message": "Plan created successfully.",
  "data": {
    "plan_id": "Plan12345",
    "name": "On-Demand Plan",
    "type": "ONDEMAND",
    "currency": "USD",
    "environment": "live",
    "created_at": "2024-11-21T10:00:00Z"
  }
}

Error Response

{
  "status": "error",
  "message": "Invalid signature_hash.",
  "error_code": 401
}

Signature Hash Generation

To ensure the authenticity of the request, generate the signature_hash by following the On-Demand Plan Request Signature Documentation.

Steps for Generating the Signature

Concatenate the required parameters (currency, merchant_order_ref) into a single string in alphabetical order.
Calculate the SHA-256 hash of the resulting string.
Base64-encode the hash to obtain the signature_hash.

Best Practices

Environment Selection: Use sandbox for testing and live for production.
Validation: Ensure all required fields are correctly validated before sending the request.
Testing: Test your API integration in the sandbox environment before moving to production.
Secure API Keys: Never expose your portone_key or authorization tokens publicly.
Monitor Responses: Regularly monitor API responses to ensure the correct plan creation.

Key Notes

Regular Plans: Suitable for fixed recurring payments like subscriptions or memberships.
Frequency and Period: Ensure the values align with the intended billing cycle.
Descriptive Details: Use descriptive names and notes for easier plan management and tracking.

This document serves as a comprehensive guide to creating Regular Plans with the PortOne API. Let me know if additional details or sections are needed!