> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/subscription/create openapi: 3.1.0 info: title: acquiring-order description: 接口文档 termsOfService: https://www.waffo.com version: 1.0.0 servers: - url: https://www.waffo.com description: Sandbox API (auto-signed via Next.js proxy) security: [] tags: - name: Order create description: ' Order create api description' - name: Subscription create description: Subscription create api description - name: Subscription inquiry description: Subscription inquiry api description - name: Order inquiry description: Order inquiry api description - name: Subscription cancel description: > Cancel an active subscription when the merchant no longer wishes to continue the recurring billing cycle. This endpoint can only be invoked when the subscription status is active - name: Order cancel description: Order cancel api description - name: Subscription manage description: > This API allows the merchant to request a subscription management URL from Waffo Waffo will generate a subscription management URL which merchant can redirect user to this URL for managing subscription details (e.g. view subscription detail and cancel subscription). This management URL has a fixed expiration time (e.g., 1 day). - name: Order refund description: Order refund api description - name: Subscription change description: > This API allows merchants to upgrade or downgrade a user's subscription plan. The change request will create a new subscription based on the original subscription, applying any remaining amount from the original subscription. 此接口允许商户升级或降级用户的订阅计划。升降级请求将基于原订阅创建新订阅，并将原订阅的剩余金额应用到新订阅中。 - name: Refund inquiry description: Refund inquiry api description - name: Subscription change inquiry description: > This API allows merchants to query the status of a subscription change (upgrade/downgrade) request. 此接口允许商户查询订阅升降级请求的状态。 - name: Merchant config inquiry description: Merchant config inquiry api description - name: Pay Method Config Inquiry description: Pay Method Config Inquiry api description paths: /api/v1/subscription/create: post: tags: - Subscription create summary: Create Subscription description: >- Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement operationId: createSubscription requestBody: content: application/json: schema: $ref: '#/components/schemas/AcqSubscriptionCreateRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseAcqSubscriptionCreateResponse' components: schemas: AcqSubscriptionCreateRequest: type: object properties: subscriptionRequest: type: string description: >- Subscription request id sent from Merchant. It will also be used for idempotent check. x-gen: NANOID maxLength: 32 minLength: 0 merchantSubscriptionId: type: string description: Merchant subscription plan ID assigned to this user example: PLAN_001 maxLength: 64 minLength: 0 currency: type: string description: Merchant subscription currency, for example USD example: USD maxLength: 12 minLength: 0 amount: type: string description: Merchant subscription amount, for example 100 example: 100 maxLength: 24 minLength: 0 productInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.ProductInfo' description: Subscription product info userCurrency: type: string description: >- User payment currency. This is needed when merchant order currency is NOT the same as user payment currency maxLength: 12 minLength: 0 merchantInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.MerchantInfo' description: | Merchant info userInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.UserInfo' description: | User info goodsInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.GoodsInfo' description: | Merchant goods information addressInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.AddressInfo' description: | Address Information brandInfo: $ref: '#/components/schemas/BrandInfo' description: Brand display information for cashier paymentInfo: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.PaymentInfo' description: | Payment information requestedAt: type: string format: date-time description: Merchant-side request time x-gen: DATETIME_ISO successRedirectUrl: type: string description: > The address of the merchant page to redirect to after successful subscription payment. If no value is provided, it will stay on the cashier page after successful payment. example: https://merchant-success-redirecturl.com maxLength: 512 minLength: 0 failedRedirectUrl: type: string description: > The address of the merchant page to which the payment pre-verification fails, or the redirection after the payment fails. If no value is provided, it will stay on the cashier page after the payment fails example: https://merchant-failed-redirecturl.com maxLength: 512 minLength: 0 notifyUrl: type: string description: > The callback address to notify the merchant after the subscription is completed / failed example: https://merchant-notify-url.com maxLength: 256 minLength: 0 cancelRedirectUrl: type: string description: > User will be redirected to this page if user choose to cancel and not continue the payment example: https://merchant-cancel-url.com maxLength: 512 minLength: 0 riskData: $ref: '#/components/schemas/AcqSubscriptionCreateRequest.RiskData' subscriptionManagementUrl: type: string description: > It refers to the subscription management page for users on the merchant side. example: https://merchant.com/subscription/manage maxLength: 256 minLength: 0 extendInfo: type: string description: | Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} maxLength: 256 minLength: 0 orderExpiredAt: type: string format: date-time description: > The order expiry time set by merchant. User is required to input payment data on Waffo cashier page prior to merchant's order expiry time. If not provided, the default is 4 hours required: - amount - currency - merchantInfo - merchantSubscriptionId - notifyUrl - productInfo - requestedAt - subscriptionRequest - userInfo ResponseAcqSubscriptionCreateResponse: type: object description: response data properties: code: type: string msg: type: string data: $ref: '#/components/schemas/AcqSubscriptionCreateResponse' AcqSubscriptionCreateRequest.ProductInfo: type: object description: Subscription product information properties: description: type: string description: >- Subscription product description, often appearing to user when asking user's confirmation example: Premium Monthly Subscription maxLength: 128 minLength: 0 periodType: type: string description: | Subscription product period type: - DAILY - WEEKLY - MONTHLY example: MONTHLY maxLength: 12 minLength: 0 periodInterval: type: string description: > Period interval. If the period type is DAILY, the period interval is between 1-365 If the period type is WEEKLY, the period interval is between 1-4 If the period type is MONTHLY, the period interval is between 1-12 For example if the period type is weekly, the period interval is 2, it means every 2 weeks time user will pay for the subscription amount example: 1 maxLength: 12 minLength: 0 numberOfPeriod: type: string description: > Specify after how many deduction period, the subscription will end. The value needs to be greater than 1. For example 3 If the value is empty, it means the subscription has no defined end period Note: The Dana subscription period shall not exceed three years in total. example: 12 maxLength: 24 minLength: 0 trialPeriodAmount: type: string description: > The subscription amount that user pay during the trial period, for example 8000 The amount shall >= 0 If the value is empty, there is no trial period example: 0 maxLength: 24 minLength: 0 numberOfTrialPeriod: type: string description: | Specify after how many periods, the trial will end. For example 1894 example: 1 maxLength: 12 minLength: 0 trialPeriodType: type: string description: > Subscription product period type: - DAILY - WEEKLY - MONTHLY This field is optional when a trial period is configured. If omitted, the system will use periodType value by default. example: MONTHLY maxLength: 12 minLength: 0 trialPeriodInterval: type: string description: > Represents the interval unit of the trial period. Same definition and behavior as periodInterval. If the period type is DAILY, the period interval is between 1-365 This field is optional when a trial period is configured. If omitted, the system will use periodInterval value by default.. example: 1 maxLength: 12 minLength: 0 required: - description - periodInterval - periodType AcqSubscriptionCreateRequest.MerchantInfo: type: object description: Merchant information properties: merchantId: type: string description: | Merchant id assigned by Waffo example: 1000000201 maxLength: 64 minLength: 0 subMerchantId: type: string description: | Sub merchant id assigned by Waffo maxLength: 64 minLength: 0 required: - merchantId AcqSubscriptionCreateRequest.UserInfo: type: object description: User information properties: userId: type: string description: 'Merchant User id. ' example: USER001 maxLength: 64 minLength: 0 userEmail: type: string description: Merchant user email example: user@example.com maxLength: 64 minLength: 0 userTerminal: type: string description: | Merchant user terminal type: - WEB (user is using a PC) - APP (user is using a Mobile Phone) maxLength: 32 minLength: 0 userPhone: type: string description: > Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157 example: +62-08990013157 maxLength: 32 minLength: 0 userFirstName: type: string description: Merchant user's first name maxLength: 64 minLength: 0 userLastName: type: string description: Merchant user's last name maxLength: 64 minLength: 0 userCreatedAt: type: string format: date-time description: Merchant user creation time required: - userEmail - userId AcqSubscriptionCreateRequest.GoodsInfo: type: object description: Goods information properties: goodsId: type: string description: | Goods item id example: GOODS001 maxLength: 32 minLength: 0 goodsName: type: string description: | Goods item name example: Premium Subscription Plan maxLength: 64 minLength: 0 goodsCategory: type: string description: | Goods category maxLength: 32 minLength: 0 goodsUrl: type: string description: > Goods URL from merchant website, for example https://www.merchant123.com/goods123 (for compliance and risk management purpose) maxLength: 128 minLength: 0 appName: type: string description: | app package name, for example com.example.app123 (for compliance and risk management purpose) maxLength: 32 minLength: 0 skuName: type: string description: | Goods sku name maxLength: 32 minLength: 0 goodsUniquePrice: type: string description: | Goods price maxLength: 16 minLength: 0 goodsQuantity: type: integer format: int32 description: | Goods quantity required: - goodsId - goodsName AcqSubscriptionCreateRequest.AddressInfo: type: object description: Address information properties: address: type: string description: | Shipping address maxLength: 256 minLength: 0 city: type: string description: | Shipping city maxLength: 32 minLength: 0 region: type: string description: | Shipping region / state / province maxLength: 32 minLength: 0 postcode: type: string description: | Shipping postcode maxLength: 16 minLength: 0 addressCountryCode: type: string description: | Shipping country code maxLength: 16 minLength: 0 BrandInfo: type: object description: Brand display information for cashier properties: cashierLogoUrl: type: string description: |2 Merchant logo for cashier display. - It supports external URL from merchant, and the format starts with https://, and the recommended size is 40x40 px - It also supports the pre-created logo ID via https://dashboard.waffo.com/checkout/cashier-customization and the format starts with logo_ maxLength: 512 minLength: 0 cashierDisplayName: type: string description: Merchant display name for cashier maxLength: 128 minLength: 0 cashierProductImageUrl: type: string description: >- Product image URL for cashier display. Starts with https://. Recommended size: 1200x630 px maxLength: 512 minLength: 0 AcqSubscriptionCreateRequest.PaymentInfo: type: object description: Payment information properties: productName: type: string description: | Payment product: - SUBSCRIPTION - MINI_PROGRAM_SUBSCRIPTION Merchant can view the signed contract product via Waffo Merchant portal example: SUBSCRIPTION maxLength: 32 minLength: 0 payMethodType: type: string description: | Payment method type. e.g. - EWALLET - CREDITCARD - DEBITCARD Merchant can provide a list of pay methods type as the filtering logic, e.g. CREDITCARD, DEBITCARD indicate user can pay use either credit card or debit card If not provided, Waffo will choose all eligible payment methods based on merchant contract and display them on Waffo's cashier page for user to select Conditional (must be provided for card payments) example: CREDITCARD,DEBITCARD,APPLEPAY,GOOGLEPAY maxLength: 256 minLength: 0 payMethodName: type: string description: | The actual payment method. e.g. DANA If payMethodName is provided, the payment request will be processed using this pay method directly. If merchant intends to limit the card payment scheme, e.g. Restrict user to use only VISA card, merchant can specify payMethodName as CC_VISA, DC_VISA Conditional (required for non-card payment methods) maxLength: 24 minLength: 0 payMethodProperties: type: string description: > For certain pay methods, there could be certain specific info needed. Json format e.g. {"key1":"value1", "key2":"value2"} maxLength: 256 minLength: 0 payMethodUserAccountType: type: string description: | User account type at the designated pay method EMAIL PHONE_NO ACCOUNT_ID maxLength: 24 minLength: 0 payMethodUserAccountNo: type: string description: | User account number at the designated pay method maxLength: 64 minLength: 0 payMethodUserAccessToken: type: string description: > User access token is required when using MINI_PROGRAM_SUBSCRIPTION product The user access token can be obtained from mini program API maxLength: 128 minLength: 0 cashierLanguage: type: string description: > Merchant specify the cashier language. It follows IETF BCP 47 language tag The format is Language (two-letter language code from ISO 639-1), follow by an optional script subtag, based on a four-letter script code from ISO 15924, and follow by an optional region subtag based on a two-letter country code from ISO 3166-1 alpha-2 For example: - en-HK: English in Hong Kong - zh-Hant-HK: Traditional Chinese in Hong Kong - zh-Hans-HK: Simplified Chinese in Hong Kong maxLength: 24 minLength: 0 cashierAppearance: type: string description: > Defines the overall appearance configuration of the UI, including colors, background, and typography settings. A JSON-formatted string containing theme variables. These variables are injected into the UI rendering layer and override the default theme settings. This field must be a valid JSON string, not a plain object. Example: {"variables":{"colorPrimary":"#0570de","colorBackground":"#ffffff","colorText":"#30313d"}} required: - productName AcqSubscriptionCreateRequest.RiskData: type: object description: Risk data for compliance properties: userType: type: string description: | Merchant user: Individual / Agent / Institution / Internal example: Individual maxLength: 24 minLength: 0 userCategory: type: string description: | Merchant user: Member / Non-Member example: Member maxLength: 24 minLength: 0 userLegalName: type: string description: | Merchant user legal name (or first name + last name) example: John Doe maxLength: 128 minLength: 0 userDisplayName: type: string description: | Merchant user display name example: John maxLength: 128 minLength: 0 userRegistrationIp: type: string description: | Merchant user registration IP address example: 192.168.1.1 maxLength: 24 minLength: 0 userLastSeenIp: type: string description: | Merchant user last login IP address example: 192.168.1.1 maxLength: 24 minLength: 0 userIsNew: type: string description: | Merchant user if he/she is a new user: Yes / No example: 'No' maxLength: 8 minLength: 0 userIsFirstPurchase: type: string description: | Merchant user if this is his/her first purchase: Yes / No example: 'No' maxLength: 8 minLength: 0 AcqSubscriptionCreateResponse: type: object properties: subscriptionRequest: type: string description: >- Subscription request id sent from Merchant. It will also be used for idempotent check. merchantSubscriptionId: type: string description: Merchant subscription plan ID assigned to this user subscriptionId: type: string description: Waffo subscription Id payMethodSubscriptionId: type: string description: | Payment method's subscription id subscriptionStatus: type: string description: > Subscription status - AUTHORIZATION_REQUIRED (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction) - IN_PROGRESS (user is in progress to confirm the subscription) - ACTIVE - CLOSE (due to timeout or failed) - MERCHANT_CANCELLED - USER_CANCELLED - CHANNEL_CANCELLED - EXPIRED subscriptionAction: type: string description: > When subscriptionStatus = AUTHORIZATION_REQUIRED, merchant follow the following: “webUrl”: redirect user to this URL ````