> ## 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. # Order inquiry ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/order/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/order/inquiry: post: tags: - Order inquiry summary: Order inquiry operationId: orderInquiry requestBody: content: application/json: schema: $ref: '#/components/schemas/AcqOrderInquiryRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseAcqOrderInquiry' components: schemas: AcqOrderInquiryRequest: type: object description: provide paymentRequestId or acquirerOrderId properties: paymentRequestId: type: string description: >- Payment request id sent from Merchant. It will also be used for idempotent check. (provide paymentRequestId or acquirerOrderId) acquiringOrderId: type: string description: |- waffo acquiring order Id (provide paymentRequestId or acquirerOrderId) example: ResponseAcqOrderInquiry: type: object description: response data properties: code: type: string msg: type: string data: $ref: '#/components/schemas/AcqOrderInquiry' AcqOrderInquiry: type: object description: A PaymentOrder object will be returned. properties: paymentRequestId: type: string description: >- Payment request id sent from Merchant. It will also be used for idempotent check. merchantOrderId: type: string description: Merchant order id acquiringOrderId: type: string description: Waffo acquiring order Id orderStatus: type: string description: >- **PAY_IN_PROGRESS** - (merchant order is accepted, and user is in the process of payment) **AUTHORIZATION_REQUIRED** (pay method requires user authorization, usually for an OTP authentication or a redirection to a page for authentication) **AUTHED_WAITING_CAPTURE** (Order needs to be captured by merchant, applicable for CARD payment) **PAY_SUCCESS** **ORDER_CLOSE** (due to order cancel or timeout) example: PAY_IN_PROGRESS orderAction: type: string description: > When orderStatus = AUTHORIZATION_REQUIRED, merchant follow the following: "actionType": value could be "WEB" / "DEEPLINK". If the actionType is WEB, merchant choose webUrl to redirect user. If the actionType is DEEPLINK, merchant choose deeplinkUrl to redirect user. "webUrl": redirect user to webURL "deeplinkUrl": redirect user to deeplink url "actionData": { "paymentExpiryTime":"2023-04-01T03:00:00.000Z", (Follow ISO 8601 standard) "paymentQr":"xxx", (QR String Value) "paymentCode":"xxx", "paymentBarCode":"xxx", "paymentCurrency": "xxx", "paymentAmount": "xxx", "userFeeAmount": "xxx", "userFeeCurrency":"xxx", "exchangeRate": "xxx" (it is paymentAmount/orderAmount when orderCurrency is not the same as paymentCurrency) } ActionData is for those Merchants who want to build their own Cashier Page for their users, without using Waffo's cashier page orderCurrency: type: string description: Merchant order currency orderAmount: type: string description: Merchant order amount finalDealAmount: type: string description: >- The final amount that the user paid. If merchant order currency is not the same as user payment currency, the finalDealAmount will not be the same as orderAmount. If there are additional service fees that the user paid, the finalDealAmount will also not be the same as orderAmount. orderDescription: type: string description: Order description information merchantInfo: $ref: '#/components/schemas/MerchantInfo' description: merchant Info userInfo: $ref: '#/components/schemas/AcqOrderMerchantUserInfo' description: user info goodsInfo: $ref: '#/components/schemas/AcqOrderGoodsInfo' description: goods info paymentInfo: $ref: '#/components/schemas/AcqOrderPaymentInfo' description: payment info addressInfo: $ref: '#/components/schemas/AcqOrderAddressInfo' description: address info orderRequestedAt: type: string description: Merchant-side request time orderExpiredAt: type: string description: >- The order expiry time set by merchant. If not set, the default merchant contract expiry time will be used orderUpdatedAt: type: string description: Order last update time orderCompletedAt: type: string description: Order completion time refundExpiryAt: type: string description: > Refund expiry time. After this time, refunds are no longer allowed. Format follows ISO 8601 standard (e.g., 2023-07-01T23:59:59.999Z) Note: If refunds are not allowed or the order is not successful, this value is null. cancelRedirectUrl: type: string description: >- The address of the merchant page to redirect to when user cancels the payment orderFailedReason: type: string description: |- Json format { "orderFailedCode":"XXX", "orderFailedDescription":"XXX" } extendInfo: type: string description: 'Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} ' userCurrency: type: string description: >- User payment currency. This is needed when merchant order currency is NOT the same as user payment currency subscriptionInfo: $ref: '#/components/schemas/SubscriptionInfo' required: - acquiringOrderId - finalDealAmount - merchantOrderId - orderAmount - orderCurrency - orderDescription - orderStatus - paymentRequestId 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 AcqOrderMerchantUserInfo: type: object description: User info properties: userId: type: string description: Merchant User id example: '0001' maxLength: 64 minLength: 0 userCreatedAt: type: string description: Merchant user creation time example: '2021-05-16T08:00:00.000Z' userEmail: type: string description: Merchant user email example: test@email.com maxLength: 64 minLength: 0 userPhone: type: string description: Merchant user mobile phone number maxLength: 30 minLength: 0 userCountryCode: type: string description: The country code of the source of the user request maxLength: 3 minLength: 0 userTerminal: type: string default: WEB description: >- user terminal type: - **WEB** (user is using a PC) - **APP** (user is using a Mobile Phone) - **IN_WALLET_APP** (user is inside a pay method's wallet app (e.g. Wechat app)) - **IN_MINI_PROGRAM** (user is inside a pay method's mini program (e.g. Wechat mini program)) Not all pay methods support the above user terminals, hence such info is used for checking if a user can use a particular pay method for his/her payment example: WEB 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 userBrowserIp: type: string description: >- Merchant user browser IP address. This is field is only required when merchant pass in card/applepay/googlepay data directly in API maxLength: 128 minLength: 0 userAgent: type: string description: >- Merchant user browser agent. This is field is only required when merchant pass in card/applepay/googlepay data directly in API maxLength: 256 minLength: 0 userReceiptUrl: type: string description: >- User receipt Url which merchant can trigger again to download the user receipt required: - userEmail - userId - userTerminal AcqOrderGoodsInfo: type: object description: GoodsInfo properties: goodsId: type: string description: Goods item id example: 10001 maxLength: 128 minLength: 0 goodsName: type: string description: Goods item name example: GameXXX-001 maxLength: 64 minLength: 0 skuName: type: string description: Goods sku categories example: GameXXX maxLength: 32 minLength: 0 goodsUniquePrice: type: string description: Goods price example: 100 maxLength: 16 minLength: 0 goodsQuantity: type: integer format: int32 description: Goods quantity example: 1 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) provide either goodsUrl or appName example: https://www.merchant123.com/goods123 maxLength: 128 minLength: 0 appName: type: string description: |- app package name, for example com.example.app123 (for compliance and risk management purpose) provide either goodsUrl or appName maxLength: 32 minLength: 0 required: - appName - goodsName - goodsUrl AcqOrderPaymentInfo: type: object description: Payment information properties: productName: type: string description: |- Payment product: - **ONE_TIME_PAYMENT** - **DIRECT_PAYMENT** example: ONE_TIME_PAYMENT maxLength: 32 minLength: 0 payMethodType: type: string description: |- Payment method type. e.g. - **EWALLET** - **ONLINE_BANKING** - **DIGITAL_BANKING** - **OTC** - **CREDITCARD** - **DEBITCARD** example: EWALLET maxLength: 256 minLength: 0 payMethodName: type: string description: > The actual payment method. e.g. DANA, GCASH If payMethodName is provided, the payment request will be processed using this pay method directly. If payMethodName is not provided, user will be redirected to Waffo's cashier page to choose the final pay method. 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 example: DANA maxLength: 256 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"}. Currently support the following key: - cpf - cardPrefix cpf: specify the user's cpf number used in this payment cardPrefix: restrict user card payment by a prefix card bin number, from 4-9 digits. Multiple card bins can be separated by commas, with a maximum of 80 allowed. cardPrefixPurpose: input restriction purpose. Merchant can set as restriction or promotion. Waffo will display the respective error message to the user maxLength: 1024 minLength: 0 payMethodResponse: type: string description: > The specific information returned by Pay Method Json format { "payMethodRefId": "xxx", "exchangeRate": "xxx", "userOpenId": "xxx" } - payMethodRefId: This is the payment ref ID that user often sees in its transaction history from Pay Method's app/portal - exchangeRate: this is the exchange rate used by Pay Method during user payment - userOpenId: this is the unique user open ID assigned by the pay method readOnly: true userPaymentAccessToken: type: string description: Applicable for ONE_CLICK_PAYMENT product maxLength: 256 minLength: 0 payMethodUserAccountNo: type: string description: User account number at the designated pay method maxLength: 64 minLength: 0 payMethodUserAccountType: type: string description: |- User account type at the designated pay method EMAIL PHONE_NO ACCOUNT_ID maxLength: 24 minLength: 0 payOption: type: string description: >- The pay option user has selected, for example - **BALANCE** - **DEBIT_CARD** - **CREDIT_CARD** If the pay method does not support users to select the pay option, the field will be empty readOnly: true 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: > Merchant specify the cashier appearance For example: - "variables": "{"colorPrimary":"#0570de","colorBackground":"#ffffff","colorText":"#30313d"}" payMethodCountry: type: string description: > Some pay methods are available in multiple countries (e.g. GrabPay, ShoppeePay), the merchant shall specify the pay method country when necessarily maxLength: 3 minLength: 0 captureMode: type: string maxLength: 24 minLength: 0 merchantInitiatedMode: type: string description: > Specify when it is a merchant initiated transaction (mit) without customer involvement. userPaymentAccessToken is also required for mit transaction - scheduled - unscheduled maxLength: 24 minLength: 0 required: - productName AcqOrderAddressInfo: type: object description: addressInfo properties: address: type: string description: Shipping address example: street 123 ... maxLength: 256 minLength: 0 city: type: string description: Shipping city example: city123 maxLength: 32 minLength: 0 region: type: string description: Shipping region / state / province example: region or state or province 123 maxLength: 32 minLength: 0 postcode: type: string description: Shipping postcode example: 112233 maxLength: 16 minLength: 0 addressCountryCode: type: string description: Shipping country code example: IDN maxLength: 16 minLength: 0 SubscriptionInfo: type: object description: The associated subscription info properties: subscriptionId: type: string description: The associated subscription ID period: type: string description: Which period the subscription payment belong to. For example 2 subscriptionRequest: type: string description: >- Subscription request id sent from Merchant. It will also be used for idempotent check. required: - period - subscriptionId - subscriptionRequest ````