v1

latestOpenAPI 3.0.02026-07-246335313.6 KB

Subscription APIs

Create Subscription

Create a Subscription link. In response you will get the Subscription Link reference and the Subscription link URL. You can share the subscription link with your customer. The master merchant can also create the subscription link for their sub-merchants, by passing the sub-merchant key as a header. Refer API docs for additional information.

post/api/subscription/createSubscription

Headers

Content-Typestring

X-Portone-Client-Keystring

The PortOne Key of the merchant

Authorizationstring

The Authorization header is used to include the JWT for authenticating API requests; learn how to generate the token <a href="/docs/jwt-authentication" target="_blank">in this guide</a>

Request body

portone_keystring required

The unique PortOne key for merchant

signature_hashstring required

The signature_hash of subscription generated as per <a href="/docs/regular-subscription" target="_blank">Regular Subscription Request Signature Documentation</a> or <a href="/docs/ondemand-subscription" target="_blank">Ondemand Subscription Request Signature Documentation</a>

merchant_order_refstring required

The unique merchant order reference generated by the merchant

descriptionstring

Product name for the customer's subscription purchase

source'default' | 'api' | 'checkout' required

default, api or checkout -- The Source of creation.

customer_email_addressstring

Email address of the customer

customer_namestring

Name of the customer

customer_phone_numberstring

Phone number of the customer

currencystring required

The currency of the subscription

environment'live' | 'sandbox' required

The environment of transacation either live OR sandbox

notify_by_emailboolean

Specifies if email notifications should be sent

notify_by_phoneboolean

Specifies if phone notifications should be sent

plan_order_refstring required

The reference ID for the plan order

success_urlstring required

The URL to redirect to after a successful subscription

failure_urlstring required

The URL to redirect to after a failed subscription

pending_urlstring required

The URL to redirect to for a pending subscription

subscription_type'REGULAR' | 'ONDEMAND' required

The type of subscription

initial_amountnumber double

The amount of the first deduction, can be a floating-point number. Required only for ONDEMAND Subscription, not available for REGULAR Subscription

first_txn_auto_refundboolean

Indicates whether the first transaction should be auto-refunded. Available only for ONDEMAND Subscription, not available for REGULAR Subscription

allow_accumulate'Y' | 'N'

Indicates whether accumulated payments are allowed. Possible values Y or N. Required only for REGULAR Subscription, not available for ONDEMAND Subscription

quantityinteger

The quantity of the item being subscribed. Required only for REGULAR Subscription, not available for ONDEMAND Subscription

recurrance_countnumber

The number of times the subscription will recur. Required only for REGULAR Subscription, not available for ONDEMAND Subscription

started_atstring

The start date and time of the subscription. Send empty value to start immediately, not available for ONDEMAND Subscription

trial_frequencyinteger

To have a trial set the trial frequency greater than 0. Use either start_date or trial_frequency and trial_period for REGULAR Subscription, not available for ONDEMAND Subscription

trial_period'H' | 'D' | 'W' | 'M' | 'Q' | 'Y'

To have a trial set the trial period. Use either start_date or trial_frequency and trial_period for REGULAR Subscription, not available for ONDEMAND Subscription. Hour trial_period is only for testing purpose

expiry_datestring

The expire date and time of the subscription link

Example request

{
  "portone_key": "<PortoneKey>",
  "signature_hash": "<Genrated signature_hash>",
  "merchant_order_ref": "<Unique merchant_order_ref>",
  "description": "Product name for the customer's subscription purchase",
  "source": "api",
  "quantity": 3,
  "currency": "THB",
  "allow_accumulate": "Y",
  "recurrance_count": 3,
  "plan_order_ref": "2RmeBi6k3mH850nvmRfYfnfADyp",
  "started_at": "2023-06-27T17:30:00.000Z",
  "expiry_date": "2023-06-27T17:30:00.000Z",
  "success_url": "https://subscription.portone.cloud/success.html",
  "failure_url": "https://subscription.portone.cloud/failure.html",
  "pending_url": "https://subscription.portone.cloud/pending.html",
  "subscription_type": "REGULAR"
}

Response

Successful response

is_successboolean

The boolean flag denoting if subscription link was successfully created

merchant_order_refstring

The unique Order reference generated by merchant

order_refstring

The unique subscription link reference stored in PortOnes database

subscription_linkstring

The subscription link generated on PortOne

status_codestring

The status_code for API request execution result