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.

Prerequisites

Signature Hash Generation

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

API Endpoint

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

Headers

Content-Type

string · required

Set to application/json.

X-Portone-Client-Key

string · required

The unique PortOne key for the merchant.

Authorization

string · required

JWT for authenticating API requests. Learn how to generate the token here.

Request Example

Request Body:

{
  "portone_key": "PORTONE_KEY",
  "merchant_order_ref": "Plan_1729672233765",
  "source": "api",
  "amount": 1000,
  "currency": "USD",
  "name": "1000 USD per month",
  "description": "1000 USD per month",
  "environment": "sandbox",
  "frequency": 1,
  "period": "M",
  "plan_type": "REGULAR",
  "notes": [
    { "key": "key1", "value": "value1" },
    { "key": "key2", "value": "value2" }
  ]
}

Request Body Parameters

Below are the required and optional parameters for creating a Regular Plan:

General Parameters

portone_key

string · required

The unique PortOne key for the merchant.

signature_hash

string · required

Signature hash generated as per Regular Plan Request Signature Documentation.

merchant_order_ref

string · required

The unique merchant order reference generated by the merchant.

source

string · required

The source of plan creation: default, api, or checkout.

description

string · required

A description of the plan.

environment

string · required

Plan environment, either live or sandbox.

name

string · required

Name of the plan.

notes

array of objects

Regular Plan-Specific Parameters

currency

string · requiredCurrency of the plan (e.g., USD).

plan_type

string · required

Type of plan. Set to REGULAR.

amount

double · required

The fixed recurring amount.

frequency

integer · required

Explaining the frequency and period fields with examples below:
W (Weeks): A period of W means each step is in weeks.
M (Months): A period of M means each step is in months.
Q (Quarters): A period of Q means each step is in quarters (3-month periods).
Y (Years): A period of Y means each step is in years.
The frequency number indicates how often the event will occur within the specified period.
For example:
If frequency is 2 and period is W, the event will happen every 2 weeks.
If frequency is 3 and period is M, the event will happen every 3 months.

period

string · required

Period of the plan (e.g., D for daily, M for monthly).

Explaining the frequency and period fields with examples below:
W (Weeks): A period of W means each step is in weeks.
M (Months): A period of M means each step is in months.
Q (Quarters): A period of Q means each step is in quarters (3-month periods).
Y (Years): A period of Y means each step is in years.
The frequency number indicates how often the event will occur within the specified period.
For example:
If frequency is 2 and period is W, the event will happen every 2 weeks.
If frequency is 3 and period is M, the event will happen every 3 months.

Response

Success Response

{
  "merchant_order_ref": "MerchantOrder12345",
  "order_ref": "PortOneOrder12345",
  "status_code": "200"
}

Error Response

{
  "is_success": false,
  "message": "The API request failed due to invalid parameters.",
  "status_code": "400",
  "status_reason": "Bad Request"
}

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.

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.