> ## 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 new order > 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/order/create openapi: 3.1.0 info: title: acquiring-order description: 接口文档 termsOfService: https://www.waffo.com version: 1.0.0 servers: - url: https://waffo.com description: Sandbox API (auto-signed via waffo.com signing proxy) 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 resume description: > Revoke a scheduled cancellation before it takes effect, so that the subscription keeps renewing. The next billing date stays unchanged. - 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/create: post: tags: - Order create summary: Create new order description: >- Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement operationId: orderCreate requestBody: content: application/json: schema: $ref: '#/components/schemas/AcqOrderCreateRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseAcqOrderCreatedResponse' components: schemas: AcqOrderCreateRequest: type: object properties: paymentRequestId: type: string description: >- Payment request id sent from Merchant. It will also be used for idempotent check. x-gen: NANOID maxLength: 32 minLength: 0 merchantOrderId: type: string description: Merchant order id x-gen: NANOID maxLength: 64 minLength: 0 orderCurrency: type: string description: Merchant order currency example: IDR maxLength: 12 minLength: 0 orderAmount: type: string description: >- Order amount excluding tax (order currency). Required unless you provide the tax-inclusive total via orderAmountInclTax instead example: 10 maxLength: 24 minLength: 0 promotionInfo: $ref: '#/components/schemas/AcqOrderCreateRequest.PromotionInfo' description: Promotion info for coupon marketing and internal amount adjustment userCurrency: type: string description: >- User payment currency. This is needed when merchant order currency is NOT the same as user payment currency example: IDR maxLength: 12 minLength: 0 orderDescription: type: string description: Order description information example: replace order desc..., maxLength: 128 minLength: 0 orderRequestedAt: type: string format: date-time description: Merchant-side request time x-gen: DATETIME_ISO orderExpiredAt: type: string format: date-time description: >- The order expiry time set by merchant. If not set, the default merchant contract expiry time will be used successRedirectUrl: type: string description: >- The address of the merchant page to redirect to after successful payment. If no value is provided, it will stay on the cashier page after successful payment. Required for x402 Waffo-hosted payment (x402Info.x402Request = true and x402Info.paymentSignatureHeader not provided): the Agent is redirected back to this address once the payment is settled, so the order is rejected when it is missing. example: https://merchant-success-redirecturl.com maxLength: 1024 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: 1024 minLength: 0 cancelRedirectUrl: type: string description: >- The address of the merchant page to redirect to when user cancels the payment example: https://merchant-cancel-url.com maxLength: 512 minLength: 0 notifyUrl: type: string description: >- The callback address to notify the merchant after the payment is completed / failed example: https://merchant-notify-url.com maxLength: 1024 minLength: 0 extendInfo: type: string description: 'Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} ' maxLength: 128 minLength: 0 merchantInfo: $ref: '#/components/schemas/AcqOrderCreateRequest.MerchantInfo' description: Merchant info userInfo: $ref: '#/components/schemas/AcqOrderMerchantUserInfo' description: User info goodsInfo: $ref: '#/components/schemas/AcqOrderGoodsInfo' description: Merchant goods information paymentInfo: $ref: '#/components/schemas/AcqOrderPaymentInfo' description: Payment information brandInfo: $ref: '#/components/schemas/BrandInfo' description: Brand display information for cashier cardInfo: $ref: '#/components/schemas/AcqCardInfo' description: >- Card data info (optional). Pass raw card data directly in the API (requires PCI DSS certification), or pass only threeDsDecision without any card field. example: null paymentTokenData: type: string description: >- User's ApplePay / GooglePay payment token. It is only required when Merchant choose to integrate with ApplePay / GooglePay frontend directly and pass in the encrypted payment token for Waffo to process the payment maxLength: 8192 minLength: 0 riskData: $ref: '#/components/schemas/AcqOrderRiskData' x402Info: $ref: '#/components/schemas/X402Info' description: >- x402 stablecoin payment info. x402Info.x402Request=true marks an x402 payin; mode① carries the Agent signature in x402Info.paymentSignatureHeader. taxInfo: $ref: '#/components/schemas/AcqOrderCreateRequest.MerchantTaxInfo' description: >- Merchant tax input (order currency). Provide orderAmountInclTax alone for a tax-inclusive total, or together with the top-level orderAmount and taxCountry when reporting both net and gross prices addressInfo: $ref: '#/components/schemas/AcqOrderAddressInfo' description: Address Information required: - merchantInfo - merchantOrderId - notifyUrl - orderCurrency - orderDescription - orderRequestedAt - paymentInfo - paymentRequestId - userInfo ResponseAcqOrderCreatedResponse: type: object description: response data properties: code: type: string example: 0 msg: type: string example: success data: $ref: '#/components/schemas/AcqOrderCreatedResponse' AcqOrderCreateRequest.PromotionInfo: type: object description: Promotion info for coupon marketing and internal amount adjustment properties: promotionCode: type: string description: >- Promotion code for coupon marketing. The merchant or Cashier can pass this code to let Acquiring apply the matched promotion/coupon and recalculate the payable order amount. Mutually exclusive with couponId maxLength: 64 minLength: 0 couponId: type: string description: >- Coupon instance id for coupon marketing. The merchant can pass a specific coupon id to let Acquiring apply that coupon directly and recalculate the payable order amount. Mutually exclusive with promotionCode maxLength: 64 minLength: 0 AcqOrderCreateRequest.MerchantInfo: type: object description: Merchant info properties: merchantId: type: string default: '1000000201' 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 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 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 AcqCardInfo: type: object description: > Card data info (optional). It supports two use cases: (1) pass in raw card data directly in the API — this requires the Merchant to have PCI DSS certification, and the fields cardNumber / cardExpiryYear / cardExpiryMonth / cardCvv / cardHolderName must then all be provided together as a group; (2) pass only `threeDsDecision` (without any card field) to convey a 3DS decision. properties: cardNumber: type: string description: >- User's card number. Optional; required as a group when passing raw card data — provide all of cardNumber / cardExpiryYear / cardExpiryMonth / cardCvv / cardHolderName together. maxLength: 24 minLength: 14 cardExpiryYear: type: integer format: int32 description: >- User's card expiry year, the format is four digits. For example 2025. Optional; required as a group when passing raw card data (see cardNumber). minimum: 2024 cardExpiryMonth: type: integer format: int32 description: >- User's card expiry month, the format is two digits. For example 10 (October). Optional; required as a group when passing raw card data (see cardNumber). maximum: 12 minimum: 1 cardCvv: type: string description: >- User's card cvv number. Optional; required as a group when passing raw card data (see cardNumber). maxLength: 4 minLength: 3 cardHolderName: type: string description: >- User's card holder name. Optional; required as a group when passing raw card data (see cardNumber). maxLength: 128 minLength: 0 threeDsDecision: type: string description: > Merchant's 3DS decision. Can be provided ALONE (without any raw card field) to influence 3DS while the card is collected elsewhere (cashier / AP / GP / saved token). Only effective for card / ApplePay / GooglePay CIT payments (ignored for other pay methods and for MIT). The following 3DS Decision are supported: - 3DS_FORCE - NO_3DS However, the eventual 3DS decision is also subject to Waffo's risk decision. maxLength: 12 minLength: 0 AcqOrderRiskData: type: object description: riskData 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) maxLength: 128 minLength: 0 userDisplayName: type: string description: Merchant user display name maxLength: 128 minLength: 0 userRegistrationIp: type: string description: Merchant user registration IP address example: 252.13.13.26 maxLength: 24 minLength: 0 userLastSeenIp: type: string description: Merchant user last login IP address example: 252.10.10.20 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 time purchase: Yes / No' example: 'No' maxLength: 8 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 AcqOrderCreateRequest.MerchantTaxInfo: type: object properties: taxCountry: type: string description: >- Tax country (billing country). Required and permitted only when both orderAmount and orderAmountInclTax are provided example: PHL orderAmountInclTax: type: string description: >- Tax-inclusive order total (order currency). Provide alone for a tax-inclusive price, or together with orderAmount (tax is then inclusive − exclusive) example: 112 maxLength: 24 minLength: 0 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 AcqOrderCreatedResponse: type: object properties: paymentRequestId: type: string description: Payment request id sent from Merchant. merchantOrderId: type: string description: Merchant order id acquiringOrderId: type: string description: Waffo acquiring order Id orderStatus: type: string description: >- Order status **PAY_IN_PROGRESS** -(merchant order is accepted, and user is in the process of payment) **AUTHORIZATION_REQUIRED** (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction) **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) 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 x402Info: $ref: '#/components/schemas/X402Info' description: >- x402 stablecoin payment info. Mode① echoes x402Request / paymentSignatureHeader and adds x402Response (base64 SettlementResponse) when orderStatus = PAY_SUCCESS. required: - acquiringOrderId - merchantOrderId - orderStatus - paymentRequestId ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.