openapi: 3.0.0
info:
title: Subscription APIs
version: 1.0.0
servers:
- url: https://api.portone.cloud
tags:
- name: Plan APIs
- name: Subscription APIs
paths:
/api/subscription/createPlan:
post:
tags:
- Plan APIs
summary: Create Plan
description: |-
Use this API for Creating Plan.
requestBody:
content:
application/json:
schema:
properties:
portone_key:
description: The unique PortOne key for merchant
type: string
signature_hash:
description: The signature_hash of plan generated as per <a href="/docs/regular-plan" target="_blank">Regular Plan Request Signature Documentation</a> or <a href="/docs/ondemand-plan" target="_blank">Ondemand Plan Request Signature Documentation</a>
type: string
merchant_order_ref:
description: The unique merchant order reference generated by the merchant
type: string
source:
description: default, api or checkout -- The Source of Plan creation.
type: string
enum: [default, api, checkout]
description:
description: The description of the plan
type: string
environment:
description: The environment of plan. Either live OR sandbox
type: string
enum: [live, sandbox]
name:
description: The name of the plan
type: string
notes:
$ref: '#/components/schemas/Notes'
currency:
description: The currency of the plan
type: string
plan_type:
description: The type of plan
type: string
enum: [REGULAR, ONDEMAND]
amount:
description: The amount of the plan, can be a floating-point number. Required only for REGULAR Plan, not available for ONDEMAND Plan
type: number
format: double
frequency:
description: The frequency of the plan (must be greater than 0). Required only for REGULAR Plan, not available for ONDEMAND Plan
type: integer
minimum: 1
period:
description: The period of the plan. Required only for REGULAR Plan, not available for ONDEMAND Plan. Hour period is only for testing purpose.
type: string
enum: [H, D, W, M, Q, Y]
type: object
required:
- portone_key
- signature_hash
- merchant_order_ref
- source
- currency
- environment
- name
- plan_type
example:
portone_key: <PortoneKey>
signature_hash: <Genrated signature_hash>
merchant_order_ref: <Unique merchant_order_ref>
source: api
amount: 100
currency: THB
description: Testing
environment: sandbox
frequency: 1
period: M
name: 100 THB Monthly
plan_type: REGULAR
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
merchant_order_ref:
description: The unique Order reference generated by merchant
type: string
order_ref:
description: The unique Order reference generated by PortOne
type: string
status_code:
description: The status_code for API request execution result
type: string
example: |-
{
"merchant_order_ref": "Plan1687858378574",
"order_ref": "2Rmbp9g8JzQOxur5ATfLV68AryT",
"status_code": "2000"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "false",
"message": "frequency is a required field",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/plan/{orderRef}/status/{status}:
put:
tags:
- Plan APIs
summary: Cancel Plan
description: |-
Use this API for Cancelling Plan.
requestBody:
content: {}
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
- name: orderRef
in: path
schema:
type: string
required: true
example: 2RmOL3Tr9qZzB6P3lZIRRJzrMhJ
- name: status
in: path
schema:
type: string
required: true
example: cancelled
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"message": "Plan status updated successfully to cancelled",
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"message": "Plan does not exist with this order ref",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/plan/{orderRef}:
get:
tags:
- Plan APIs
summary: Get Plan
description: |-
Use this API for fetching Plan.
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
- name: orderRef
in: path
schema:
type: string
required: true
example: 2RmOL3Tr9qZzB6P3lZIRRJzrMhJ
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
content:
$ref: '#/components/schemas/PlanContent'
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"content": {
"amount": 1000,
"portone_key": "NPSkZZYefGyKvBxi",
"currency": "THB",
"description": "Testing",
"environment": "sandbox",
"frequency": 1,
"merchant_order_ref": "Plan1687859548746",
"name": "1000 THB Monthly",
"notes": [
{
"key": "test",
"value": "abc"
},
{
"key": "test1",
"value": "abc"
}
],
"order_ref": "2RmeBi6k3mH850nvmRfYfnfADyp",
"period": "M",
"is_active": true,
"plan_type": "REGULAR"
},
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"message": "Plan does not exist with this order ref",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/createSubscription:
post:
tags:
- Subscription APIs
summary: Create Subscription
description: |-
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.
requestBody:
content:
application/json:
schema:
properties:
portone_key:
description: The unique PortOne key for merchant
type: string
signature_hash:
description: 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>
type: string
merchant_order_ref:
description: The unique merchant order reference generated by the merchant
type: string
description:
description: Product name for the customer's subscription purchase
type: string
source:
description: default, api or checkout -- The Source of creation.
type: string
enum: [default, api, checkout]
customer_email_address:
description: Email address of the customer
type: string
customer_name:
description: Name of the customer
type: string
customer_phone_number:
description: Phone number of the customer
type: string
currency:
description: The currency of the subscription
type: string
environment:
description: The environment of transacation either live OR sandbox
type: string
enum: [live, sandbox]
notify_by_email:
type: boolean
description: Specifies if email notifications should be sent
notify_by_phone:
type: boolean
description: Specifies if phone notifications should be sent
plan_order_ref:
type: string
description: The reference ID for the plan order
notes:
$ref: '#/components/schemas/Notes'
additional_costs:
$ref: '#/components/schemas/AdditionalCost'
success_url:
type: string
description: The URL to redirect to after a successful subscription
failure_url:
type: string
description: The URL to redirect to after a failed subscription
pending_url:
type: string
description: The URL to redirect to for a pending subscription
subscription_type:
type: string
description: The type of subscription
enum: [REGULAR, ONDEMAND]
initial_amount:
description: The amount of the first deduction, can be a floating-point number. Required only for ONDEMAND Subscription, not available for REGULAR Subscription
type: number
format: double
minimum: 1
allow_accumulate:
description: Indicates whether accumulated payments are allowed. Possible values Y or N. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
type: string
enum: [Y, N]
quantity:
description: The quantity of the item being subscribed. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
type: integer
minimum: 1
recurrance_count:
description: The number of times the subscription will recur. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
type: number
minimum: 1
started_at:
type: string
description: The start date and time of the subscription. Send empty value to start immediately, not available for ONDEMAND Subscription
trial_frequency:
description: 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
type: integer
minimum: 1
trial_period:
description: 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
type: string
enum: [H, D, W, M, Q, Y]
expiry_date:
type: string
description: The expire date and time of the subscription link
type: object
required:
- portone_key
- signature_hash
- merchant_order_ref
- source
- currency
- environment
- plan_order_ref
- success_url
- failure_url
- pending_url
- subscription_type
example:
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
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting if subscription link was successfully created
type: boolean
merchant_order_ref:
description: The unique Order reference generated by merchant
type: string
order_ref:
description: The unique subscription link reference stored in PortOnes database
type: string
subscription_link:
description: The subscription link generated on PortOne
type: string
status_code:
description: The status_code for API request execution result
type: string
example: |-
{
"is_success": "true",
"merchant_order_ref": "Subscription_1687863670647",
"order_ref": "2RmmXauKYyPl58ZRdmbSu9KyjdU",
"status_code": "2000",
"subscription_link": "https://subscription.portone.cloud/?ref=2RmmXauKYyPl58ZRdmbSu9KyjdU"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "false",
"message": "Allow Accumulate must be Y or N only",
"status_code": "4086",
"status_reason": "INVALID_QUANTITY"
}
/api/subscription/createDeduction:
post:
tags:
- Subscription APIs
summary: Create Ondemand Deduction
description: |-
Use this API for Creating Ondemand Deduction.
requestBody:
content:
application/json:
schema:
properties:
portone_key:
description: The unique PortOne key for merchant
type: string
signature_hash:
description: The signature_hash of ondemand deduction generated as per <a href="/docs/ondemand-deduction" target="_blank">Ondemand Deduction Request Signature Documentation</a>
type: string
merchant_order_ref:
description: The unique merchant order reference generated by the merchant
type: string
subscription_order_ref:
description: The unique subscription order reference of the subscription link
type: string
description:
description: Product name for the customer's subscription purchase
type: string
source:
description: default, api or checkout -- The Source of creation.
type: string
enum: [api, checkout]
amount:
description: The amount of deduction, can be a floating-point number
type: number
format: double
currency:
description: The currency of the subscription
type: string
environment:
description: The environment of transacation either live OR sandbox
type: string
enum: [live, sandbox]
type: object
required:
- portone_key
- signature_hash
- merchant_order_ref
- subscription_order_ref
- source
- currency
- amount
- environment
example:
portone_key: <PortoneKey>
signature_hash: <Genrated signature_hash>
merchant_order_ref: <Unique merchant_order_ref>
subscription_order_ref: <Unique subscription_order_ref>
description: Product name for the customer's subscription purchase
source: api
amount: 10
currency: THB
subscription_type: ONDEMAND
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting if subscription ondemand deduction was successfully created
type: boolean
merchant_order_ref:
description: The unique Order reference generated by merchant
type: string
order_ref:
description: The unique transaction reference stored in PortOnes database
type: string
status_code:
description: The status_code for API request execution result
type: string
status:
description: The status for the ondemand deduction result
type: string
example: |-
{
"is_success": "true",
"merchant_order_ref": "Subscription_1687863670647",
"order_ref": "2RmmXauKYyPl58ZRdmbSu9KyjdU",
"status_code": "2000",
"status": "Initiated"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "false",
"message": "",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/triggerNextDeduction:
put:
tags:
- Subscription APIs
summary: Trigger Next Deduction
description: |-
Use this API to trigger the next deduction for a regular subscription.
requestBody:
content:
application/json:
schema:
properties:
portone_key:
description: The unique PortOne key for merchant
type: string
subscription_order_ref:
description: The unique subscription order reference of the subscription link
type: string
environment:
description: The environment of the transaction either live OR sandbox
type: string
enum: [sandbox, live]
type: object
required:
- portone_key
- subscription_order_ref
- environment
example:
portone_key: gvFFggsdgGfrshuh
subscription_order_ref: 2rIbzBBpNjUH681AmQilntIzz3b
environment: sandbox
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting if the next deduction was successfully triggered
type: boolean
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "true",
"message": "The next deduction should happen shortly",
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "false",
"message": "Invalid request parameters",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/{orderRef}:
get:
tags:
- Subscription APIs
summary: Get Subscription
description: |-
Use this API for fetching Subscription.
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
- name: orderRef
in: path
schema:
type: string
required: true
example: 2RmOVbktKab2SjUa5sAr5xkPoct
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
content:
$ref: '#/components/schemas/SubscriptionContent'
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"content": {
"additional_costs": [
{
"key": "test",
"value": 5
},
{
"key": "test1",
"value": 5
}
],
"allow_accumulate": "Y",
"portone_key": "NPSkZZYefGyKvBxi",
"created_at": "2023-06-27T11:32:57.073143Z",
"currency": "THB",
"country_code": "",
"customer_email_address": "test@test.com",
"customer_name": "test2",
"customer_phone_number": "8947594533",
"environment": "sandbox",
"expired_at": "2023-07-27T11:32:57.071477Z",
"merchant_order_ref": "Subscription_1687865574692",
"notes": [
{
"key": "test",
"value": "abc"
},
{
"key": "test1",
"value": "abc"
},
{
"key": "test",
"value": "payment payment payment"
}
],
"notify_by_email": false,
"notify_by_phone": false,
"plan_order_ref": "2RmeBi6k3mH850nvmRfYfnfADyp",
"quantity": 3,
"recurrance_count": 3,
"signature_hash": "",
"source": "api",
"started_at": "2023-06-27T11:32:57.071477Z",
"status": "Created",
"subscription_type":"REGULAR",
"total_amount": 9010,
"plan_amount": 1000,
"collected_amount": 0,
"total_additional_cost": 10,
"next_deduction_amount": 0,
"next_deduction_date": null,
"collected_count": 0,
"trial_frequency": 7,
"trial_period": "D",
"in_trial": false
},
"is_success": "true",
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"message": "Subscription does not exist with this order ref",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/{orderRef}/txns-records:
get:
tags:
- Subscription APIs
summary: Get Subscription Link Transaction Details
description: |-
Use this API for fetching Subscription Link Transaction Details
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
- name: orderRef
in: path
schema:
type: string
required: true
example: 2RmOVbktKab2SjUa5sAr5xkPoct
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: boolean
content:
type: array
items:
$ref: '#/components/schemas/TxnContent'
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"content": [
{
"amount": 20000,
"channel_name": "ONEPAY",
"channel_order_ref": "PAY-AUFHX6QDG6D5YW3R",
"created_at": "2024-03-11T05:37:34.902388Z",
"currency": "VND",
"merchant_order_ref": "2Vij79pz49Xs9a7IQqFnySO37xI_NpxZA",
"method_key": "ONEPAY_SUBSCRIPTION_CARD",
"order_ref": "2Vij79pz49Xs9a7IQqFnySO37xI_NpxZA",
"payment_method_used": "",
"refund_status": "",
"status": "Failed"
},
{
"amount": 20000,
"channel_name": "ONEPAY",
"channel_order_ref": "PAY-_LNNH5aRScCgsmrG9rOYYg",
"created_at": "2024-04-11T05:37:34.902388Z",
"currency": "VND",
"merchant_order_ref": "2Vij79pz49Xs9a7IQqFnySO37xI_ciUQP",
"method_key": "ONEPAY_SUBSCRIPTION_CARD",
"order_ref": "2Vij79pz49Xs9a7IQqFnySO37xI_ciUQP",
"payment_method_used": "",
"refund_status": "",
"status": "Success"
}
],
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"message": "Subscription does not exist with this order ref",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
/api/subscription/{orderRef}/status/{status}:
put:
tags:
- Subscription APIs
summary: Cancel Subscription
description: |-
Use this API for Cancelling Subscription.
requestBody:
content: {}
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: X-Portone-Client-Key
in: header
description: The PortOne Key of the merchant
schema:
type: string
example: 'gvFFggsdgGfrshuh'
- name: Authorization
in: header
description: 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>
schema:
type: string
example: >-
Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjI2NDk3NjU5MDEsImlhdCI6MTY0OTc2NTkwMSwiaXNzIjoiQ0hBSVBBWSIsInN1YiI6Ik5QU2taWlllZkd5S3ZCeGkifQ.VHicuV4dvfp8skktlcRVJNS_WwsD_MtKB4JLBbLWOcQ
- name: orderRef
in: path
schema:
type: string
required: true
example: 2RmOVbktKab2SjUa5sAr5xkPoct
- name: status
in: path
schema:
type: string
required: true
example: cancelled
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: string
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "true",
"message": "Subscription status updated successfully to cancelled",
"status_code": "2000",
"status_reason": "SUCCESS"
}
'400':
description: Failure response
content:
application/json:
schema:
properties:
is_success:
description: The boolean flag denoting API request execution result
type: string
message:
description: The description of the API request execution result
type: string
status_code:
description: The status_code for API request execution result
type: string
status_reason:
description: The status_reason for API request execution result
type: string
example: |-
{
"is_success": "false",
"message": "Subscription does not exist with this order ref",
"status_code": "4001",
"status_reason": "INVALID_REQUEST"
}
components:
schemas:
Notes:
title: Additional Notes
description: Additional Notes
type: array
items:
type: object
properties:
key:
type: string
description: Title
value:
type: string
description: Description
PlanContent:
title: PlanContent
type: object
description: The meta details of the plan
properties:
amount:
description: The amount of the plan, can be a floating-point number
type: number
format: double
portone_key:
description: The unique PortOne key for merchant
type: string
currency:
description: The currency of the plan
type: string
description:
description: The description of the plan
type: string
environment:
description: The environment of plan either live OR sandbox
type: string
frequency:
description: The frequency of the plan (must be greater than 0)
type: integer
minimum: 1
name:
description: The name of the plan
type: string
merchant_order_ref:
description: The unique merchant order reference generated by the merchant
type: string
notes:
$ref: '#/components/schemas/Notes'
plan_type:
description: The type of plan
type: string
order_ref:
description: The unique Order reference generated by PortOne
type: string
period:
description: The period of the plan
type: string
is_active:
description: The boolean flag denoting active status of Plan
type: boolean
AdditionalCost:
title: Additional Cost. Optional for REGULAR Subscription, not available for ONDEMAND Subscription
description: Additional Cost. Optional for REGULAR Subscription, not available for ONDEMAND Subscription
type: array
items:
type: object
properties:
key:
type: string
description: Type of cost
value:
type: number
description: Amount
format: double
TxnContent:
title: Transactions
type: object
description: The JSON object containing the transactions of the subscription
properties:
amount:
description: The amount of transaction, can be a floating-point number
type: number
format: double
channel_name:
type: string
description: The key of the Payment Channel. Refer PortOne docs for more details
channel_order_ref:
type: string
description: The unique order reference of the transaction generated by PSP
currency:
type: string
description: The currency of transaction
merchant_order_ref:
type: string
description: The unique merchant order reference for the transaction
order_ref:
type: string
description: The unique transaction reference generated by PortOne
method_key:
type: string
description: The Payment Method Key used for the transaction
payment_method_used:
type: string
description: The payment method used
refund_status:
type: string
description: The refund status.
created_at:
type: string
description: The timestamp of when the transaction was created
status:
type: string
description: The status of the transaction.
SubscriptionContent:
title: SubscriptionContent
type: object
description: The meta details of the subscription
properties:
additional_costs:
$ref: '#/components/schemas/AdditionalCost'
allow_accumulate:
description: Indicates whether accumulated payments are allowed. Possible values Y or N
type: string
portone_key:
description: The unique PortOne key for merchant
type: string
created_at:
type: string
description: The creation date and time of the subscription
currency:
description: The currency of the subscription
type: string
country_code:
description: Country code associated with subscription
type: string
customer_email_address:
description: Email address of the customer
type: string
customer_name:
description: Name of the customer
type: string
customer_phone_number:
description: Phone number of the customer
type: string
environment:
description: The environment of transacation either live OR sandbox
type: string
expired_at:
type: string
description: The expire date and time of the subscription link
merchant_order_ref:
description: The unique merchant order reference generated by the merchant
type: string
notes:
$ref: '#/components/schemas/Notes'
notify_by_email:
type: boolean
description: Specifies if email notifications should be sent
notify_by_phone:
type: boolean
description: Specifies if phone notifications should be sent
plan_order_ref:
type: string
description: The reference ID for the plan
quantity:
description: The quantity of the item being subscribed
type: integer
minimum: 1
recurrance_count:
description: The number of times the subscription will recur
type: number
source:
description: The Source of creation.
type: string
started_at:
type: string
description: The start date and time of the subscription
status:
type: string
description: The status of the subscription link
subscription_type:
type: string
description: The type of subscription
total_amount:
type: number
format: double
description: The total amount of the subscription. Applicable only for REGULAR Subscription
plan_amount:
type: number
format: double
description: The amount of the plan. Applicable only for REGULAR Subscription
collected_amount:
type: number
format: double
description: The total amount collected till now
total_additional_cost:
type: number
format: double
description: The total additional cost of the subscription. Optional for REGULAR Subscription, not available for ONDEMAND Subscription
next_deduction_amount:
type: number
format: double
description: The amount for the next deduction
next_deduction_date:
type: string
description: The date for the next deduction
collected_count:
type: string
description: The number of times the amount has been collected
trial_frequency:
description: Frequency configured for the trial duration
type: integer
trial_period:
description: Period configured for the trial duration
type: string
in_trial:
type: boolean
description: Indicates whether the subscription is currently in the trial phase
