Getting Started
API Endpoints
- Server To Server
- Tokenization
- Subscriptions
- Wallet
- Hosted Payment Page
Error and Response
Webhook
Create Subscription API
The Create Subscription API allows merchants to set up recurring billing for customers, offering flexible plans with various billing intervals, trials, and discounts.
curl --request POST \
--url https://api-dev.paymentoptions.com/api/v1/api/v1/server-to-server-interface/subscription/payment \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"amount": "1000",
"currency": "JPY",
"card": {
"cvc": "112",
"expiry_month": "12",
"expiry_year": "24",
"name": "John Doe",
"number": "4000000000001091"
},
"payment_method": {
"type": "scheme",
"store_payment_method": false
},
"merchant_txn_ref": "qwe",
"customer_ip": "127.0.0.1",
"merchant_id": "< Merchant ID >",
"return_url": {
"webhook_url": "< Webhook url >",
"success_url": "http://www.successurl.com/",
"decline_url": "http://www.declineurl.com/"
},
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"time_zone": "Asia/Kuala_Lumpur",
"subscription": {
"plan_name": "Three weeks plan",
"plan_desc": "Billed every two days",
"cycle_type": "DAYS",
"subscription_end_type": "CYCLE",
"cycle_interval": 2,
"max_cycle_count": 10,
"has_trial_period": false,
"trial_period_duration_type": "DAYS",
"trial_period_duration": 14,
"has_discount": true,
"discount_percentage": 10,
"discount_duration": 2
}
}'
{
"success": true,
"status_code": 201,
"is_live": false,
"transaction_type": "CAPTURE",
"gateway_response": {
"version": "1",
"type": "INFO",
"message": "Payment Successful.",
"code": "INFO0000"
},
"merchant_details": {
"legal_name": "Beck's Coffee Shop Pvt. Ltd.",
"mid": "JP00000472",
"merchant_txn_ref": "qwe",
"billing_details": {
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
}
},
"device_details": {
"visited_ip": "127.0.0.1",
"merchant_ip": "127.0.0.1",
"customer_ip": "127.0.0.1"
}
},
"payment_details": {
"amount": 900,
"response_code": 0,
"auth_code": "175438",
"currency": "JPY",
"payment_method": "VISA_DEBIT-SSL",
"scheme": "VISA",
"card": {
"name": "John Doe",
"number": "4000000000001091",
"exp_month": "12",
"exp_year": "24"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "359f39bd-673a-47b3-b9ec-cbd6cd313b8e",
"ref": 74860,
"timestamp": "2024-11-26T01:31:29.000Z",
"merchant_txn_ref": "qwe",
"stored_payment_method_id": null
},
"risk-details": {
"risk_score": null
},
"subscription_details": {
"id": "664dc930-88bd-4696-8807-5e0f1fedba0b",
"type": "CYCLE",
"max_cycle_count": 10,
"status": "ACTIVE",
"completed_payment_cycle": 1,
"next_payment_date": "2024-11-28T01:31:29.154Z",
"next_payment_cycle": 2,
"subscription_plan_details": {
"name": "Three weeks plan",
"desc": "Billed every two days",
"billing_cycle_type": "DAYS",
"billing_cycle_interval": 2,
"amount": 1000,
"ccy": "JPY",
"trial_period_duration": "",
"trial_period_duration_type": "NONE",
"plan_discount_percentage": 10,
"plan_discount_duration": 2
}
}
}
Request Example of Subscription Creation
"subscription": {
"plan_name": "<string>",
"plan_desc": "<string>",
"cycle_type": "<DAYS/MONTHS>",
"subscription_end_type": "CYCLE",
"cycle_interval": <int>,
"max_cycle_count": <int>,
"has_trial_period": <boolean>,
"trial_period_duration_type": "DAYS",
"trial_period_duration": <int>,
"has_discount": <boolean>,
"discount_percentage": <int>,
"discount_duration": <int>
}
Key Points
Subscription Creation
- This API enables the setup of subscription plans, allowing for automatic recurring payments. It supports various billing cycles and flexible configurations such as discounts and trial periods.
Subscription Configuration
-
Merchants can define custom plans, including: Plan Name and Description.
-
Cycle Type: Billing can be based on days, weeks, months, etc.
-
Cycle Interval: Defines the frequency of billing (e.g., every 2 days, every month).
-
Max Cycle Count: Sets the maximum number of billing cycles.
-
Trial Period: Option to offer a trial period before the subscription starts.
-
Discounts: Ability to apply discounts for a set number of billing cycles.
Flow diagram
Api Parameters
Authorizations
API Key for Authorization. Format: 'Basic YOUR_API_KEY_HERE'
API Key specific to x-api-key.
Body
Payload for processing subscription payments.
The body is of type object
.
Response
Subscription payment processed successfully.
The response is of type object
.
curl --request POST \
--url https://api-dev.paymentoptions.com/api/v1/api/v1/server-to-server-interface/subscription/payment \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"amount": "1000",
"currency": "JPY",
"card": {
"cvc": "112",
"expiry_month": "12",
"expiry_year": "24",
"name": "John Doe",
"number": "4000000000001091"
},
"payment_method": {
"type": "scheme",
"store_payment_method": false
},
"merchant_txn_ref": "qwe",
"customer_ip": "127.0.0.1",
"merchant_id": "< Merchant ID >",
"return_url": {
"webhook_url": "< Webhook url >",
"success_url": "http://www.successurl.com/",
"decline_url": "http://www.declineurl.com/"
},
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"time_zone": "Asia/Kuala_Lumpur",
"subscription": {
"plan_name": "Three weeks plan",
"plan_desc": "Billed every two days",
"cycle_type": "DAYS",
"subscription_end_type": "CYCLE",
"cycle_interval": 2,
"max_cycle_count": 10,
"has_trial_period": false,
"trial_period_duration_type": "DAYS",
"trial_period_duration": 14,
"has_discount": true,
"discount_percentage": 10,
"discount_duration": 2
}
}'
{
"success": true,
"status_code": 201,
"is_live": false,
"transaction_type": "CAPTURE",
"gateway_response": {
"version": "1",
"type": "INFO",
"message": "Payment Successful.",
"code": "INFO0000"
},
"merchant_details": {
"legal_name": "Beck's Coffee Shop Pvt. Ltd.",
"mid": "JP00000472",
"merchant_txn_ref": "qwe",
"billing_details": {
"billing_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
},
"shipping_address": {
"country": "JP",
"email": "billing@testemail.com",
"phone_number": "8112345678",
"address1": "1-2-3 Shinjuku",
"city": "Shinjuku-ku",
"state": "Tokyo",
"postal_code": "1600022"
}
},
"device_details": {
"visited_ip": "127.0.0.1",
"merchant_ip": "127.0.0.1",
"customer_ip": "127.0.0.1"
}
},
"payment_details": {
"amount": 900,
"response_code": 0,
"auth_code": "175438",
"currency": "JPY",
"payment_method": "VISA_DEBIT-SSL",
"scheme": "VISA",
"card": {
"name": "John Doe",
"number": "4000000000001091",
"exp_month": "12",
"exp_year": "24"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "359f39bd-673a-47b3-b9ec-cbd6cd313b8e",
"ref": 74860,
"timestamp": "2024-11-26T01:31:29.000Z",
"merchant_txn_ref": "qwe",
"stored_payment_method_id": null
},
"risk-details": {
"risk_score": null
},
"subscription_details": {
"id": "664dc930-88bd-4696-8807-5e0f1fedba0b",
"type": "CYCLE",
"max_cycle_count": 10,
"status": "ACTIVE",
"completed_payment_cycle": 1,
"next_payment_date": "2024-11-28T01:31:29.154Z",
"next_payment_cycle": 2,
"subscription_plan_details": {
"name": "Three weeks plan",
"desc": "Billed every two days",
"billing_cycle_type": "DAYS",
"billing_cycle_interval": 2,
"amount": 1000,
"ccy": "JPY",
"trial_period_duration": "",
"trial_period_duration_type": "NONE",
"plan_discount_percentage": 10,
"plan_discount_duration": 2
}
}
}