Subscribe
POST/v1/subscription/create
Create a subscription
Request
- application/json
Body
required
Array [
Array [
]
]
non-empty
The id of this subscription you define.
<= 64 characters
The id of the merchant id.
non-empty
The id of the sub-merchant (e.g., merchant application id), used to identify sub-merchant accounts under the main merchant.
subscriber
object
Subscriber
non-empty and <= 64 characters
The id of the subscriber.
The midas login id (muid) of the subscriber. Apply only to midasbuy.
The name of the subscriber.
The email of the subscriber.
The ip of the subscriber.
The phone number of the subscriber.
address
object
Address of payer or payee
country (eg. CN) -- use region_code instead
<= 100 characters
ISO 3166-2 define
city
county
region code
street name
house info
<= 100 characters
address postal code
subscription_units
object[]
>= 1
The subscription unit of this subscription. You can customize the behavior of this subscription, such as free trial, discount trial etc. It is also supported customizing the execution sequence of these units.
product
object
Product
non-empty
The id of the product.
The name of the product.
The description of the product.
[UNKNOWN, REGULAR, PROMOTIONAL]
Indicates whether the unit is regular or promotional (e.g., free trial, discount). Rules: - There must be at most one regular unit per subscription, and it must be the last element in the units array. - Only regular units can have total_cycles set to 0, indicating infinite cycles. - Promotional units must have total_cycles set to a finite value (1 to 999).
period
object
Period value multiply period unit equals the duration of subscription unit. If period.period_unit = MONTH, it represents a calendar (natural) month. For example, a period starting on Jan 31 will renew on Feb 28/29. If a fixed-length period like "31 days" is desired instead of a natural month, use period.period_unit = DAY and period.value = 31.
[UNKNOWN, DAY, MONTH, YEAR]
Period unit.
The number of period unit. When using DAY as the period unit, the value must be at least 7 (i.e., value >= 7).
The order in which this unit is to run among other subscription units. For example, a promotional unit has a sequence of 1 while a regular unit has a sequence of 2, so that promotional unit runs before the regular unit. We will execute the subscription units by the sequence you specified.
The number of times this subscription unit gets executed. Promotional unit can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular units can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).
amount
object
The three-character ISO-4217 currency code that identifies the currency.see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value as the summary of all kinds of total_amount in breakdown, which might be:An integer for currencies like JPY that are not typically fractional.A decimal fraction for currencies like TND that are subdivided into thousandths.For the required number of decimal places for a currency code, see Currency Codes.
breakdown
object
tax_total
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
taxes
object[]
The tax with breakdown
[UNKNOWN, ECOMMERCE_CONSUMPTION_TAX]
tax type
non-empty
tax name
Tax as a percentage of total amount example: value 8 means the tax as a percentage of total amount is 8%
tax_amount
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
tax reference
item_total
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
[UNKNOWN, TOTAL_AMOUNT, ITEM_AMOUNT]
Tax check mode, check tax by total amount or item amount. If merchant use payment_method=CHECKOUT_PAGE, this field is optional, and no need present tax_check_mode, tax_total of breakdown, taxes of breakdown. Otherwise, this field is required, and merchant should present tax_check_mode, tax_total of breakdown, taxes of breakdown.
[UNKNOWN, TAX_INCLUSIVE, TAX_EXCLUSIVE, NOT_TAX, TAX_DELAY]
tax mode This field is provided by system, merchant should not set it.
discount_display
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
remaining_discount_display
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
before_discount_display
object
The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The value, which might be: An integer for currencies like JPY that are not typically fractional. A decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency Codes.
Defines the maximum number of times a subscriber can receive promotional benefits for this product. This limit applies per (merchant_id, sub_merchant_id, subscriber.id, product.id). For example, if promotion_limit = 1, the subscriber can only enjoy this promotional unit once under the same combination of merchant, sub-merchant, subscriber, and product—even if they cancel and re-subscribe. This only affects subscription units with a promotional type. If the number of previous promotional subscriptions equals or exceeds the limit, the system will reject execution of the promotional unit. Default is 0, which means there is no limit.
The purchase reference of this subscription unit.
application_context
object
ApplicationContext provides contextual information for the subscription flow, including payment method selection, user navigation URLs, and the webhook endpoint for receiving asynchronous subscription lifecycle events.
payment_method
object
The method of payment, such as PAYPAL,CREDIT_CARD,GO_PAY pay etc.
non-empty
The name of pay method, such as PAYPAL,CREDIT_CARD,GO_PAY
The URL where the customer is redirected after the customer approves the subscription.
The URL where the customer is redirected after the customer cancels the subscription.
The URL to which your system will receive subscription-related events, covering initial subscription activation, renewals, cancellations, suspensions, resumes, and payment result notifications.
The two-character ISO639 language code see: https://en.wikipedia.org/wiki/ISO_639#Active_codes The language code of the merchant
Value must match regular expression ^[A-Z]{2}$
The two-character ISO 3166-1:2006 region code see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 The region code of the merchant
metadata
object
The additional data.
Responses
- 200
- default
OK
- application/json
- Response
- Example
Response
Array [
]
Array [
]
Array [
]
The id of this subscription we offer. Please save it for the other action such as query, cancellation etc.
[UNKNOWN, PENDING, APPROVED, ACTIVE, SUSPENDED, CANCELLED, VOIDED, COMPLETED]
The status of this subscription.
links
object[]
An array of request-related HATEOAS links. To complete subscription, use the "subscription" link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the Pay JavaScript SDK to initiate Pay Checkout (in context) ensure that you include application_context.return_url is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
[UNKNOWN, PAYMENT, SUBSCRIPTION, AUTHORISE, CAPTURE, UNBIND, QRCODE, QRCODE_IMAGE, PREPAY_TOKEN]
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
The HTTP method required to make the related call. Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.
internal_merchant_addition_data
object
内部商户特有字段
The channel name.
[MODE_UNKNOWN, NEED_CONTRACT, NO_CONTRACT, MIX_CONTRACT]
[MODE_UNKNOWN, NEED_CONTRACT, NO_CONTRACT]
payer_address
object
Address of payer or payee
country (eg. CN) -- use region_code instead
<= 100 characters
ISO 3166-2 define
city
county
region code
street name
house info
<= 100 characters
address postal code
internal_transaction_trace_infos
object[]
channel_addition_datas
object[]
外部渠道附加信息。
The channel name.
[MODE_UNKNOWN, NEED_CONTRACT, NO_CONTRACT]
{
"id": "string",
"status": "UNKNOWN",
"links": [
{
"rel": "UNKNOWN",
"href": "string",
"method": "string"
}
],
"internal_merchant_addition_data": {
"channel_name": "string",
"merchant_contract_mode": "MODE_UNKNOWN",
"channel_contract_mode": "MODE_UNKNOWN",
"channel_account_id": "string",
"channel_real_channels": [
"string"
],
"channel_order_id": "string",
"payer_ip": "string",
"payer_address": {
"country": "string",
"state_or_province": "string",
"city": "string",
"county": "string",
"region_code": "string",
"street": "string",
"house_number_or_name": "string",
"postal_code": "string"
},
"internal_transaction_trace_infos": [
{
"trace_id": "string",
"channel_name": "string",
"reference": "string",
"ouid": "string",
"merchant_ouid": "string",
"channel_midas_ouid": "string",
"merchant_midas_ouid": "string",
"multi_ou_version": "string"
}
],
"channel_addition_datas": [
{
"channel_name": "string",
"channel_contract_mode": "MODE_UNKNOWN",
"channel_account_id": "string",
"channel_real_channels": [
"string"
],
"channel_order_id": "string"
}
]
}
}
Error response structure
- application/json
- Response
- Example
Response
Array [
]
Array [
]
details
object[]
The type of the serialized message.
causes
object[]
{
"name": "string",
"message": "string",
"details": [
{
"@type": "string"
}
],
"debug_id": "string",
"causes": [
{
"cause": "string",
"solution": "string"
}
]
}