> ## 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: [] 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/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 example: 0 msg: type: string example: success 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, failed 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) "bankAccount":"xxx", "bankName":"xxx", "referenceNumber":"xxx", "bankBeneficiary":"xxx" } 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 originalAmount: type: string description: Original merchant order amount before discount 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/AcqOrderInquiry.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 x402Info: $ref: '#/components/schemas/X402Info' description: >- x402 stablecoin payment info. Carries x402Response (base64 SettlementResponse) only when orderStatus = PAY_SUCCESS. subscriptionInfo: $ref: '#/components/schemas/AcqOrderInquiry.SubscriptionInfo' required: - acquiringOrderId - finalDealAmount - merchantOrderId - orderAmount - orderCurrency - orderDescription - orderStatus - paymentRequestId AcqOrderInquiry.MerchantInfo: type: object description: Merchant info properties: merchantId: type: string description: Merchant Id assigned by Waffo subMerchantId: type: string description: Sub merchant id assigned by Waffo 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. This field is required. If you have not collected the user's email, pass a unique fallback in the format `userId@examples.com`, replacing `userId` with the actual user ID. You can also contact Waffo to configure this fallback on your behalf; merchant authorization is required. After going live, pass the user's real email whenever possible. Do not use placeholder values such as `test` or share one email address across multiple users, because this may trigger risk controls. example: 0001@examples.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** (currently supported for DANA only) - **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 name 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** - **MINI_PROGRAM_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: 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 - allowedRemitters: restrict who can pay a bank transfer order. Only applicable to India Bank Transfer (payMethodType VA, payMethodName BANKTRANSFER). Optional; when omitted, any remitter can pay. When provided, one or more items are allowed and both fields are required for each item: accountNumber is the payer's bank account number, bankRoutingCode is the payer's bank routing code, which for India is the IFSC code. The virtual account will only accept transfers from these accounts. Example: {"allowedRemitters":[{"accountNumber":"26291800001191","bankRoutingCode":"YESB0000262"}]} maxLength: 1024 minLength: 0 payMethodResponse: type: string description: > The specific information returned by Pay Method Json format { "payMethodRefId": "xxx", "exchangeRate": "xxx", "userOpenId": "xxx", "maskCardData": "402856******9917", "userPaymentAmount": "10.00", "userPaymentCurrency": "CNY" } - 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 - maskCardData: returns the first six and last four digits of customer card data for a successful card payment transaction - userPaymentAmount: the actual amount paid by the user on the pay method side - userPaymentCurrency: the currency of the actual payment made by the user on the pay method side readOnly: true userPaymentAccessToken: type: string description: > User payment access token is generated via Waffo tokenization service. It is used to tokenize user's card data. For card binding and tokenization details, refer to [Waffo Tokenization Overview](https://waffo.com/docs/zh/developer-docs/integration/tokenization/overview). 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 receiptTemplateId: type: string description: Merchant specify the receipt template id maxLength: 32 minLength: 0 cashierAppearance: type: string description: > Defines the overall appearance configuration of the UI, including colors, background, and typography settings. This field must be a valid JSON string, not a plain object. For example: {"variables":{"colorPrimary":"#0570de","colorBackground":"#ffffff","colorText":"#30313d"}} payMethodCountry: type: string description: > Some pay methods are available in multiple countries (e.g. GrabPay, ShopeePay). The merchant shall specify the pay method country when necessary. maxLength: 3 minLength: 0 captureMode: type: string description: > - **manualCapture**: the payment was authorized first, but Merchant will capture it manually at a later stage 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 setupFutureUsage: type: boolean description: > Indicate that this payment shall also set up (tokenize) the payment method for future merchant initiated transactions (mit). When true, only pay methods capable of mit are offered. After this customer initiated payment succeeds, the payment method is tokenized; reuse the resulting token as userPaymentAccessToken, together with merchantInitiatedMode, to initiate a later mit. When setupFutureUsage is used, do not provide userPaymentAccessToken. For how the token is obtained and reused for mit, refer to [Waffo Tokenization Overview](https://waffo.com/docs/zh/developer-docs/integration/tokenization/overview). 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 X402Info: type: object description: x402 stablecoin payment info envelope properties: x402Request: type: boolean description: Whether this is an x402 stablecoin payment request example: true paymentSignatureHeader: type: string description: >- Mode① only. base64-encoded x402 PaymentPayload (EIP-3009 signature) the merchant collected from the Agent and forwards to Waffo for settlement. maxLength: 4096 minLength: 0 x402Response: type: string description: >- Response only. base64-encoded x402 SettlementResponse (PAYMENT-RESPONSE), returned only when orderStatus = PAY_SUCCESS. readOnly: true AcqOrderInquiry.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 merchantRequest: type: string description: >- Subscription request id sent from Merchant. It will also be used for idempotent check. subscriptionRequest: type: string description: >- Subscription request id sent from Merchant. It will also be used for idempotent check. subscriptionEvent: type: string description: 'Subscription event: PERIOD_CHARGE / USER_ADD_PAYMENT_METHOD' required: - merchantRequest - subscriptionEvent - subscriptionId - subscriptionRequest ````