Creating a Regular Subscription

This document provides a comprehensive guide for creating a Regular Subscription using the PortOne API. Merchants can generate subscription links and share them with customers to process subscriptions seamlessly.

Steps to Create a Regular Subscription

1. Setup API Credentials: Ensure you have your PortOne Key, Secret Key, and JWT Token ready for authentication.
2. Create Payload: Prepare the JSON request body with all required parameters.
3. Generate Signature Hash: Generate the signature_hash as per the Signature Documentation.
4. Send API Request: Use the API endpoint with the prepared payload.
5. Handle API Response: Handle the response to retrieve the subscription link and its status.

API Endpoint

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

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": "Subscription_1729672233761",
  "source": "api",
  "customer_email_address": "[email protected]",
  "customer_name": "NGUYEN VAN A",
  "customer_phone_number": "+919876543210",
  "description": "Product name for the customer's subscription purchase",
  "quantity": 1,
  "currency": "USD",
  "country_code": "US",
  "environment": "sandbox",
  "allow_accumulate": "Y",
  "recurrance_count": 3,
  "notify_by_email": false,
  "notify_by_phone": false,
  "plan_order_ref": "2nsJNracNOB6mzJ4elECMmnOlu2",
  "subscription_type": "REGULAR",
  "notes": [
    { "key": "special_instructions", "value": "Deliver between 9-11 AM" },
    { "key": "gift_wrap", "value": "Yes" }
  ],
  "additional_costs": [
    { "key": "tax", "value": 50 },
    { "key": "shipping", "value": 25 }
  ],
  "started_at": "",
  "trial_frequency": 7,
  "trial_period": "D",
  "success_url": "https://subscription.portone.cloud/success.html",
  "failure_url": "https://subscription.portone.cloud/failure.html",
  "pending_url": "https://subscription.portone.cloud/pending.html"
}

Request Body Parameters

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

General Parameters

portone_key

string · required

The unique PortOne key for the merchant.

signature_hash

string · required

Signature hash generated as per Regular Subscription Request Signature Documentation.

merchant_order_ref

string · required

The unique merchant order reference generated by the merchant.

description

string

Product name for the customer's subscription purchase.

source

string · required

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

customer_email_address

string

Email address of the customer.

customer_name

string

Name of the customer.

customer_phone_number

string

Phone number of the customer in international format (e.g., +91XXXXXXXXXX).

currency

string · required

The currency of the subscription (e.g., USD).

environment

string · required

Environment of the transaction, either sandbox or live.

notify_by_email

boolean

Specifies if email notifications should be sent (true/false).

notify_by_phone

boolean

Specifies if phone notifications should be sent (true/false).

plan_order_ref

string · required

The reference ID for the plan order.

success_url

string · required

The URL to redirect to after a successful subscription.

failure_url

string · required

The URL to redirect to after a failed subscription.

pending_url

string · required

The URL to redirect to for a pending subscription.

Regular Subscription-Specific Parameters

subscription_type

string · required

The type of subscription. Set to REGULAR.

allow_accumulate

string · required

Indicates whether accumulated payments are allowed (Y or N).

quantity

integer · required

The quantity of the item being subscribed.

recurrance_count

integer · required

The number of times the subscription will recur.

expiry_date

string

The expiration date and time of the subscription link.

started_at

string

The start date and time of the subscription in ISO format, or empty for immediate start.

trial_period

string

Defines the duration type of the trial (e.g., D for daily, W for weekly).

Explaining the trial_period field with examples below:
D (Days): A trial_period of D means the trial duration is counted in days.
W (Weeks): A trial_period of W means the trial duration is counted in weeks.
M (Months): A trial_period of M means the trial duration is counted in months.
Y (Years): A trial_period of Y means the trial duration is counted in years.

For example:
If trial_period is W, the trial duration is specified in weeks.
If trial_period is M, the trial duration is specified in months.

trial_frequency

integer

Specifies the number of units for the trial period.

Explaining the trial_frequency and trial_period fields with examples below:
If trial_frequency is 7 and trial_period is D, the trial lasts 7 days.
If trial_frequency is 2 and trial_period is W, the trial lasts 2 week.
If trial_frequency is 1 and trial_period is M, the trial lasts 1 months.

notes

array of objects

additional_costs

array of objects

Response

Success Response

{
  "is_success": true,
  "merchant_order_ref": "Subscription_1729672233761",
  "order_ref": "2nsJNracNOB6mzJ4elECMmnOlu2",
  "subscription_link": "https://subscription.portone.cloud/?ref=2nsJNracNOB6mzJ4elECMmnOlu2",
  "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: Validate all required fields before sending the request.

This document serves as a comprehensive guide to creating Regular Subscriptions using the PortOne API.