> ## 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: [] security: [] tags: - name: Subscription inquiry description: Subscription inquiry 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: Subscription change inquiry description: > This API allows merchants to query the status of a subscription change (upgrade/downgrade) request. 此接口允许商户查询订阅升降级请求的状态。 - name: Subscription update description: ' Subscription update api description' - name: Order inquiry description: Order inquiry api description - name: Payout inquiry description: Payout inquiry api description - name: Order create description: ' Order create api description' - name: Pay Method Config Inquiry description: Pay Method Config Inquiry api description - name: Order cancel description: Order cancel api description - name: Order capture description: Order capture api description - name: Chargeback list description: Chargeback list api description - name: Payout create description: Payout create api description - name: Chargeback file download description: Chargeback file download 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: Chargeback accept description: Chargeback accept api description - name: Chargeback file upload description: Chargeback file upload api description - name: Chargeback update description: Chargeback update api description - name: Wallet inquiry description: Wallet inquiry api description - name: Order refund description: Order refund api description - name: Refund inquiry description: Refund 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: Merchant config inquiry description: Merchant config inquiry api description - name: Chargeback inquiry description: Chargeback inquiry api description - name: Subscription create description: Subscription create api description - name: Reported Fraud list description: Reported Fraud list 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 example: 0 msg: type: string example: success 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 cancelReason: type: string description: >- Platform cancel reason; only present when subscriptionStatus = PLATFORM_CANCELLED example: CHARGEBACK_ALERT 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/SubscriptionInquiryResponse.ProductInfo' description: Subscription product info details merchantInfo: $ref: '#/components/schemas/SubscriptionInquiryResponse.MerchantInfo' description: Merchant info userInfo: $ref: '#/components/schemas/SubscriptionInquiryResponse.UserInfo' description: User info paymentInfo: $ref: '#/components/schemas/SubscriptionInquiryResponse.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/SubscriptionInquiryResponse.GoodsInfo' description: Merchant goods information addressInfo: $ref: '#/components/schemas/SubscriptionInquiryResponse.AddressInfo' description: Address Information SubscriptionInquiryResponse.ProductInfo: type: object description: Subscription product information 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 must be greater than or equal to 1. For example 24 means every 24 months, and 36 means every 36 months 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 scheduledAmounts: type: array description: Scheduled amount list for each period items: $ref: '#/components/schemas/SubscriptionScheduledAmount' required: - description - periodInterval - periodType SubscriptionInquiryResponse.MerchantInfo: type: object description: Merchant information 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 SubscriptionInquiryResponse.UserInfo: type: object description: User information 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 SubscriptionInquiryResponse.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 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 payMethodCountry: type: string description: > Some pay methods are available in multiple countries (e.g. GrabPay, ShopeePay). The pay method country specified by merchant on subscription creation. maxLength: 3 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 topupDetails: type: array description: >- The array object of seat add-on (top-up) orders accepted in this period; absent when the period has none items: $ref: '#/components/schemas/SubscriptionInquiryResponse.TopupDetail' SubscriptionInquiryResponse.GoodsInfo: type: object description: Goods information 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 SubscriptionInquiryResponse.AddressInfo: type: object description: Address information 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 SubscriptionScheduledAmount: type: object description: Scheduled amount item for a specific period properties: period: type: string description: Period number, for example 1 amount: type: string description: Merchant subscription amount for this period, for example 100 SubscriptionInquiryResponse.TopupDetail: type: object properties: acquiringOrderId: type: string description: Waffo acquiring order Id of the top-up order topupRequest: type: string description: Merchant top-up request Id (idempotency key of the seat add-on) topupAmount: type: string description: Top-up amount charged in the current period orderCurrency: type: string description: Top-up order currency orderStatus: type: string description: Top-up order status ````