> ## 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. # Subscription Inquiry ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/subscription/inquiry 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/inquiry: post: tags: - Subscription inquiry summary: Subscription Inquiry operationId: subscriptionInquiry requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionInquiryRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseSubscriptionInquiryResponse' components: schemas: SubscriptionInquiryRequest: type: object description: Provide subscriptionRequest or subscriptionId properties: subscriptionRequest: type: string description: >- Merchant subscription plan ID assigned to this user (provide subscriptionRequest or subscriptionId) example: maxLength: 32 minLength: 0 subscriptionId: type: string description: >- Waffo subscription Id (provide subscriptionRequest or subscriptionId) example: maxLength: 64 minLength: 0 paymentDetails: type: integer format: int32 description: > Indicate if merchant wants to inquiry all the payment details associated with the subscription. Default is 0 - 0 (meaning payment details are not required) - 1 (meaning payment details are required) example: 1 ResponseSubscriptionInquiryResponse: type: object description: response data properties: code: type: string msg: type: string data: $ref: '#/components/schemas/SubscriptionInquiryResponse' SubscriptionInquiryResponse: 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 currency: type: string description: Merchant subscription currency, for example IDR example: IDR userCurrency: type: string description: >- User payment currency. This is needed when merchant order currency is NOT the same as user payment currency amount: type: string description: Merchant subscription amount, for example 10000 productInfo: $ref: '#/components/schemas/ProductInfo' description: Subscription product info details merchantInfo: $ref: '#/components/schemas/MerchantInfo' description: Merchant info userInfo: $ref: '#/components/schemas/UserInfo' description: User info paymentInfo: $ref: '#/components/schemas/PaymentInfo' description: Payment information requestedAt: type: string description: Merchant-side request time updatedAt: type: string description: Subscription last update time failedReason: type: string description: | Json format { "orderFailedCode": "XXX", "orderFailedDescription"" "XXX" } subscriptionManagementUrl: type: string description: > It refers to the subscription management page for users on the merchant side. extendInfo: type: string description: | Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} paymentDetails: type: array description: >- The array object of the payment details associated to this subscription items: $ref: '#/components/schemas/PaymentDetail' goodsInfo: $ref: '#/components/schemas/GoodsInfo' description: Merchant goods information addressInfo: $ref: '#/components/schemas/AddressInfo' description: Address Information ProductInfo: type: object properties: description: type: string description: >- Subscription product description, often appearing to user when asking user's confirmation maxLength: 128 minLength: 0 periodType: type: string description: | Subscription product period type: - DAILY - WEEKLY - MONTHLY maxLength: 12 minLength: 0 periodInterval: type: string description: > Period interval. For example 1 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 maxLength: 12 minLength: 0 numberOfPeriod: type: string description: > Specify after how many deduction period, the subscription will end. For example 3 If the value is empty, it means the subscription has no defined end period The subscription periods shall not exceed 3 years in total 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 maxLength: 24 minLength: 0 numberOfTrialPeriod: type: string description: | Specify after how many periods, the trial will end. For 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. 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.. maxLength: 12 minLength: 0 startDateTime: type: string description: When the subscription starts maxLength: 24 minLength: 0 endDateTime: type: string description: When the subscription ends maxLength: 24 minLength: 0 nextPaymentDateTime: type: string description: When the next payment is on due maxLength: 24 minLength: 0 currentPeriod: type: string description: Indicate the number of current period. For example, 4 maxLength: 24 minLength: 0 required: - description - periodInterval - periodType MerchantInfo: type: object properties: merchantId: type: string description: Merchant Id assigned by Waffo maxLength: 64 minLength: 0 subMerchantId: type: string description: Sub merchant id assigned by Waffo maxLength: 64 minLength: 0 required: - merchantId UserInfo: type: object properties: userId: type: string description: Merchant User id maxLength: 64 minLength: 0 userEmail: type: string description: Merchant user email maxLength: 64 minLength: 0 userPhone: type: string description: Merchant user mobile phone number maxLength: 16 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 description: Merchant user creation time maxLength: 24 minLength: 0 required: - userEmail - userId PaymentInfo: type: object properties: productName: type: string description: > Payment product: - SUBSCRIPTION - MINI_PROGRAM_SUBSCRIPTION Merchant can view the signed contract product via Waffo Merchant portal 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 maxLength: 16 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 maxLength: 24 minLength: 0 payMethodProperties: type: string description: >- For certain payment methods, there could be certain specific info needed. Json format e.g. {"key1":"value1", "key2":"value2"} maxLength: 256 minLength: 0 payMethodResponse: type: string description: The specific information returned by pay Method 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 payMethodPublicUid: type: string description: Public user id at the designated pay method maxLength: 128 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 required: - payMethodName - productName PaymentDetail: type: object properties: acquiringOrderId: type: string description: Waffo acquiring order Id orderCurrency: type: string description: Subscription Payment order currency orderAmount: type: string description: Subscription Payment amount orderStatus: type: string description: | Subscription Payment status - PAY_SUCCESS - ORDER_CLOSE (payment failed) orderUpdatedAt: type: string description: Subscription Payment update time period: type: string description: Which period the subscription payment belong to. For example 2 GoodsInfo: type: object properties: goodsId: type: string description: Goods item id goodsName: type: string description: Goods item name goodsCategory: type: string description: Goods category goodsUrl: type: string description: > Goods URL from merchant website, for example https://www.merchant123.com/goods123 (for compliance and risk management purpose) appName: type: string description: | app package name, for example com.example.app123 (for compliance and risk management purpose) skuName: type: string description: Goods sku name goodsUniquePrice: type: string description: Goods price goodsQuantity: type: integer format: int32 description: Goods quantity AddressInfo: type: object properties: address: type: string description: Shipping address city: type: string description: Shipping city region: type: string description: Shipping region / state / province postcode: type: string description: Shipping postcode addressCountryCode: type: string description: Shipping country code ````