> ## 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://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/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: Merchant order amount example: 10 maxLength: 24 minLength: 0 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. example: https://merchant-success-redirecturl.com maxLength: 512 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: 512 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: 256 minLength: 0 extendInfo: type: string description: 'Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} ' maxLength: 128 minLength: 0 merchantInfo: $ref: '#/components/schemas/create.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. It is only required when Merchant wants to pass in card data directly in API (note: Merchant needs to have PCI DSS certification) 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' addressInfo: $ref: '#/components/schemas/AcqOrderAddressInfo' description: Address Information innerCardData: $ref: '#/components/schemas/WaffoTokenCardData' required: - merchantInfo - merchantOrderId - notifyUrl - orderAmount - orderCurrency - orderDescription - orderRequestedAt - paymentInfo - paymentRequestId - userInfo ResponseAcqOrderCreatedResponse: type: object description: response data properties: code: type: string msg: type: string data: $ref: '#/components/schemas/AcqOrderCreatedResponse' create.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 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 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 info properties: cardNumber: type: string description: 'User''s card number ' maxLength: 24 minLength: 14 cardExpiryYear: type: integer format: int32 description: >- User's card expiry year, the format is four digits. For example 2025 minimum: 2024 cardExpiryMonth: type: integer format: int32 description: >- User's card expiry year, the format is two digits. For example 10 (October) maximum: 12 minimum: 1 cardCvv: type: string description: 'User''s card cvv number ' maxLength: 4 minLength: 3 cardHolderName: type: string description: 'User''s card holder name ' maxLength: 128 minLength: 0 threeDsDecision: type: string description: > Merchant's 3DS decision. Merchant can provide its own 3DS decision. The following 3DS Decision are supported: + - 3DS_FORCE - 3DS_ATTEMPT - NO_3DS However, the eventual 3DS decision is also subject to Waffo's risk decision. maxLength: 12 minLength: 0 required: - cardCvv - cardExpiryMonth - cardExpiryYear - cardHolderName - cardNumber 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 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 WaffoTokenCardData: type: object properties: cardBinDataList: type: array items: $ref: '#/components/schemas/CardBinData' maskedCardInfo: type: string cardBin: type: string cardExpiry: type: string 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) } ActionData is for those Merchants who want to build their own Cashier Page for their users, without using Waffo's cashier page required: - acquiringOrderId - merchantOrderId - orderStatus - paymentRequestId CardBinData: type: object properties: cardBin: type: string description: 卡BIN 卡号前6或前8位 cardScheme: type: string description: VISA / MASTERCARD / JCB etc cardBrand: type: string description: 卡品牌 MASTERO etc cardType: type: string description: CREDIT_CARD / DEBIT_CARD / PREPAID_CARD / COMBO_CARD cardTypeList: type: array description: >- CREDIT_CARD / DEBIT_CARD / PREPAID_CARD，当cardType = COMBO_CARD时，卡类型列表会给出2种类型（CREDIT_CARD + DEBIT_CARD） items: type: string subCardType: type: string description: >- 卡子类型，标准化后的子卡类型 CLASSIC/GOLD/PLATINUM/SIGNATURE/INFINITE/BUSINESS/CORPORATE 等 cardIssuerName: type: string description: 发卡行 cardIssuerCode: type: string description: 发卡行编号 cardIssueCountryCode: type: string description: >- 发卡行国家编号 Follow ISO_3166-1_alpha-3 Standard https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 cardIssueCountryCodeList: type: array description: 发卡行国家列表，同一个卡BIN可能在多个国家发行 items: type: string status: type: string description: VALID - 有效卡BIN INVALID - 无效卡BIN extendedInfo: type: string description: 扩展信息，json格式字符串 ````