Creating a Regular Plan

This document provides a comprehensive guide for creating a Regular Plan using the PortOne API. A Regular Plan allows merchants to set up fixed recurring payments for their customers at regular 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 a Regular 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 Regular 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.

Regular 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 `REGULAR`.
`amount`	double	Yes	The fixed recurring amount.
`frequency`	integer	Yes	The billing frequency (e.g., `1` , `30`).
`period`	string	Yes	Period of the plan (e.g., `D` for daily, `M` for monthly).

Request Example

Regular Plan Request

Request Body:

{
  "portone_key": "PORTONE_KEY",
  "signature_hash": "GENERATED_SIGNATURE",
  "merchant_order_ref": "MerchantRef12345",
  "source": "api",
  "description": "Premium Monthly Subscription Plan",
  "environment": "live",
  "name": "Premium Monthly Plan",
  "notes": [
    {
      "key": "Plan Note",
      "value": "This is a premium plan."
    }
  ],
  "currency": "USD",
  "plan_type": "REGULAR",
  "amount": 100.50,
  "frequency": 30,
  "period": "M"
}

Response

Success Response

{
  "status": "success",
  "message": "Plan created successfully.",
  "data": {
    "plan_id": "Plan12345",
    "name": "Premium Monthly Plan",
    "type": "REGULAR",
    "amount": 100.50,
    "currency": "USD",
    "frequency": 30,
    "period": "M",
    "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 Regular Plan Request Signature Documentation.

Steps for Generating the Signature

Concatenate the required parameters (amount, currency, frequency, 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!