{ "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)" } ], "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\nWaffo 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).\n" }, { "name": "Subscription change inquiry", "description": "This API allows merchants to query the status of a subscription change (upgrade/downgrade) request.\n此接口允许商户查询订阅升降级请求的状态。\n" }, { "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.\n\n此接口允许商户升级或降级用户的订阅计划。升降级请求将基于原订阅创建新订阅，并将原订阅的剩余金额应用到新订阅中。\n" }, { "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\n" }, { "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/wallet/inquiry": { "post": { "tags": [ "Wallet inquiry" ], "summary": "Wallet inquiry", "description": "Query on-chain wallet / receiving address (network/asset/payTo) for x402 stablecoin payin", "operationId": "walletInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletInquiryReq" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseWalletInquiryResponse" } } } } } } }, "/api/v1/subscription/update": { "post": { "tags": [ "Subscription update" ], "summary": "Subscription update", "operationId": "subscriptionUpdate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseSubscriptionUpdateResponse" } } } } }, "x-order": "7" } }, "/api/v1/subscription/manage": { "post": { "tags": [ "Subscription manage" ], "summary": "Subscription manage", "operationId": "subscriptionManage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionManageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseSubscriptionManageResponse" } } } } }, "x-order": "4" } }, "/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" } } } } }, "x-order": "2" } }, "/api/v1/subscription/create": { "post": { "tags": [ "Subscription create" ], "summary": "Create Subscription", "description": "Note: For certain Pay Methods, some optional fields are required. Kindly refer to Section Specific Pay Method Requirement", "operationId": "createSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAcqSubscriptionCreateResponse" } } } } }, "x-order": "1" } }, "/api/v1/subscription/change": { "post": { "tags": [ "Subscription change" ], "summary": "Subscription change", "operationId": "changeSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseSubscriptionChangeResponse" } } } } }, "x-order": "5" } }, "/api/v1/subscription/change/inquiry": { "post": { "tags": [ "Subscription change inquiry" ], "summary": "Subscription change inquiry", "operationId": "subscriptionChangeInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionChangeInquiryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseSubscriptionChangeInquiryResponse" } } } } }, "x-order": "6" } }, "/api/v1/subscription/cancel": { "post": { "tags": [ "Subscription cancel" ], "summary": "Subscription cancel", "operationId": "merchantCancel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCancelRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseSubscriptionCancelResponse" } } } } }, "x-order": "3" } }, "/api/v1/refund/inquiry": { "post": { "tags": [ "Refund inquiry" ], "summary": "Refund inquiry", "operationId": "refundInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcqOrderRefundInquiryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAcqOrderRefundInquiry" } } } } }, "x-order": "5" } }, "/api/v1/payout/inquiry": { "post": { "tags": [ "Payout inquiry" ], "summary": "Payout inquiry", "operationId": "payoutOrderQuery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponsePayoutOrderData" } } } } }, "x-order": "2" } }, "/api/v1/payout/create": { "post": { "tags": [ "Payout create" ], "summary": "Payout create", "operationId": "payoutOrderSubmit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponsePayoutOrderData" } } } } }, "x-order": "1" } }, "/api/v1/paymethodconfig/inquiry": { "post": { "tags": [ "Pay Method Config Inquiry" ], "summary": "Pay Method Config Inquiry", "operationId": "payMethodConfigInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayMethodConfigInquiryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponsePayMethodConfigInquiryResponse" } } } } }, "x-order": "7" } }, "/api/v1/order/refund": { "post": { "tags": [ "Order refund" ], "summary": "Order refund", "operationId": "orderRefund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcqOrderRefundRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAcqOrderRefundResponse" } } } } }, "x-order": "4" } }, "/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" } } } } }, "x-order": "2" } }, "/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" } } } } }, "x-order": "1" } }, "/api/v1/order/capture": { "post": { "tags": [ "Order capture" ], "summary": "Order capture", "operationId": "orderCapture", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCaptureRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseOrderCaptureResponse" } } } } }, "x-order": "8" } }, "/api/v1/order/cancel": { "post": { "tags": [ "Order cancel" ], "summary": "Order cancel", "operationId": "orderCancel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcqOrderCancelRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAcqOrderCancelResponse" } } } } }, "x-order": "3" } }, "/api/v1/merchantconfig/inquiry": { "post": { "tags": [ "Merchant config inquiry" ], "summary": "Merchant Config inquiry", "operationId": "merchantConfigInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcqMerchantConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseAcqMerchantConfigInquiryResponse" } } } } }, "x-order": "6" } }, "/api/v1/fraud-report/list": { "post": { "tags": [ "Reported Fraud list" ], "summary": "Reported Fraud list", "description": "Query the fraud reports the card schemes raised against your transactions, filtered by fraud report date, card scheme and acquiring order Id. \nReported fraud is the card scheme's own fraud signal and is independent of chargebacks: a reported transaction may never be charged back, and a chargeback may exist without a fraud report — use the Chargeback list API for chargebacks. \nThe query range must not exceed 3 months.", "operationId": "fraudReportList", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudReportListRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseApiPageResponseFraudReportResponse" } } } } }, "x-order": "1" } }, "/api/v1/chargeback/update": { "post": { "tags": [ "Chargeback update" ], "summary": "Chargeback update", "description": "Submit defense evidence in First Cycle, or defend the case in Second Cycle. Note: in First Cycle at least one evidence file is required, supplied through message.documents or evidence.othersFile; in Second Cycle the call itself defends the case and evidence is not accepted. On success the status becomes UNDER_REVIEW.", "operationId": "chargebackUpdate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackUpdateEvidenceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseChargebackDetailResponse" } } } } }, "x-order": "3" } }, "/api/v1/chargeback/list": { "post": { "tags": [ "Chargeback list" ], "summary": "Chargeback list", "description": "Query chargebacks by creation time range, status and life cycle. Note: this API does not return the message and evidence objects; use Chargeback inquiry to retrieve them.", "operationId": "chargebackList", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackListRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseApiPageResponseChargebackQueryResponse" } } } } }, "x-order": "2" } }, "/api/v1/chargeback/inquiry": { "post": { "tags": [ "Chargeback inquiry" ], "summary": "Chargeback inquiry", "description": "Query a single chargeback by chargebackId or originalOrderId. Note: when the original order has more than one chargeback, for example after escalation to Second Cycle, query by chargebackId.", "operationId": "chargebackInquiry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackInquiryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseChargebackDetailResponse" } } } } }, "x-order": "1" } }, "/api/v1/chargeback/file/upload": { "post": { "tags": [ "Chargeback file upload" ], "summary": "Chargeback file upload", "description": "Upload an evidence file and obtain the fileId used by the Chargeback update API. Send the request as multipart/form-data. Note: this API is authenticated by X-API-KEY only and does not participate in RSA signing; the response carries no X-SIGNATURE. The merchantId must match the merchant bound to the API key.", "operationId": "chargebackFileUpload", "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "merchantId", "in": "query", "description": "Merchant id assigned by Waffo. Sent as a form field or query parameter, not inside a JSON body", "required": true, "schema": { "type": "string" }, "example": 1000000201 } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The binary data of the evidence file. The multipart part name must be file. Supported formats: JPG, JPEG, PNG and PDF. Maximum size: 10 MB" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseChargebackFileUploadResponse" } } } } }, "x-order": "1" } }, "/api/v1/chargeback/accept": { "post": { "tags": [ "Chargeback accept" ], "summary": "Chargeback accept", "description": "Accept the chargeback. The amount and fee were already debited when the chargeback was created, so accepting does not trigger a further debit — the case is closed and the merchant is not refunded. Note: this action is irreversible — no further evidence can be submitted afterwards, and an ACCEPTED notification is pushed to the configured chargeback notify URL.", "operationId": "chargebackAccept", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackAcceptRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ResponseChargebackDetailResponse" } } } } }, "x-order": "4" } }, "/api/v1/chargeback/file/download": { "get": { "tags": [ "Chargeback file download" ], "summary": "Chargeback file download", "description": "Download a previously uploaded evidence file. On success the API returns HTTP 302 Found with a Location header pointing to a time-limited pre-signed URL; the file content is served from that URL, so the HTTP client must follow redirects (curl requires -L). This API does not stream the file bytes directly, does not participate in RSA signing, and returns no X-SIGNATURE.", "operationId": "chargebackFileDownload", "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "merchantId", "in": "query", "description": "Merchant id assigned by Waffo", "required": true, "schema": { "type": "string" }, "example": 1000000201 }, { "name": "fileId", "in": "query", "description": "The unique ID of the file returned by the Chargeback file upload API. Must be URL-encoded, because the value contains a slash", "required": true, "schema": { "type": "string" }, "example": "1766043193910/receipt.pdf" } ], "responses": { "200": { "description": "OK" } }, "x-order": "2" } } }, "components": { "schemas": { "WalletInquiryReq": { "type": "object", "description": "Wallet / on-chain receiving address inquiry request", "properties": { "paymentRequestId": { "type": "string", "description": "Payment request id sent from Merchant, same value as order/create. Used for correlation and idempotency.", "maxLength": 32, "minLength": 0 }, "merchantInfo": { "$ref": "#/components/schemas/WalletInquiryReq.MerchantInfo", "description": "Merchant info" }, "orderCurrency": { "type": "string", "description": "Order currency for the resource pricing. Phase 1 supports USDC only (same-currency USDC→USDC).", "example": "USDC", "maxLength": 12, "minLength": 0 } }, "required": [ "merchantInfo", "orderCurrency", "paymentRequestId" ] }, "WalletInquiryReq.MerchantInfo": { "type": "object", "description": "Merchant info", "properties": { "merchantId": { "type": "string", "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" ] }, "ResponseWalletInquiryResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/WalletInquiryResponse" } } }, "WalletInquiryResponse": { "type": "object", "description": "Wallet / on-chain receiving address inquiry response", "properties": { "network": { "type": "string", "description": "CAIP-2 network id. Phase 1 Base mainnet eip155:8453.", "example": "eip155:8453" }, "asset": { "type": "string", "description": "On-chain token contract address for the network + currency (Base + USDC → USDC contract).", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "payTo": { "type": "string", "description": "Waffo / platform receiving wallet address. Not supplied by merchant/Agent.", "example": "0x..." } } }, "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" } } }, "SubscriptionUpdateRequest": { "type": "object", "description": "Provide subscriptionRequest or subscriptionId", "properties": { "subscriptionRequest": { "type": "string", "description": "Merchant subscription request ID (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 }, "amount": { "type": "string", "description": "Merchant subscription amount, for example 100. At least one of amount, productInfo.trialPeriodAmount, and productInfo.scheduledAmounts must be provided.", "example": 100.0, "maxLength": 24, "minLength": 0 }, "productInfo": { "$ref": "#/components/schemas/SubscriptionUpdateRequest.ProductInfo", "description": "Subscription product info" }, "topupInfo": { "$ref": "#/components/schemas/SubscriptionUpdateRequest.TopupInfo", "description": "Seat add-on top-up info. When provided, this update becomes a seat add-on: charge the top-up amount immediately and adjust the amount above from the next period." } } }, "SubscriptionUpdateRequest.ProductInfo": { "type": "object", "description": "Subscription product information", "properties": { "trialPeriodAmount": { "type": "string", "description": "The subscription amount that user pay during the trial period, for example 8000\nThe amount shall >= 0\nIf the value is empty, there is no trial period\nAt least one of amount, productInfo.trialPeriodAmount, and productInfo.scheduledAmounts must be provided.\n", "example": 0.0, "maxLength": 24, "minLength": 0 }, "scheduledAmounts": { "type": "array", "description": "Scheduled amount list for each period. Use scheduled amounts when a merchant wants to set different amounts for each subscription period. At least one of amount, productInfo.trialPeriodAmount, and productInfo.scheduledAmounts must be provided.", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } } } }, "SubscriptionUpdateRequest.TopupInfo": { "type": "object", "description": "Seat add-on top-up info", "properties": { "topupRequest": { "type": "string", "description": "Idempotency key for this top-up, for example mimo-topup-001. Allowed characters: letters, digits and hyphen.", "example": "mimo-topup-001", "maxLength": 32, "minLength": 0 }, "topupAmount": { "type": "string", "description": "Top-up amount to charge for the current period, calculated by the merchant. Must be greater than 0.", "example": 30.0, "maxLength": 24, "minLength": 0 }, "description": { "type": "string", "description": "Order description of the top-up charge, shown on cashier and billing.", "example": "Seat add-on 3 seats", "maxLength": 256, "minLength": 0 }, "orderExpiredAt": { "type": "string", "format": "date-time", "description": "Top-up order expiry time (cashier session deadline) in ISO8601. If empty, defaults to now plus the configured minutes.", "example": "2026-08-18T10:30:00+08:00" } } }, "ResponseSubscriptionUpdateResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SubscriptionUpdateResponse" } } }, "SubscriptionUpdateResponse": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Waffo subscription Id" }, "subscriptionRequest": { "type": "string", "description": "Subscription request id sent from Merchant" }, "previousTrialPeriodAmount": { "type": "string", "description": "Merchant subscription previous trail amount, for example 10" }, "newTrialPeriodAmount": { "type": "string", "description": "Merchant subscription new trail amount after update, , for example 8" }, "previousAmount": { "type": "string", "description": "Merchant subscription previous amount, for example 100" }, "newAmount": { "type": "string", "description": "Merchant subscription new amount after update, for example 90" }, "previousScheduledAmounts": { "type": "array", "description": "Previous scheduled amount list for each period", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } }, "newScheduledAmounts": { "type": "array", "description": "New scheduled amount list for each period", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } }, "nextEffectivePeriod": { "type": "string", "description": "The next period number when the new amount takes effect" }, "topupInfo": { "$ref": "#/components/schemas/SubscriptionUpdateResponse.TopupInfo", "description": "Seat add-on top-up result, present only when the request carries topupInfo" } } }, "SubscriptionUpdateResponse.TopupInfo": { "type": "object", "description": "Seat add-on top-up result", "properties": { "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order id of the top-up charge" }, "topupRequest": { "type": "string", "description": "Idempotency key echoed from request" }, "topupAmount": { "type": "string", "description": "Top-up amount charged for the current period" }, "topupStatus": { "type": "string", "description": "Top-up charge order status, for example AUTHORIZATION_REQUIRED" }, "topupAction": { "type": "string", "description": "Structured order action, merchant redirects user to cashier with it" } } }, "SubscriptionManageRequest": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "Waffo subscription Id ", "maxLength": 64, "minLength": 0 }, "subscriptionRequest": { "type": "string", "description": "Subscription request id sent from Merchant. It will also be used for idempotent check. ", "maxLength": 64, "minLength": 0 } } }, "ResponseSubscriptionManageResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SubscriptionManageResponse" } } }, "SubscriptionManageResponse": { "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": "The subscription ID assigned by Waffo" }, "managementUrl": { "type": "string", "description": "The generated management url for this subscription" }, "expiredAt": { "type": "string", "description": "The expiration time of the management url (ISO 8601 format,UTC+0 timezone)" }, "subscriptionStatus": { "type": "string", "description": "Subscription status\n- AUTHORIZATION_REQUIRED (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction)\n- IN_PROGRESS (user is in progress to confirm the subscription)\n- ACTIVE \n- CLOSE (due to timeout or failed)\n- MERCHANT_CANCELLED\n- USER_CANCELLED\n- CHANNEL_CANCELLED\n- EXPIRED\n- PLATFORM_CANCELLED\n" } } }, "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\n- 0 (meaning payment details are not required)\n- 1 (meaning payment details are required)\n", "example": 1 } } }, "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\n- PAY_SUCCESS \n- ORDER_CLOSE (payment failed)\n" }, "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" } } } }, "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\n- AUTHORIZATION_REQUIRED (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction)\n- IN_PROGRESS (user is in progress to confirm the subscription)\n- ACTIVE \n- CLOSE (due to timeout or failed)\n- MERCHANT_CANCELLED\n- USER_CANCELLED\n- CHANNEL_CANCELLED\n- EXPIRED\n- PLATFORM_CANCELLED\n" }, "subscriptionAction": { "type": "string", "description": "When subscriptionStatus = AUTHORIZATION_REQUIRED, merchant follow the following: \n“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 {\n\"orderFailedCode\": \"XXX\",\n\"orderFailedDescription\"\" \"XXX\"\n}\n" }, "subscriptionManagementUrl": { "type": "string", "description": "It refers to the subscription management page for users on the merchant side.\n" }, "extendInfo": { "type": "string", "description": "Reserved. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"} \n" }, "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.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" } } }, "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\n(for compliance and risk management purpose)\n" }, "appName": { "type": "string", "description": "app package name, for example com.example.app123\n(for compliance and risk management purpose)\n" }, "skuName": { "type": "string", "description": "Goods sku name" }, "goodsUniquePrice": { "type": "string", "description": "Goods price" }, "goodsQuantity": { "type": "integer", "format": "int32", "description": "Goods quantity" } } }, "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.PaymentInfo": { "type": "object", "description": "Payment information", "properties": { "productName": { "type": "string", "description": "Payment product: \n- SUBSCRIPTION\n- MINI_PROGRAM_SUBSCRIPTION\nMerchant can view the signed contract product via Waffo Merchant portal\n", "maxLength": 32, "minLength": 0 }, "payMethodType": { "type": "string", "description": "Payment method type. e.g. \n- EWALLET\n- CREDITCARD\n- DEBITCARD\nMerchant 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\nIf 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\n", "maxLength": 16, "minLength": 0 }, "payMethodName": { "type": "string", "description": "The actual payment method. e.g. DANA\nIf payMethodName is provided, the payment request will be processed using this pay method directly.\nIf 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\n", "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\nEMAIL\nPHONE_NO\nACCOUNT_ID\n", "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\nThe user access token can be obtained from mini program API\n", "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.\n", "maxLength": 3, "minLength": 0 } }, "required": [ "payMethodName", "productName" ] }, "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:\n- DAILY\n- WEEKLY\n- MONTHLY\n", "maxLength": 12, "minLength": 0 }, "periodInterval": { "type": "string", "description": "Period interval. For example 1\nIf the period type is DAILY, the period interval is between 1-365\nIf the period type is WEEKLY, the period interval is between 1-4\nIf 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\nFor 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\n", "maxLength": 12, "minLength": 0 }, "numberOfPeriod": { "type": "string", "description": "Specify after how many deduction period, the subscription will end. For example 3\nIf the value is empty, it means the subscription has no defined end period\nThe subscription periods shall not exceed 3 years in total\n", "maxLength": 24, "minLength": 0 }, "trialPeriodAmount": { "type": "string", "description": "The subscription amount that user pay during the trial period, for example 8000\nThe amount shall >= 0\n", "maxLength": 24, "minLength": 0 }, "numberOfTrialPeriod": { "type": "string", "description": "Specify after how many periods, the trial will end. For example 1\n", "maxLength": 12, "minLength": 0 }, "trialPeriodType": { "type": "string", "description": "Subscription product period type:\n- DAILY\n- WEEKLY\n- MONTHLY\nThis field is optional when a trial period is configured. If omitted, the system will use periodType value by default.\n", "maxLength": 12, "minLength": 0 }, "trialPeriodInterval": { "type": "string", "description": "Represents the interval unit of the trial period. Same definition and behavior as periodInterval.\nIf the period type is DAILY, the period interval is between 1-365\nThis field is optional when a trial period is configured. If omitted, the system will use periodInterval value by default..\n", "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.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" } } }, "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" ] }, "AcqSubscriptionCreateRequest": { "type": "object", "properties": { "subscriptionRequest": { "type": "string", "description": "Subscription request id sent from Merchant. It will also be used for idempotent check.", "x-gen": "NANOID", "maxLength": 32, "minLength": 0 }, "merchantSubscriptionId": { "type": "string", "description": "Merchant subscription plan ID assigned to this user", "example": "PLAN_001", "maxLength": 64, "minLength": 0 }, "currency": { "type": "string", "description": "Merchant subscription currency, for example USD", "example": "USD", "maxLength": 12, "minLength": 0 }, "amount": { "type": "string", "description": "Merchant subscription amount, for example 100", "example": 100.0, "maxLength": 24, "minLength": 0 }, "promotionInfo": { "$ref": "#/components/schemas/SubscriptionPromotionInfo", "description": "Promotion info for coupon marketing" }, "productInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.ProductInfo", "description": "Subscription product info" }, "userCurrency": { "type": "string", "description": "User payment currency. This is needed when merchant order currency is NOT the same as user payment currency", "maxLength": 12, "minLength": 0 }, "merchantInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.MerchantInfo", "description": "Merchant info\n" }, "userInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.UserInfo", "description": "User info\n" }, "goodsInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.GoodsInfo", "description": "Merchant goods information\n" }, "addressInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.AddressInfo", "description": "Address Information\n" }, "brandInfo": { "$ref": "#/components/schemas/BrandInfo", "description": "Brand display information for cashier" }, "paymentInfo": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.PaymentInfo", "description": "Payment information\n", "example": { "productName": "SUBSCRIPTION", "payMethodType": "APPLEPAY,CREDITCARD,DEBITCARD,GOOGLEPAY" } }, "requestedAt": { "type": "string", "format": "date-time", "description": "Merchant-side request time", "x-gen": "DATETIME_ISO" }, "startTime": { "type": "string", "format": "date-time", "description": "Specified subscription start time. If not provided, the subscription starts immediately.", "x-gen": "DATETIME_ISO" }, "successRedirectUrl": { "type": "string", "description": "The address of the merchant page to redirect to after successful subscription payment. \nIf no value is provided, it will stay on the cashier page after successful payment. \n", "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\n", "example": "https://merchant-failed-redirecturl.com", "maxLength": 1024, "minLength": 0 }, "notifyUrl": { "type": "string", "description": "The callback address to notify the merchant after the subscription is completed / failed\n", "example": "https://merchant-notify-url.com", "maxLength": 1024, "minLength": 0 }, "cancelRedirectUrl": { "type": "string", "description": "User will be redirected to this page if user choose to cancel and not continue the payment\n", "example": "https://merchant-cancel-url.com", "maxLength": 512, "minLength": 0 }, "riskData": { "$ref": "#/components/schemas/AcqSubscriptionCreateRequest.RiskData" }, "subscriptionManagementUrl": { "type": "string", "description": "It refers to the subscription management page for users on the merchant side.\n", "example": "https://merchant.com/subscription/manage", "maxLength": 256, "minLength": 0 }, "extendInfo": { "type": "string", "description": "Reserved. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"} \n", "maxLength": 256, "minLength": 0 }, "orderExpiredAt": { "type": "string", "format": "date-time", "description": "The order expiry time set by merchant. User is required to input payment data on Waffo cashier page prior to merchant's order expiry time. \nIf not provided, the default is 4 hours\n" } }, "required": [ "amount", "currency", "merchantInfo", "merchantSubscriptionId", "notifyUrl", "productInfo", "requestedAt", "subscriptionManagementUrl", "subscriptionRequest", "userInfo" ] }, "AcqSubscriptionCreateRequest.AddressInfo": { "type": "object", "description": "Address information", "properties": { "address": { "type": "string", "description": "Shipping address\n", "maxLength": 256, "minLength": 0 }, "city": { "type": "string", "description": "Shipping city\n", "maxLength": 32, "minLength": 0 }, "region": { "type": "string", "description": "Shipping region / state / province\n", "maxLength": 32, "minLength": 0 }, "postcode": { "type": "string", "description": "Shipping postcode\n", "maxLength": 16, "minLength": 0 }, "addressCountryCode": { "type": "string", "description": "Shipping country code\n", "maxLength": 16, "minLength": 0 } } }, "AcqSubscriptionCreateRequest.GoodsInfo": { "type": "object", "description": "Goods information", "properties": { "goodsId": { "type": "string", "description": "Goods item id\n", "example": "GOODS001", "maxLength": 32, "minLength": 0 }, "goodsName": { "type": "string", "description": "Goods item name\n", "example": "Premium Subscription Plan", "maxLength": 64, "minLength": 0 }, "goodsCategory": { "type": "string", "description": "Goods category\n", "maxLength": 32, "minLength": 0 }, "goodsUrl": { "type": "string", "description": "Goods URL from merchant website, for example https://www.merchant123.com/goods123\n (for compliance and risk management purpose)\n", "maxLength": 128, "minLength": 0 }, "appName": { "type": "string", "description": "app package name, for example com.example.app123\n (for compliance and risk management purpose)\n", "maxLength": 32, "minLength": 0 }, "skuName": { "type": "string", "description": "Goods sku name\n", "maxLength": 32, "minLength": 0 }, "goodsUniquePrice": { "type": "string", "description": "Goods price\n", "maxLength": 16, "minLength": 0 }, "goodsQuantity": { "type": "integer", "format": "int32", "description": "Goods quantity\n" } }, "required": [ "goodsId", "goodsName" ] }, "AcqSubscriptionCreateRequest.MerchantInfo": { "type": "object", "description": "Merchant information", "properties": { "merchantId": { "type": "string", "description": "Merchant id assigned by Waffo\n", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "subMerchantId": { "type": "string", "description": "Sub merchant id assigned by Waffo\n", "maxLength": 64, "minLength": 0 } }, "required": [ "merchantId" ] }, "AcqSubscriptionCreateRequest.PaymentInfo": { "type": "object", "description": "Payment information", "properties": { "productName": { "type": "string", "description": "Payment product: \n - SUBSCRIPTION\n - MINI_PROGRAM_SUBSCRIPTION\n Merchant can view the signed contract product via Waffo Merchant portal \n", "example": "SUBSCRIPTION", "maxLength": 32, "minLength": 0 }, "payMethodType": { "type": "string", "description": "Payment method type. e.g. \n - EWALLET\n - CREDITCARD\n - DEBITCARD\n 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\n 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\n Conditional (must be provided for card payments)\n", "example": "CREDITCARD,DEBITCARD,APPLEPAY,GOOGLEPAY", "maxLength": 256, "minLength": 0 }, "payMethodName": { "type": "string", "description": "The actual payment method. e.g. DANA\n If payMethodName is provided, the payment request will be processed using this pay method directly.\n 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\n Conditional (required for non-card payment methods)\n", "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\"} \n", "maxLength": 256, "minLength": 0 }, "payMethodUserAccountType": { "type": "string", "description": "User account type at the designated pay method\n EMAIL\n PHONE_NO\n ACCOUNT_ID\n", "maxLength": 24, "minLength": 0 }, "payMethodUserAccountNo": { "type": "string", "description": "User account number at the designated pay method\n", "maxLength": 64, "minLength": 0 }, "payMethodUserAccessToken": { "type": "string", "description": "User access token is required when using MINI_PROGRAM_SUBSCRIPTION product\n The user access token can be obtained from mini program API\n", "maxLength": 128, "minLength": 0 }, "cashierLanguage": { "type": "string", "description": "Merchant specify the cashier language. It follows IETF BCP 47 language tag\nThe 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\nFor example:\n- en-HK: English in Hong Kong\n- zh-Hant-HK: Traditional Chinese in Hong Kong\n- zh-Hans-HK: Simplified Chinese in Hong Kong\n", "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.\n A JSON-formatted string containing theme variables.\n These variables are injected into the UI rendering layer and override the default theme settings.\n This field must be a valid JSON string, not a plain object.\n Example: {\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\"}}\n" }, "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.\n", "maxLength": 3, "minLength": 0 } }, "required": [ "productName" ] }, "AcqSubscriptionCreateRequest.ProductInfo": { "type": "object", "description": "Subscription product information", "properties": { "description": { "type": "string", "description": "Subscription product description, often appearing to user when asking user's confirmation", "example": "Premium Monthly Subscription", "maxLength": 128, "minLength": 0 }, "periodType": { "type": "string", "description": "Subscription product period type:\n - DAILY\n - WEEKLY\n - MONTHLY\nYEARLY is not supported. For an annual subscription, set periodType to MONTHLY and periodInterval to 12.\n", "example": "MONTHLY", "maxLength": 12, "minLength": 0 }, "periodInterval": { "type": "string", "description": "Period interval. \nIf the period type is DAILY, the period interval is between 1-365\nIf the period type is WEEKLY, the period interval is between 1-4\nIf 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\nFor 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\n", "example": 1, "maxLength": 12, "minLength": 0 }, "numberOfPeriod": { "type": "string", "description": "Specify after how many deduction period, the subscription will end.\nThe value needs to be greater than 1. For example 3\nIf the value is empty, it means the subscription has no defined end period\nNote: The Dana subscription period shall not exceed three years in total.\n", "example": 12, "maxLength": 24, "minLength": 0 }, "trialPeriodAmount": { "type": "string", "description": "The subscription amount that user pay during the trial period, for example 8000\nThe amount shall >= 0\nIf the value is empty, there is no trial period\n", "example": 0.0, "maxLength": 24, "minLength": 0 }, "numberOfTrialPeriod": { "type": "string", "description": "Specify after how many periods, the trial will end. For example 1894\n", "example": 1, "maxLength": 12, "minLength": 0 }, "trialPeriodType": { "type": "string", "description": "Subscription product period type:\n- DAILY\n- WEEKLY\n- MONTHLY\nThis field is optional when a trial period is configured. If omitted, the system will use periodType value by default.\n", "example": "MONTHLY", "maxLength": 12, "minLength": 0 }, "trialPeriodInterval": { "type": "string", "description": "Represents the interval unit of the trial period. Same definition and behavior as periodInterval.\nIf the period type is DAILY, the period interval is between 1-365\nThis field is optional when a trial period is configured. If omitted, the system will use periodInterval value by default..\n", "example": 1, "maxLength": 12, "minLength": 0 }, "scheduledAmounts": { "type": "array", "description": "Scheduled amount list for each period", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } } }, "required": [ "description", "periodInterval", "periodType" ] }, "AcqSubscriptionCreateRequest.RiskData": { "type": "object", "description": "Risk data for compliance", "properties": { "userType": { "type": "string", "description": "Merchant user: Individual / Agent / Institution / Internal\n", "example": "Individual", "maxLength": 24, "minLength": 0 }, "userCategory": { "type": "string", "description": "Merchant user: Member / Non-Member\n", "example": "Member", "maxLength": 24, "minLength": 0 }, "userLegalName": { "type": "string", "description": "Merchant user legal name (or first name + last name)\n", "example": "John Doe", "maxLength": 128, "minLength": 0 }, "userDisplayName": { "type": "string", "description": "Merchant user display name\n", "example": "John", "maxLength": 128, "minLength": 0 }, "userRegistrationIp": { "type": "string", "description": "Merchant user registration IP address\n", "example": "192.168.1.1", "maxLength": 24, "minLength": 0 }, "userLastSeenIp": { "type": "string", "description": "Merchant user last login IP address\n", "example": "192.168.1.1", "maxLength": 24, "minLength": 0 }, "userIsNew": { "type": "string", "description": "Merchant user if he/she is a new user: Yes / No\n", "example": "No", "maxLength": 8, "minLength": 0 }, "userIsFirstPurchase": { "type": "string", "description": "Merchant user if this is his/her first purchase: Yes / No\n", "example": "No", "maxLength": 8, "minLength": 0 } } }, "AcqSubscriptionCreateRequest.UserInfo": { "type": "object", "description": "User information", "properties": { "userId": { "type": "string", "description": "Merchant User id. ", "example": "USER001", "maxLength": 64, "minLength": 0 }, "userEmail": { "type": "string", "description": "Merchant user email. This field is required.\nIf 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.\nYou can also contact Waffo to configure this fallback on your behalf; merchant authorization is required.\nAfter going live, pass the user's real email whenever possible.\nDo not use placeholder values such as `test` or share one email address across multiple users, because this may trigger risk controls.\n", "example": "USER001@examples.com", "maxLength": 64, "minLength": 0 }, "userTerminal": { "type": "string", "description": "Merchant user terminal type: \n- WEB (user is using a PC)\n- APP (user is using a Mobile Phone)\n", "maxLength": 32, "minLength": 0 }, "userPhone": { "type": "string", "description": "Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157\n", "example": "+62-08990013157", "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 }, "userCreatedAt": { "type": "string", "format": "date-time", "description": "Merchant user creation time" } }, "required": [ "userEmail", "userId" ] }, "BrandInfo": { "type": "object", "description": "Brand display information for cashier", "properties": { "cashierLogoUrl": { "type": "string", "description": " Merchant logo for cashier display.\n - It supports external URL from merchant, and the format starts with https://, and the recommended size is 40x40 px\n - It also supports the pre-created logo ID via https://dashboard.waffo.com/checkout/cashier-customization and the format starts with logo_\n", "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 } } }, "SubscriptionPromotionInfo": { "type": "object", "description": "Promotion info for subscription coupon marketing", "properties": { "promotionCode": { "type": "string", "description": "Promotion code for coupon marketing. Mutually exclusive with couponId", "maxLength": 64, "minLength": 0 }, "couponId": { "type": "string", "description": "Coupon instance id for coupon marketing. Mutually exclusive with promotionCode", "maxLength": 64, "minLength": 0 } } }, "AcqSubscriptionCreateResponse": { "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\n" }, "subscriptionStatus": { "type": "string", "description": "Subscription status\n- AUTHORIZATION_REQUIRED (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction)\n- IN_PROGRESS (user is in progress to confirm the subscription)\n- ACTIVE \n- CLOSE (due to timeout or failed)\n- MERCHANT_CANCELLED\n- USER_CANCELLED\n- CHANNEL_CANCELLED\n- EXPIRED\n- PLATFORM_CANCELLED\n" }, "subscriptionAction": { "type": "string", "description": "When subscriptionStatus = AUTHORIZATION_REQUIRED, merchant follow the following: \n“webUrl”: redirect user to this URL\n" } } }, "ResponseAcqSubscriptionCreateResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqSubscriptionCreateResponse" } } }, "SubscriptionChangeRequest": { "type": "object", "description": "Subscription change request", "properties": { "subscriptionRequest": { "type": "string", "description": "New subscription request id sent from Merchant. It will also be used for idempotent check.", "x-gen": "NANOID", "maxLength": 32, "minLength": 0 }, "merchantSubscriptionId": { "type": "string", "description": "New merchant subscription plan ID assigned to this user", "maxLength": 64, "minLength": 0 }, "promotionInfo": { "$ref": "#/components/schemas/SubscriptionPromotionInfo", "description": "Promotion info applied to the new subscription plan during upgrade or downgrade. When provided, Waffo applies the matched coupon to the new subscription amount." }, "originSubscriptionRequest": { "type": "string", "description": "Original subscription request id that needs to be changed", "example": "ORG_SUB_REQ_001", "maxLength": 32, "minLength": 0 }, "remainingAmount": { "type": "string", "description": "Remaining amount from the original subscription to be applied to the new subscription", "example": 50000.0, "maxLength": 24, "minLength": 0 }, "currency": { "type": "string", "description": "Subscription currency, for example USD", "example": "USD", "maxLength": 12, "minLength": 0 }, "userCurrency": { "type": "string", "description": "User payment currency. This is needed when merchant order currency is NOT the same as user payment currency", "maxLength": 12, "minLength": 0 }, "requestedAt": { "type": "string", "format": "date-time", "description": "Merchant-side request time", "x-gen": "DATETIME_ISO" }, "startTime": { "type": "string", "format": "date-time", "description": "Specified new subscription start time. If not provided, the new subscription starts immediately.", "x-gen": "DATETIME_ISO" }, "successRedirectUrl": { "type": "string", "description": "The address of the merchant page to redirect to after successful subscription change. If no value is provided, it will stay on the cashier page after successful payment.", "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", "maxLength": 1024, "minLength": 0 }, "notifyUrl": { "type": "string", "description": "The callback address to notify the merchant after the subscription change is completed / failed", "example": "https://merchant.com/notify", "maxLength": 1024, "minLength": 0 }, "cancelRedirectUrl": { "type": "string", "description": "User will be redirected to this page if user choose to cancel and not continue the payment", "maxLength": 512, "minLength": 0 }, "subscriptionManagementUrl": { "type": "string", "description": "It refers to the subscription management page for users on the merchant side.", "maxLength": 256, "minLength": 0 }, "extendInfo": { "type": "string", "description": "Reserved. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"}", "maxLength": 256, "minLength": 0 }, "orderExpiredAt": { "type": "string", "format": "date-time", "description": "The order expiry time set by merchant. User is required to input payment data on Waffo cashier page prior to merchant's order expiry time. If not provided, the default is 4 hours" }, "productInfoList": { "type": "array", "description": "New subscription product information list", "items": { "$ref": "#/components/schemas/SubscriptionChangeRequest.ProductInfo" }, "minItems": 1 }, "merchantInfo": { "$ref": "#/components/schemas/SubscriptionChangeRequest.MerchantInfo", "description": "Merchant info" }, "userInfo": { "$ref": "#/components/schemas/SubscriptionChangeRequest.UserInfo", "description": "User info" }, "goodsInfo": { "$ref": "#/components/schemas/SubscriptionChangeRequest.GoodsInfo", "description": "Merchant goods information" }, "addressInfo": { "$ref": "#/components/schemas/SubscriptionChangeRequest.AddressInfo", "description": "Address Information" }, "brandInfo": { "$ref": "#/components/schemas/BrandInfo", "description": "Brand display information for cashier" }, "paymentInfo": { "$ref": "#/components/schemas/SubscriptionChangeRequest.PaymentInfo", "description": "Payment information" }, "riskData": { "$ref": "#/components/schemas/SubscriptionChangeRequest.RiskData", "description": "Risk data for compliance and risk management" } }, "required": [ "currency", "goodsInfo", "merchantInfo", "notifyUrl", "originSubscriptionRequest", "paymentInfo", "productInfoList", "remainingAmount", "requestedAt", "subscriptionRequest", "userInfo" ] }, "SubscriptionChangeRequest.AddressInfo": { "type": "object", "description": "Address information", "properties": { "address": { "type": "string", "description": "Shipping address", "maxLength": 256, "minLength": 0 }, "city": { "type": "string", "description": "Shipping city", "maxLength": 32, "minLength": 0 }, "region": { "type": "string", "description": "Shipping region / state / province", "maxLength": 32, "minLength": 0 }, "postcode": { "type": "string", "description": "Shipping postcode", "maxLength": 16, "minLength": 0 }, "addressCountryCode": { "type": "string", "description": "Shipping country code", "maxLength": 16, "minLength": 0 } } }, "SubscriptionChangeRequest.GoodsInfo": { "type": "object", "description": "Goods information", "properties": { "goodsId": { "type": "string", "description": "Goods item id", "example": "GOODS001", "maxLength": 32, "minLength": 0 }, "goodsName": { "type": "string", "description": "Goods item name", "example": "Premium Subscription Plan", "maxLength": 64, "minLength": 0 }, "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)", "maxLength": 128, "minLength": 0 }, "appName": { "type": "string", "description": "App package name, for example com.example.app123 (for compliance and risk management purpose)", "maxLength": 32, "minLength": 0 }, "skuName": { "type": "string", "description": "Goods sku name", "maxLength": 32, "minLength": 0 }, "goodsUniquePrice": { "type": "string", "description": "Goods price", "maxLength": 16, "minLength": 0 }, "goodsQuantity": { "type": "integer", "format": "int32", "description": "Goods quantity" } }, "required": [ "goodsId", "goodsName" ] }, "SubscriptionChangeRequest.MerchantInfo": { "type": "object", "description": "Merchant information", "properties": { "merchantId": { "type": "string", "description": "Merchant id assigned by Waffo", "example": "M0001", "maxLength": 64, "minLength": 0 }, "subMerchantId": { "type": "string", "description": "Sub merchant id assigned by Waffo", "maxLength": 64, "minLength": 0 } }, "required": [ "merchantId" ] }, "SubscriptionChangeRequest.PaymentInfo": { "type": "object", "description": "Payment information", "properties": { "productName": { "type": "string", "description": "Payment product:\n- SUBSCRIPTION\nMerchant can view the signed contract product via Waffo Merchant portal\n", "example": "SUBSCRIPTION", "maxLength": 32, "minLength": 0 }, "payMethodType": { "type": "string", "description": "Payment method type. e.g.\n- EWALLET\n- CREDITCARD\n- DEBITCARD\nMerchant can provide a list of pay methods type as the filtering logic. If not provided, Waffo will choose all eligible payment methods based on merchant contract\n\nConditional\n(must be provided for card payments)\n", "maxLength": 256, "minLength": 0 }, "payMethodName": { "type": "string", "description": "The actual payment method. e.g. DANA\nIf payMethodName is provided, the payment request will be processed using this pay method directly\nConditional\n(required for non-card payment methods)\n", "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\"}", "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 }, "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 }, "cashierAppearance": { "type": "string", "description": "Defines the overall appearance configuration of the UI, including colors, background, and typography settings. A JSON-formatted string containing theme variables." }, "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.\n", "maxLength": 3, "minLength": 0 }, "cashierLanguage": { "type": "string", "description": "Merchant specify the cashier language. It follows IETF BCP 47 language tag\nThe 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\nFor example:\n- en-HK: English in Hong Kong\n- zh-Hant-HK: Traditional Chinese in Hong Kong\n- zh-Hans-HK: Simplified Chinese in Hong Kong\n", "maxLength": 24, "minLength": 0 } }, "required": [ "productName" ] }, "SubscriptionChangeRequest.ProductInfo": { "type": "object", "description": "Subscription product information", "properties": { "description": { "type": "string", "description": "Subscription product description, often appearing to user when asking user's confirmation", "example": "Premium Monthly Subscription", "maxLength": 128, "minLength": 0 }, "periodType": { "type": "string", "description": "Subscription product period type: - DAILY - WEEKLY - MONTHLY", "example": "MONTHLY", "maxLength": 12, "minLength": 0 }, "amount": { "type": "string", "description": "Subscription amount for this product", "example": 100000.0, "maxLength": 12, "minLength": 0 }, "periodInterval": { "type": "string", "description": "Period interval. 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 or 36. 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", "example": 1, "maxLength": 12, "minLength": 0 }, "numberOfPeriod": { "type": "string", "description": "Specify after how many deduction period, the subscription will end. The value needs to be greater than 1. For example 3. If the value is empty, it means the subscription has no defined end period. Note: The Dana subscription period shall not exceed three years in total.", "example": 12, "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. If the value is empty, there is no trial period", "example": 0.0, "maxLength": 24, "minLength": 0 }, "numberOfTrialPeriod": { "type": "string", "description": "Specify after how many periods, the trial will end. For example 1894", "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.", "example": "MONTHLY", "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.", "example": 1, "maxLength": 12, "minLength": 0 }, "scheduledAmounts": { "type": "array", "description": "Scheduled amount list for each period", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } } }, "required": [ "amount", "description", "periodInterval", "periodType" ] }, "SubscriptionChangeRequest.RiskData": { "type": "object", "description": "Risk data for compliance and risk management", "properties": { "userType": { "type": "string", "description": "Merchant user: Individual / Agent / Institution / Internal", "maxLength": 24, "minLength": 0 }, "userCategory": { "type": "string", "description": "Merchant user: Member / Non-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", "maxLength": 24, "minLength": 0 }, "userLastSeenIp": { "type": "string", "description": "Merchant user last login IP address", "maxLength": 24, "minLength": 0 }, "userIsNew": { "type": "string", "description": "Merchant user if he/she is a new user: Yes / No", "maxLength": 8, "minLength": 0 }, "userIsFirstPurchase": { "type": "string", "description": "Merchant user if this is his/her first purchase: Yes / No", "maxLength": 8, "minLength": 0 } } }, "SubscriptionChangeRequest.UserInfo": { "type": "object", "description": "User information", "properties": { "userId": { "type": "string", "description": "Merchant User id", "example": "USER001", "maxLength": 64, "minLength": 0 }, "userEmail": { "type": "string", "description": "Merchant user email", "example": "user@example.com", "maxLength": 64, "minLength": 0 }, "userTerminal": { "type": "string", "description": "Merchant user terminal type: \n- WEB (user is using a PC)\n- APP (user is using a Mobile Phone)\n", "maxLength": 32, "minLength": 0 }, "userPhone": { "type": "string", "description": "Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157", "example": "+62-08990013157", "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", "format": "date-time", "description": "Merchant user creation time" } }, "required": [ "userEmail", "userId" ] }, "ResponseSubscriptionChangeResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SubscriptionChangeResponse" } } }, "SubscriptionChangeResponse": { "type": "object", "description": "Subscription change response", "properties": { "originSubscriptionRequest": { "type": "string", "description": "Original subscription request id that was changed" }, "subscriptionRequest": { "type": "string", "description": "New subscription request id after the change" }, "merchantSubscriptionId": { "type": "string", "description": "Merchant's new subscription plan ID assigned to this user" }, "subscriptionChangeStatus": { "type": "string", "description": "Subscription change status: - IN_PROGRESS (payment request initiated) - AUTHORIZATION_REQUIRED (user needs to authorize payment) - SUCCESS (subscription change completed) - CLOSED (subscription change failed or timeout)" }, "subscriptionAction": { "type": "string", "description": "When subscriptionChangeStatus = AUTHORIZATION_REQUIRED, merchant follow the following: \"webUrl\": redirect user to this URL" }, "subscriptionId": { "type": "string", "description": "New Waffo subscription Id" } }, "required": [ "subscriptionId" ] }, "SubscriptionChangeInquiryRequest": { "type": "object", "description": "Subscription change inquiry request", "properties": { "originSubscriptionRequest": { "type": "string", "description": "Original subscription request id that was changed", "maxLength": 32, "minLength": 0 }, "subscriptionRequest": { "type": "string", "description": "New subscription request id after the change", "maxLength": 32, "minLength": 0 } }, "required": [ "originSubscriptionRequest", "subscriptionRequest" ] }, "ResponseSubscriptionChangeInquiryResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse" } } }, "SubscriptionChangeInquiryResponse": { "type": "object", "description": "Subscription change inquiry response", "properties": { "subscriptionRequest": { "type": "string", "description": "New subscription request id after the change", "maxLength": 32, "minLength": 0 }, "originSubscriptionRequest": { "type": "string", "description": "Original subscription request id that was changed", "maxLength": 32, "minLength": 0 }, "merchantSubscriptionId": { "type": "string", "description": "Merchant's new subscription plan ID assigned to this user", "maxLength": 64, "minLength": 0 }, "subscriptionId": { "type": "string", "description": "New Waffo subscription Id" }, "subscriptionChangeStatus": { "type": "string", "description": "Subscription change status:\n- IN_PROGRESS (payment request initiated)\n- AUTHORIZATION_REQUIRED (user needs to authorize payment)\n- SUCCESS (subscription change completed)\n- CLOSED (subscription change failed or timeout)\n" }, "subscriptionAction": { "type": "string", "description": "When subscriptionChangeStatus = AUTHORIZATION_REQUIRED, merchant follow the following: \n\"webUrl\": redirect user to this URL\n" }, "remainingAmount": { "type": "string", "description": "Remaining amount from the original subscription applied to the new subscription", "maxLength": 24, "minLength": 0 }, "currency": { "type": "string", "description": "Merchant subscription currency, for example IDR", "maxLength": 12, "minLength": 0 }, "userCurrency": { "type": "string", "description": "User payment currency. This is needed when merchant order currency is NOT the same as user payment currency", "maxLength": 12, "minLength": 0 }, "requestedAt": { "type": "string", "description": "Merchant-side request time" }, "subscriptionManagementUrl": { "type": "string", "description": "It refers to the subscription management page for users on the merchant side", "maxLength": 256, "minLength": 0 }, "extendInfo": { "type": "string", "description": "Reserved. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"}", "maxLength": 256, "minLength": 0 }, "orderExpiredAt": { "type": "string", "description": "The order expiry time set by merchant" }, "productInfoList": { "type": "array", "description": "New subscription product information list", "items": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.ProductInfo" }, "minItems": 1 }, "merchantInfo": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.MerchantInfo", "description": "Merchant info" }, "userInfo": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.UserInfo", "description": "User info" }, "goodsInfo": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.GoodsInfo", "description": "Merchant goods information" }, "addressInfo": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.AddressInfo", "description": "Address Information" }, "paymentInfo": { "$ref": "#/components/schemas/SubscriptionChangeInquiryResponse.PaymentInfo", "description": "Payment information" } }, "required": [ "currency", "goodsInfo", "merchantInfo", "merchantSubscriptionId", "originSubscriptionRequest", "paymentInfo", "productInfoList", "remainingAmount", "requestedAt", "subscriptionId", "subscriptionRequest", "userInfo" ] }, "SubscriptionChangeInquiryResponse.AddressInfo": { "type": "object", "description": "Address information", "properties": { "address": { "type": "string", "description": "Shipping address", "maxLength": 256, "minLength": 0 }, "city": { "type": "string", "description": "Shipping city", "maxLength": 32, "minLength": 0 }, "region": { "type": "string", "description": "Shipping region / state / province", "maxLength": 32, "minLength": 0 }, "postcode": { "type": "string", "description": "Shipping postcode", "maxLength": 16, "minLength": 0 }, "addressCountryCode": { "type": "string", "description": "Shipping country code", "maxLength": 16, "minLength": 0 } } }, "SubscriptionChangeInquiryResponse.GoodsInfo": { "type": "object", "description": "Goods information", "properties": { "goodsId": { "type": "string", "description": "Goods item id", "maxLength": 32, "minLength": 0 }, "goodsName": { "type": "string", "description": "Goods item name", "maxLength": 64, "minLength": 0 }, "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)", "maxLength": 128, "minLength": 0 }, "appName": { "type": "string", "description": "app package name, for example com.example.app123 (for compliance and risk management purpose)", "maxLength": 32, "minLength": 0 }, "skuName": { "type": "string", "description": "Goods sku name", "maxLength": 32, "minLength": 0 }, "goodsUniquePrice": { "type": "string", "description": "Goods price", "maxLength": 16, "minLength": 0 }, "goodsQuantity": { "type": "integer", "format": "int32", "description": "Goods quantity" } }, "required": [ "goodsId", "goodsName" ] }, "SubscriptionChangeInquiryResponse.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" ] }, "SubscriptionChangeInquiryResponse.PaymentInfo": { "type": "object", "description": "Payment information", "properties": { "productName": { "type": "string", "description": "Payment product:\n- SUBSCRIPTION\nMerchant can view the signed contract product via Waffo Merchant portal\n", "maxLength": 32, "minLength": 0 }, "payMethodType": { "type": "string", "description": "Payment method type. e.g.\n- EWALLET\n- CREDITCARD\n- DEBITCARD\nMerchant can provide a list of pay methods type as the filtering logic. If not provided, Waffo will choose all eligible payment methods based on merchant contract\n\nConditional\n(must be provided for card payments)\n", "maxLength": 256, "minLength": 0 }, "payMethodName": { "type": "string", "description": "The actual payment method. e.g. DANA\nIf payMethodName is provided, the payment request will be processed using this pay method directly\nConditional\n(required for non-card payment methods)\n", "maxLength": 24, "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\"}", "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 }, "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 }, "cashierAppearance": { "type": "string", "description": "Defines the overall appearance configuration of the UI, including colors, background, and typography settings. A JSON-formatted string containing theme variables. These variables are injected into the UI rendering layer and override the default theme settings. This field must be a valid JSON string, not a plain object. Example: {\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\"}}" }, "cashierLogoId": { "type": "string", "description": "Cashier Logo Id" }, "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 change.\n", "maxLength": 3, "minLength": 0 } }, "required": [ "productName" ] }, "SubscriptionChangeInquiryResponse.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 }, "amount": { "type": "string", "description": "Subscription amount for this product", "maxLength": 12, "minLength": 0 }, "periodInterval": { "type": "string", "description": "Period interval. 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 or 36. 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. The value needs to be greater than 1. For example 3. If the value is empty, it means the subscription has no defined end period. Note: The Dana subscription period shall not exceed three 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. If the value is empty, there is no trial period", "maxLength": 24, "minLength": 0 }, "numberOfTrialPeriod": { "type": "string", "description": "Specify after how many periods, the trial will end. For example 1894", "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 }, "scheduledAmounts": { "type": "array", "description": "Scheduled amount list for each period", "items": { "$ref": "#/components/schemas/SubscriptionScheduledAmount" } } }, "required": [ "amount", "description", "periodInterval", "periodType" ] }, "SubscriptionChangeInquiryResponse.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 }, "userTerminal": { "type": "string", "description": "Merchant user terminal type: \n- WEB (user is using a PC)\n- APP (user is using a Mobile Phone)\n", "maxLength": 32, "minLength": 0 }, "userPhone": { "type": "string", "description": "Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157", "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" } }, "required": [ "userEmail", "userId" ] }, "SubscriptionCancelRequest": { "type": "object", "description": "Subscription cancel request", "properties": { "subscriptionId": { "type": "string", "description": "Waffo subscription Id", "example": "", "maxLength": 64, "minLength": 0 }, "merchantId": { "type": "string", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "requestedAt": { "type": "string", "format": "date-time", "description": "Merchant-side cancel request time", "x-gen": "DATETIME_ISO" } }, "required": [ "merchantId", "requestedAt", "subscriptionId" ] }, "ResponseSubscriptionCancelResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SubscriptionCancelResponse" } } }, "SubscriptionCancelResponse": { "type": "object", "properties": { "merchantSubscriptionId": { "type": "string", "description": "Merchant subscription plan ID assigned to this user " }, "subscriptionRequest": { "type": "string", "description": "Subscription request id sent from Merchant. It will also be used for idempotent check. " }, "subscriptionId": { "type": "string", "description": "Waffo subscription Id " }, "orderStatus": { "type": "string", "description": "- CLOSE (due to timeout or failed)\n- MERCHANT_CANCELLED\n- CHANNEL_CANCELLED\n- EXPIRED \n" } } }, "AcqOrderRefundInquiryRequest": { "type": "object", "description": "provide refundRequestId or acquiringRefundOrderId", "properties": { "refundRequestId": { "type": "string", "description": "Refund request id sent from Merchant. It will also be used for idempotent check. \n(provide refundRequestId or acquiringRefundOrderId) \n" }, "acquiringRefundOrderId": { "type": "string", "description": "Waffo refund order Id \n(provide refundRequestId or acquiringRefundOrderId) \n", "example": "" } } }, "AcqOrderRefundInquiry": { "type": "object", "description": "A RefundOrder object will be returned", "properties": { "refundRequestId": { "type": "string", "description": "Refund request id sent from Merchant. It will also be used for idempotent check. " }, "merchantRefundOrderId": { "type": "string", "description": "merchant refund order id" }, "acquiringOrderId": { "type": "string", "description": "acquiring order id" }, "acquiringRefundOrderId": { "type": "string", "description": "acquiring refund order id" }, "origPaymentRequestId": { "type": "string", "description": "Original Payment request id sent from Merchant." }, "refundAmount": { "type": "string", "description": "refund amount" }, "refundStatus": { "type": "string", "description": "**REFUND_IN_PROGRESS** - refund request has been accepted and result will be sent back to merchant \n**ORDER_PARTIALLY_REFUNDED** \n**ORDER_FULLY_REFUNDED** \n**ORDER_REFUND_FAILED**" }, "refundReason": { "type": "string", "description": "merchant refund reason" }, "refundRequestedAt": { "type": "string", "description": "merchant side request time" }, "refundUpdatedAt": { "type": "string", "description": "order last update time" }, "refundFailedReason": { "type": "string", "description": "Json format \n { \n \"orderFailedCode\":\"XXX\", \n \"orderFailedDescription\":\"XXX\" \n}" }, "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." }, "finalDealAmount": { "type": "string", "description": "The final refunded amount that the user receives.\nIf merchant order currency is not the same as user payment currency, the finalDealAmount will not be the same as orderAmount.\nThe refunded amount may not include the service/tax fee that user has paid, hence the finalDealAmount may not the same as orderAmount. " }, "merchantUserId": { "type": "string", "description": "Merchant user id" }, "subscriptionInfo": { "$ref": "#/components/schemas/AcqOrderRefundInquiry.SubscriptionInfo", "description": "The associated subscription info. Present when the refund is linked to a subscription payment order." }, "remainingRefundAmount": { "type": "string", "description": "Remaining Refund Amount that Merchant can still refund" }, "userInfo": { "$ref": "#/components/schemas/RefundOrderUserInfo", "description": "For certain pay method type (e.g. ONLINE_BANKING) the refund requires Merchant to provide user information to execute" }, "refundCompletedAt": { "type": "string", "description": "Refund order completion time" }, "refundSource": { "type": "string", "description": "Refund Source\n**MERCHANT**: Indicates the refund is triggered by the Merchant.\n**RDR**: Indicates the refund is triggered by the chargeback alert service via vendor RDR.\n**ETHOCA**: Indicates the refund is triggered by the chargeback alert service via vendor Ethoca.\n" } }, "required": [ "acquiringOrderId", "acquiringRefundOrderId", "finalDealAmount", "origPaymentRequestId", "refundAmount", "refundReason", "refundRequestId", "refundRequestedAt", "refundStatus", "refundUpdatedAt", "remainingRefundAmount" ] }, "AcqOrderRefundInquiry.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" ] }, "RefundOrderUserBankInfo": { "type": "object", "properties": { "bankAccountNo": { "type": "string", "maxLength": 64, "minLength": 0 }, "bankCode": { "type": "string", "maxLength": 64, "minLength": 0 }, "bankName": { "type": "string", "maxLength": 64, "minLength": 0 }, "bankCity": { "type": "string", "maxLength": 64, "minLength": 0 }, "bankBranch": { "type": "string", "maxLength": 64, "minLength": 0 } } }, "RefundOrderUserInfo": { "type": "object", "description": "For certain pay method type (e.g. ONLINE_BANKING) the refund requires Merchant to provide user information to execute", "properties": { "userType": { "type": "string", "default": "INDIVIDUAL", "description": "User Type: \n- **INDIVIDUAL** \n- **BUSINESS**", "example": "INDIVIDUAL", "maxLength": 12, "minLength": 0 }, "userFirstName": { "type": "string", "description": "User's first name", "maxLength": 64, "minLength": 0 }, "userMiddleName": { "type": "string", "maxLength": 64, "minLength": 0 }, "userLastName": { "type": "string", "description": "User's last name", "maxLength": 64, "minLength": 0 }, "nationality": { "type": "string", "maxLength": 3, "minLength": 0 }, "userEmail": { "type": "string", "description": "User's email address for refund communication", "example": "test@email.com", "maxLength": 64, "minLength": 0 }, "userBankInfo": { "$ref": "#/components/schemas/RefundOrderUserBankInfo", "description": "it will include the following info in a json format: \n{ \n\"bankAccountNo\": \"XXX\", \n\"bankCode\": \"XXX\", \n\"bankCity\": \"XXX\", \n\"bankBranch\": \"XXX\" \n}" }, "userPhone": { "type": "string", "description": "Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157", "maxLength": 16, "minLength": 0 }, "userBirthDay": { "type": "string", "maxLength": 12, "minLength": 0 }, "userIDType": { "type": "string", "description": "User's Identification Type", "maxLength": 24, "minLength": 0 }, "userIDNumber": { "type": "string", "description": "User's Identification Number", "maxLength": 64, "minLength": 0 }, "userIDIssueDate": { "type": "string", "description": "The date of issue of User's ID. Format is dd/mm/yyyy", "maxLength": 12, "minLength": 0 }, "userIDExpiryDate": { "type": "string", "description": "The date of expiry of User's ID. Format is dd/mm/yyyy", "maxLength": 12, "minLength": 0 } }, "required": [ "userType" ] }, "ResponseAcqOrderRefundInquiry": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqOrderRefundInquiry" } } }, "PayoutQueryRequest": { "type": "object", "properties": { "payoutRequestId": { "type": "string", "description": "Your unique ID for this payout request. Also used for the idempotency check.\nProvide either this or payoutOrderId.\n", "maxLength": 64, "minLength": 0 }, "payoutOrderId": { "type": "string", "description": "Waffo's payout Order ID. Also used for the idempotency check.\nProvide either this or payoutRequestId.\nIf both are provided, payoutOrderId takes precedence, and both must refer to the same payout order; Otherwise the request is rejected.\n", "maxLength": 64, "minLength": 0 } } }, "AddressInfo": { "type": "object", "properties": { "address": { "type": "string", "description": "The payee's street and address details\n", "maxLength": 256, "minLength": 0 }, "city": { "type": "string", "description": "The payee's address city\n", "maxLength": 32, "minLength": 0 }, "region": { "type": "string", "description": "The payee's address region / state / province\n", "maxLength": 32, "minLength": 0 }, "postcode": { "type": "string", "description": "The payee's address postcode\n", "maxLength": 16, "minLength": 0 }, "addressCountryCode": { "type": "string", "description": "The payee's address country code, i.e. ISO 3166-1 alpha-3 code\n", "maxLength": 3, "minLength": 3 } } }, "MerchantInfo": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Your merchant ID, assigned by Waffo during onboarding and shown on Dashboard\n", "maxLength": 64, "minLength": 0 }, "subMerchantId": { "type": "string", "description": "Your sub-merchant ID, assigned by Waffo if required\n", "maxLength": 64, "minLength": 0 } }, "required": [ "merchantId" ] }, "PayeeInfo": { "type": "object", "properties": { "payeeType": { "type": "string", "description": "Payee type.\n- INDIVIDUAL - a person\n- BUSINESS - a company or organization\n", "maxLength": 10, "minLength": 0 }, "payeeId": { "type": "string", "description": "Your own identifier for this payee.\nWaffo stores it and returns it unchanged in query responses and notifications, so you can reconcile payouts against your own payee records\n", "maxLength": 64, "minLength": 0 }, "payeeFirstName": { "type": "string", "description": "The payee's first name, exactly as registered on the receiving bank account or e-wallet.\nThe required format depends on the destination country and payout method. See [Payout Payee Name Fields Filling Instructions] for the exact script, pattern and example\n", "maxLength": 60, "minLength": 0 }, "payeeMiddleName": { "type": "string", "description": "The payee's middle name, exactly as registered on the receiving bank account or e-wallet.\nThe required format depends on the destination country and payout method. See [Payout Payee Name Fields Filling Instructions] for the exact script, pattern and example\n", "maxLength": 60, "minLength": 0 }, "payeeLastName": { "type": "string", "description": "The payee's last name, exactly as registered on the receiving bank account or e-wallet.\nThe required format depends on the destination country and payout method. See [Payout Payee Name Fields Filling Instructions] for the exact script, pattern and example\n", "maxLength": 80, "minLength": 0 }, "nationality": { "type": "string", "description": "The payee's nationality, as an ISO 3166-1 alpha-3 country code.\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n", "maxLength": 3, "minLength": 3 }, "payeeEmail": { "type": "string", "description": "The payee's email address. Used for compliance screening and, where the destination rail requires it, passed to the receiving institution\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n", "maxLength": 64, "minLength": 0 }, "payeePhone": { "type": "string", "description": "The payee's mobile number in international format +-, e.g. +62-8xxxx\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n", "maxLength": 20, "minLength": 0 }, "payeeIDType": { "type": "string", "description": "The payee's identification type\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n", "maxLength": 24, "minLength": 0 }, "payeeIDNumber": { "type": "string", "description": "The identification number of the document given in payeeIDType\n", "maxLength": 64, "minLength": 0 }, "payeeBirthDay": { "type": "string", "description": "The payee's date of birth, formatted dd/mm/yyyy\n", "maxLength": 12, "minLength": 0 }, "payeeIDIssueDate": { "type": "string", "description": "Issue date of the document in payeeIDType, formatted dd/mm/yyyy\n", "maxLength": 12, "minLength": 0 }, "payeeIDExpiryDate": { "type": "string", "description": "Expiry date of the document in payeeIDType, formatted dd/mm/yyyy\n", "maxLength": 12, "minLength": 0 }, "payeeFullName": { "type": "string" } }, "required": [ "payeeType" ] }, "PayoutInfo": { "type": "object", "properties": { "productName": { "type": "string", "description": "The payout product to use.\n- ONE_TIME_PAYOUT - a single one-off payout\n", "maxLength": 32, "minLength": 0 }, "payoutMethodType": { "type": "string", "description": "The payout method type describes how the funds reach the payee. Availability varies by destination country and can be found in your Payout contract\n- EWALLET - Payout to an e-wallet. e.g. DANA, GCASH.\n- BANK_ACCOUNT - Payout to a bank account. e.g. DBS BANK LTD.\n- PROXY - Payout via a country's instant-payment proxy network that maps a proxy ID(PHONE/VPA) to a bank account or e-wallet. e.g. PAYNOW in Singapore.\n", "maxLength": 16, "minLength": 0 }, "payoutMethodName": { "type": "string", "description": "The payout method name describes how the funds reach the payee. Availability varies by destination country and can be found in your Payout contract\nRequired for EWALLET (e.g. DANA, GCASH) and PROXY (e.g. PAYNOW).\nOptional for BANK_ACCOUNT: if you omit it, Waffo derives the bank from the bankCode and bankBranch in payoutMethodProperty\n", "maxLength": 24, "minLength": 0 }, "payoutMethodProperty": { "type": "string", "description": "Payout routing details\n- BANK_ACCOUNT - Bank routing details, Required for some destination countries. — see [Payout Creation Field Requirements Table].\n This field contains the following information in JSON format:\n {\"bankCode\":\"XXX\",\"bankName\":\"XXX\",\"bankBranch\":\"XXX\",\"accountType\":\"XXX\"}\n bankCode — the bank's code in the destination country's clearing scheme, required field\n bankName — the bank's name in the destination country's clearing scheme, optional field\n bankBranch — the bank branch's code in the destination country's clearing scheme, conditional field\n accountType — the type of bank account, conditional field, required in certain countries, e.g. USA\n Please refer to [Bank List] for full bank lists supported by each country\n\n- EWALLET — E-wallet routing details. Required for certain payout methods; see [Payout Creation Field Requirements Table].\n This field contains the following information in JSON format:\n {\"eWalletAccountType\":\"XXX\"}\n eWalletAccountType — the identifier type of e-wallet account number, \"PHONE\" is the default value, it is optional. e.g. PHONE, EMAIL\n Please refer to [EWALLET List] for full identifier type lists supported by each e-wallet\n\n- PROXY — Instant-payment routing details. Required for certain payout methods; see [Payout Creation Field Requirements Table].\n This field contains the following information in JSON format:\n {\"proxyIdentifierType\":\"XXX\"}\n proxyIdentifierType — the identifier type of proxy ID, it is required. e.g. PHONE, VPA\n Please refer to [PROXY List] for full identifier type lists supported by each proxy scheme\n", "maxLength": 512, "minLength": 0 }, "payoutMethodUserAccountNo": { "type": "string", "description": "The payee's account number, format depends on payoutMethodType:\n- EWALLET — the payee's wallet account number.\n \"PHONE\" is the default value, it is optional, as +- or without symbols, length is generally not checked, e.g. +62-8xxxx, 628xxxx\n The accepted format per wallet is in [EWALLET List].\n- BANK_ACCOUNT — the payee's bank account number.\n Supported institutions vary by country, see [Bank List].\n- PROXY — the proxy identifier, e.g. PHONE, VPA\n \"PHONE\" as +- or without symbols, e.g. +62-8xxxx, 628xxxx\n The accepted format per proxy type is in [PROXY List].\n", "maxLength": 64, "minLength": 0 } }, "required": [ "payoutMethodType", "payoutMethodUserAccountNo", "productName" ] }, "PayoutOrderData": { "type": "object", "properties": { "payoutRequestId": { "type": "string", "description": "Your own identifier for this payout request. Must be unique within your merchant account. Waffo treats it as the idempotency key\n" }, "payoutCurrency": { "type": "string", "description": "The merchant payout currency, as an ISO 4217 alpha-3 code (e.g. USD, VND). Please refer to your Payout contract for the supported currency in the destination country and payout methods\n" }, "payoutAmount": { "type": "string", "description": "The merchant Payout amount. The maximum decimal places must match the currency's ISO 4217 unit (e.g. 2 for USD, 0 for VND). Examples: \"1000.01\", \"2001\"\nUse . as the decimal separator, no thousands separator\n" }, "country": { "type": "string", "description": "The destination country of the funds, as an ISO 3166-1 alpha-3 code. Must be a country enabled for your account\n" }, "description": { "type": "string", "description": "Description shown on the beneficiary's bank or e-wallet statement. Waffo accepts up to 64 characters, but the receiving institution applies its own, much shorter limit and truncates silently without an error. Keep it to 10 characters or fewer to be safe on every rail;\nUse ASCII letters, digits and spaces only — other characters may be stripped or rejected downstream.\n" }, "purpose": { "type": "string", "description": "The reason for the payout, used for regulatory reporting and compliance screening in the destination country. Allowed values vary by country — see [Payout Purpose Enum Table]\nSend the value that actually describes the payment; a mismatched purpose can cause the receiving institution to return the funds.\n" }, "merchantInfo": { "$ref": "#/components/schemas/MerchantInfo", "description": "Merchant info\n" }, "payeeInfo": { "$ref": "#/components/schemas/PayeeInfo", "description": "The information of payee who receives this payout\n" }, "addressInfo": { "$ref": "#/components/schemas/AddressInfo", "description": "The payee's residential or registered address.\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n" }, "payoutInfo": { "$ref": "#/components/schemas/PayoutInfo", "description": "Payout information\n" }, "notifyUrl": { "type": "string", "description": "The URL to which we send a notification when the payout reaches a final state.\n" }, "extendInfo": { "type": "string", "description": "Merchants pass the information and return it as is. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"}\n" }, "payoutRequestedAt": { "type": "string", "description": "Merchant-side payout request time (ISO 8601, UTC+00:00): yyyy-MM-dd'T'HH:mm:ss.SSS'Z', e.g. 2026-08-12T09:30:00.000Z\n" }, "payoutOrderId": { "type": "string", "description": "Waffo's payout Order ID\n" }, "prefundCurrency": { "type": "string", "description": "The currency funded by the merchant\n" }, "prefundAmount": { "type": "string", "description": "The amount funded by the merchant, inclusive of the handling fee.\nIf the transaction fails, except for the handling fee, which may be charged depending on the situation, the remaining amount will be returned to the merchant.\n" }, "payeeCurrency": { "type": "string", "description": "The currency of the final amount received by the payee\n" }, "payeeAmount": { "type": "string", "description": "The final amount received by the payee.\nThe maximum decimal places must match the currency's ISO 4217 unit (e.g. 2 for USD, 0 for VND). Examples: \"1000.01\", \"2001\". Use \".\" as the decimal separator, no thousands separator.\n" }, "feeCurrency": { "type": "string", "description": "Payout Fee Currency\n" }, "feeAmount": { "type": "string", "description": "The provisioned fee amount for this payout, calculated when the payout is created. The currency is specified by feeCurrency.\nCompare with actFeeAmount, which is the amount actually collected once the payout reaches a final state.\n" }, "actFeeAmount": { "type": "string", "description": "The actual fee amount collected upon completion of the transaction. The currency is specified by feeCurrency.\n" }, "status": { "type": "string", "description": "Payout status.\n- IN_PROGRESS - (Payout is in progress)\n- SUCCESS - (Payout is successful)\n- FAILURE (Payout failed)\n" }, "subStatus": { "type": "string", "description": "Only present when a reverse occurs, payout status stays SUCCESS. Most orders never have it.\n- FULL_REVERSED - the whole payout amount was reversed\n- PARTIAL_REVERSED - only part of the payout amount was reversed\n" }, "failureCode": { "type": "string", "description": "Payout failure code\n" }, "failureReason": { "type": "string", "description": "Payout failure reason\n" }, "payoutArrivalAt": { "type": "string", "description": "Payout Arrival Time (ISO 8601, UTC+00:00): yyyy-MM-dd'T'HH:mm:ss.SSS'Z', e.g. 2026-08-12T09:30:00.000Z\n" }, "payoutUpdatedAt": { "type": "string", "description": "Payout last update time (ISO 8601, UTC+00:00): yyyy-MM-dd'T'HH:mm:ss.SSS'Z', e.g. 2026-08-12T09:30:00.000Z\n" } } }, "ResponsePayoutOrderData": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/PayoutOrderData" } } }, "PayoutOrderRequest": { "type": "object", "properties": { "payoutRequestId": { "type": "string", "description": "Your own identifier for this payout request. Must be unique within your merchant account. Waffo treats it as the idempotency key\n", "maxLength": 64, "minLength": 0 }, "payoutCurrency": { "type": "string", "description": "The merchant payout currency, as an ISO 4217 alpha-3 code (e.g. USD, VND). Please refer to your Payout contract for the supported currency in the destination country and payout methods\n", "maxLength": 3, "minLength": 3 }, "payoutAmount": { "type": "string", "description": "The merchant Payout amount. The maximum decimal places must match the currency's ISO 4217 unit (e.g. 2 for USD, 0 for VND). Examples: \"1000.01\", \"2001\"\nUse \".\" as the decimal separator, no thousands separator\n", "maxLength": 24, "minLength": 0 }, "country": { "type": "string", "description": "The destination country of the funds, as an ISO 3166-1 alpha-3 code. Must be a country enabled for your account\n", "maxLength": 3, "minLength": 3 }, "description": { "type": "string", "description": "Description shown on the beneficiary's bank or e-wallet statement. Waffo accepts up to 64 characters, but the receiving institution applies its own, much shorter limit and truncates silently without an error. Keep it to 10 characters or fewer to be safe on every rail;\nUse ASCII letters, digits and spaces only — other characters may be stripped or rejected downstream.\n", "maxLength": 64, "minLength": 0 }, "purpose": { "type": "string", "description": "The reason for the payout, used for regulatory reporting and compliance screening in the destination country. Allowed values vary by country — see [Payout Purpose Enum Table]\nSend the value that actually describes the payment; a mismatched purpose can cause the receiving institution to return the funds.\n", "maxLength": 32, "minLength": 0 }, "merchantInfo": { "$ref": "#/components/schemas/MerchantInfo", "description": "Merchant info\n" }, "payeeInfo": { "$ref": "#/components/schemas/PayeeInfo", "description": "The information of payee who receives this payout\n" }, "addressInfo": { "$ref": "#/components/schemas/AddressInfo", "description": "The payee's residential or registered address.\nRequired for some destination countries. — see [Payout Creation Field Requirements Table]\n" }, "payoutInfo": { "$ref": "#/components/schemas/PayoutInfo", "description": "Payout information\n" }, "notifyUrl": { "type": "string", "description": "The URL to which we send a notification when the payout reaches a final state.\n", "maxLength": 256, "minLength": 0 }, "extendInfo": { "type": "string", "description": "Merchants pass the information and return it as is. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"}\n", "maxLength": 128, "minLength": 0 }, "payoutRequestedAt": { "type": "string", "description": "Merchant-side payout request time (ISO 8601, UTC+00:00): yyyy-MM-dd'T'HH:mm:ss.SSS'Z', e.g. 2026-08-12T09:30:00.000Z\n", "maxLength": 24, "minLength": 0 } }, "required": [ "country", "description", "merchantInfo", "payeeInfo", "payoutCurrency", "payoutInfo", "payoutRequestId", "payoutRequestedAt" ] }, "PayMethodConfigInquiryRequest": { "type": "object", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 } }, "required": [ "merchantId" ] }, "FixedMaintenanceRule": { "type": "object", "description": "The fixed maintenance timezone. e.g UTC+08:00, UTC+05:30", "properties": { "startRule": { "type": "string", "description": "The start time of fixed maintenance. written in cron expression format e.g. \n**00 00 00 ? * THU**" }, "endRule": { "type": "string", "description": "The end time of fixed maintenance. written in cron expression format e.g. \n**00 00 00 ? * THU**" } }, "required": [ "endRule", "startRule" ] }, "PayMethodConfigInquiryResponse": { "type": "object", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant id assigned by Waffo", "example": 1000000201 }, "payMethodDetails": { "type": "array", "description": "The array object of the pay methods details that merchant has signed a contract with", "items": { "$ref": "#/components/schemas/PayMethodDetail" } } }, "required": [ "merchantId", "payMethodDetails" ] }, "PayMethodDetail": { "type": "object", "description": "The pay methods details that merchant has signed a contract with", "properties": { "productName": { "type": "string", "description": "Payment product: \n- **ONE_TIME_PAYMENT** \n- **DIRECT_PAYMENT**" }, "payMethodName": { "type": "string", "description": "The name of the pay method. e.g. GCash, DANA" }, "country": { "type": "string", "description": "The country of the pay method e.g. PHL, IDN" }, "currentStatus": { "type": "string", "description": "The current availability of the pay method\n- **1** - Available\n- **0** - Not available\nMay be empty when real-time availability is temporarily unavailable." }, "fixedMaintenanceRules": { "type": "array", "description": "The fixed maintenance period, written in cron expression format. e.g.\n- **0 30 1 * * ? - 0 30 2 * * ?** - Not available daily from 1:30-2:30am\n- **0 00 23 ? * 1,2,3,4,5 - 0 59 23 ? * 1,2,3,4,5** - Not available From Mon-Fri 11:00pm-11:59pm\n- **0 00 0 1,15 * ? - 0 59 23 1,15 * ?** - Not available on Day 1, Day 15 of the month", "items": { "$ref": "#/components/schemas/FixedMaintenanceRule" } }, "fixedMaintenanceTimezone": { "type": "string", "description": "The fixed maintenance timezone. e.g UTC+08:00, UTC+05:30" }, "payMethodType": { "type": "string", "description": "The category of the pay method. e.g. CARD, EWALLET, BANK_ACCOUNT" }, "currency": { "type": "string", "description": "The supported currency of the pay method (ISO 4217). e.g. PHP, IDR" }, "orderAmountMin": { "type": "string", "description": "The minimum order amount allowed for this pay method" }, "orderAmountMax": { "type": "string", "description": "The maximum order amount allowed for this pay method" }, "refundAllowed": { "type": "integer", "format": "int32", "description": "The refund policy of the pay method\n- **0** - Refund is not allowed\n- **1** - Full refund is allowed\n- **21** - Partial refund is allowed, single time\n- **22** - Partial refund is allowed, multiple times" } }, "required": [ "country", "fixedMaintenanceRules", "fixedMaintenanceTimezone", "payMethodName", "productName" ] }, "ResponsePayMethodConfigInquiryResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/PayMethodConfigInquiryResponse" } } }, "AcqOrderRefundRequest": { "type": "object", "properties": { "refundRequestId": { "type": "string", "description": "Refund request id sent from Merchant. It will also be used for idempotent check.", "x-gen": "NANOID", "maxLength": 32, "minLength": 0 }, "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order Id", "example": "", "maxLength": 32, "minLength": 0 }, "merchantRefundOrderId": { "type": "string", "description": "Merchant side refund order id", "maxLength": 64, "minLength": 0 }, "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "requestedAt": { "type": "string", "format": "date-time", "description": "Merchant-side request time", "x-gen": "DATETIME_ISO" }, "refundAmount": { "type": "string", "description": "Refund amount", "example": 10.0, "minLength": 1 }, "refundReason": { "type": "string", "description": "Refund reason", "example": "replace your reason....", "maxLength": 256, "minLength": 0 }, "refundNotifyUrl": { "type": "string", "description": "The callback address to notify the merchant after the refund is completed / failed. \nIf not provided, Merchant can use inquiry refund API to get the final refund status.", "maxLength": 256, "minLength": 0 }, "extendInfo": { "type": "string", "description": "Reserved. Json format e.g. {\"key1\":\"value1\", \"key2\":\"value2\"} ", "maxLength": 128, "minLength": 0 }, "refundSource": { "type": "string" }, "userInfo": { "$ref": "#/components/schemas/RefundOrderUserInfo", "description": "For certain pay method type (e.g. ONLINE_BANKING) the refund requires Merchant to provide user information to execute" } }, "required": [ "acquiringOrderId", "merchantId", "refundAmount", "refundReason", "refundRequestId", "requestedAt" ] }, "AcqOrderRefundResponse": { "type": "object", "properties": { "refundRequestId": { "type": "string", "description": "Refund request id sent from Merchant. It will also be used for idempotent check." }, "merchantRefundOrderId": { "type": "string", "description": "Merchant order id" }, "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order Id" }, "acquiringRefundOrderId": { "type": "string", "description": "Waffo refund order Id" }, "refundAmount": { "type": "string", "description": "Refund amount" }, "refundStatus": { "type": "string", "description": "**REFUND_IN_PROGRESS** - refund request has been accepted and result will be sent back to merchant via refundNotifyUrl \n**ORDER_PARTIALLY_REFUNDED** \n**ORDER_FULLY_REFUNDED** \n**ORDER_REFUND_FAILED**" }, "remainingRefundAmount": { "type": "string", "description": "Remaining Refund Amount that Merchant can still refund" }, "refundSource": { "type": "string", "description": "Refund Source \n**MERCHANT** \n**RDR** \n**ETHOCA**" } }, "required": [ "acquiringOrderId", "acquiringRefundOrderId", "refundAmount", "refundRequestId", "refundSource", "refundStatus", "remainingRefundAmount" ] }, "ResponseAcqOrderRefundResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqOrderRefundResponse" } } }, "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. \n (provide paymentRequestId or acquirerOrderId) " }, "acquiringOrderId": { "type": "string", "description": "waffo acquiring order Id \n(provide paymentRequestId or acquirerOrderId)", "example": "" } } }, "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 } } }, "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.0, "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 \n https://www.merchant123.com/goods123 \n (for compliance and risk management purpose) \n 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\n(for compliance and risk management purpose) \n provide either goodsUrl or appName", "maxLength": 32, "minLength": 0 } }, "required": [ "appName", "goodsName", "goodsUrl" ] }, "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) \n**AUTHORIZATION_REQUIRED** (pay method requires user authorization, usually for an OTP authentication or a redirection to a page for authentication) \n**AUTHED_WAITING_CAPTURE** (Order needs to be captured by merchant, applicable for CARD payment) \n**PAY_SUCCESS** \n**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: \n\"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.\n\"webUrl\": redirect user to webURL\n\"deeplinkUrl\": redirect user to deeplink url\n\"actionData\": {\n \"paymentExpiryTime\":\"2023-04-01T03:00:00.000Z\", (Follow ISO 8601 standard)\n \"paymentQr\":\"xxx\", (QR String Value)\n \"paymentCode\":\"xxx\",\n \"paymentBarCode\":\"xxx\",\n \"paymentCurrency\": \"xxx\",\n \"paymentAmount\": \"xxx\",\n \"userFeeAmount\": \"xxx\",\n \"userFeeCurrency\":\"xxx\",\n \"exchangeRate\": \"xxx\", (it is paymentAmount/orderAmount when orderCurrency is not the same as paymentCurrency)\n \"bankAccount\":\"xxx\",\n \"bankName\":\"xxx\",\n \"referenceNumber\":\"xxx\",\n \"bankBeneficiary\":\"xxx\"\n}\nActionData is for those Merchants who want to build their own Cashier Page for their users, without using Waffo's cashier page\n" }, "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.\nIf merchant order currency is not the same as user payment currency, the finalDealAmount will not be the same as orderAmount. \nIf 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)\nNote: \nIf refunds are not allowed or the order is not successful, this value is null.\n" }, "cancelRedirectUrl": { "type": "string", "description": "The address of the merchant page to redirect to when user cancels the payment" }, "orderFailedReason": { "type": "string", "description": "Json format \n { \n \"orderFailedCode\":\"XXX\", \n \"orderFailedDescription\":\"XXX\" \n}" }, "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" ] }, "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" ] }, "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.\nIf 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.\nYou can also contact Waffo to configure this fallback on your behalf; merchant authorization is required.\nAfter going live, pass the user's real email whenever possible.\nDo not use placeholder values such as `test` or share one email address across multiple users, because this may trigger risk controls.\n", "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: \n- **WEB** (user is using a PC) \n- **APP** (user is using a Mobile Phone) \n- **IN_WALLET_APP** (currently supported for DANA only) \n- **IN_MINI_PROGRAM** (user is inside a pay method's mini program (e.g. Wechat mini program)) \nNot 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" ] }, "AcqOrderPaymentInfo": { "type": "object", "description": "Payment information", "properties": { "productName": { "type": "string", "description": "Payment product: \n- **ONE_TIME_PAYMENT** \n- **DIRECT_PAYMENT** \n- **MINI_PROGRAM_PAYMENT** ", "example": "ONE_TIME_PAYMENT", "maxLength": 32, "minLength": 0 }, "payMethodType": { "type": "string", "description": "Payment method type. e.g. \n- **EWALLET** \n- **ONLINE_BANKING** \n- **DIGITAL_BANKING** \n- **OTC** \n- **CREDITCARD** \n- **DEBITCARD**", "example": "EWALLET", "maxLength": 256, "minLength": 0 }, "payMethodName": { "type": "string", "description": "The actual payment method. e.g. DANA, GCASH\nIf payMethodName is provided, the payment request will be processed using this pay method directly. \nIf payMethodName is not provided, user will be redirected to Waffo's cashier page to choose the final pay method. \nIf 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\n", "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: \n\n- cpf: specify the user's cpf number used in this payment\n- 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.\n- cardPrefixPurpose: input restriction purpose. Merchant can set as restriction or promotion. Waffo will display the respective error message to the user\n- 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\"}]}\n", "maxLength": 1024, "minLength": 0 }, "payMethodResponse": { "type": "string", "description": "The specific information returned by Pay Method \nJson format \n{ \n\"payMethodRefId\": \"xxx\", \n\"exchangeRate\": \"xxx\", \n\"userOpenId\": \"xxx\", \n\"maskCardData\": \"402856******9917\", \n\"userPaymentAmount\": \"10.00\", \n\"userPaymentCurrency\": \"CNY\" \n} \n- payMethodRefId: This is the payment ref ID that user often sees in its transaction history from Pay Method's app/portal \n- exchangeRate: this is the exchange rate used by Pay Method during user payment\n- userOpenId: this is the unique user open ID assigned by the pay method\n- maskCardData: returns the first six and last four digits of customer card data for a successful card payment transaction\n- userPaymentAmount: the actual amount paid by the user on the pay method side\n- userPaymentCurrency: the currency of the actual payment made by the user on the pay method side\n", "readOnly": true }, "userPaymentAccessToken": { "type": "string", "description": "User payment access token is generated via Waffo tokenization service.\nIt is used to tokenize user's card data.\nFor card binding and tokenization details, refer to [Waffo Tokenization Overview](https://waffo.com/docs/zh/developer-docs/integration/tokenization/overview).\n", "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 \nEMAIL \nPHONE_NO \nACCOUNT_ID", "maxLength": 24, "minLength": 0 }, "payOption": { "type": "string", "description": "The pay option user has selected, for example\n- **BALANCE** \n- **DEBIT_CARD** \n- **CREDIT_CARD** \nIf 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\nThe 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\nFor example: \n- en-HK: English in Hong Kong\n- zh-Hant-HK: Traditional Chinese in Hong Kong\n- zh-Hans-HK: Simplified Chinese in Hong Kong\n", "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.\nThis field must be a valid JSON string, not a plain object.\nFor example:\n{\"variables\":{\"colorPrimary\":\"#0570de\",\"colorBackground\":\"#ffffff\",\"colorText\":\"#30313d\"}}\n" }, "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.\n", "maxLength": 3, "minLength": 0 }, "captureMode": { "type": "string", "description": "- **manualCapture**: the payment was authorized first, but Merchant will capture it manually at a later stage\n", "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\n- scheduled\n- unscheduled\n", "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).\nWhen true, only pay methods capable of mit are offered.\nAfter this customer initiated payment succeeds, the payment method is tokenized; reuse the resulting token as userPaymentAccessToken, together with merchantInitiatedMode, to initiate a later mit.\nWhen setupFutureUsage is used, do not provide userPaymentAccessToken.\nFor how the token is obtained and reused for mit, refer to [Waffo Tokenization Overview](https://waffo.com/docs/zh/developer-docs/integration/tokenization/overview).\n" } }, "required": [ "productName" ] }, "ResponseAcqOrderInquiry": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqOrderInquiry" } } }, "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 } } }, "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.\n", "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:\n - 3DS_FORCE\n - NO_3DS\n However, the eventual 3DS decision is also subject to Waffo's risk decision.\n", "maxLength": 12, "minLength": 0 } } }, "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.0, "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. \nIf no value is provided, it will stay on the cashier page after successful payment. \nRequired 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." }, "addressInfo": { "$ref": "#/components/schemas/AcqOrderAddressInfo", "description": "Address Information" } }, "required": [ "merchantInfo", "merchantOrderId", "notifyUrl", "orderAmount", "orderCurrency", "orderDescription", "orderRequestedAt", "paymentInfo", "paymentRequestId", "userInfo" ] }, "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" ] }, "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 } } }, "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 } } }, "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 \n**PAY_IN_PROGRESS** -(merchant order is accepted, and user is in the process of payment) \n**AUTHORIZATION_REQUIRED** (pay method requires user authorization, merchant needs to bring user to the authorization page by retrieving the information from orderAction) \n**AUTHED_WAITING_CAPTURE** (Order needs to be captured by merchant, applicable for CARD payment) \n **PAY_SUCCESS** \n**ORDER_CLOSE** (due to order cancel, failed or timeout)" }, "orderAction": { "type": "string", "description": "When orderStatus = AUTHORIZATION_REQUIRED, merchant follow the following: \n\"**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.\n\"**webUrl**\": redirect user to webURL\n\"**deeplinkUrl**\": redirect user to deeplink url\n\"actionData\": {\n \"paymentExpiryTime\":\"2023-04-01T03:00:00.000Z\", (Follow ISO 8601 standard)\n \"paymentQr\":\"xxx\", (QR String Value)\n \"paymentCode\":\"xxx\",\n \"paymentBarCode\":\"xxx\",\n \"paymentCurrency\": \"xxx\",\n \"paymentAmount\": \"xxx\",\n \"userFeeAmount\": \"xxx\",\n \"userFeeCurrency\":\"xxx\",\n \"exchangeRate\": \"xxx\", (it is paymentAmount/orderAmount when orderCurrency is not the same as paymentCurrency)\n \"bankAccount\":\"xxx\",\n \"bankName\":\"xxx\",\n \"referenceNumber\":\"xxx\",\n \"bankBeneficiary\":\"xxx\"\n}\nActionData is for those Merchants who want to build their own Cashier Page for their users, without using Waffo's cashier page\n" }, "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" ] }, "ResponseAcqOrderCreatedResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqOrderCreatedResponse" } } }, "OrderCaptureRequest": { "type": "object", "properties": { "paymentRequestId": { "type": "string", "maxLength": 32, "minLength": 0 }, "acquiringOrderId": { "type": "string", "maxLength": 32, "minLength": 0 }, "merchantId": { "type": "string", "maxLength": 32, "minLength": 0 }, "captureRequestedAt": { "type": "string", "format": "date-time" }, "captureAmount": { "type": "string", "maxLength": 32, "minLength": 0 } }, "required": [ "captureAmount", "captureRequestedAt", "merchantId" ] }, "OrderCaptureResponse": { "type": "object", "properties": { "paymentRequestId": { "type": "string" }, "merchantOrderId": { "type": "string" }, "acquiringOrderId": { "type": "string" }, "orderStatus": { "type": "string" }, "compensateSuccess": { "type": "boolean" } } }, "ResponseOrderCaptureResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/OrderCaptureResponse" } } }, "AcqOrderCancelRequest": { "type": "object", "properties": { "paymentRequestId": { "type": "string", "description": "Payment request id sent from Merchant. It will also be used for idempotent check. \n(provide paymentRequestId or acquirerOrderId)", "maxLength": 32, "minLength": 0 }, "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order Id \n(provide paymentRequestId or acquirerOrderId)", "example": "", "maxLength": 32, "minLength": 0 }, "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "orderRequestedAt": { "type": "string", "format": "date-time", "description": "Merchant-side cancel request time", "x-gen": "DATETIME_ISO" } }, "required": [ "merchantId", "orderRequestedAt" ] }, "AcqOrderCancelResponse": { "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_CLOSE** (due to order cancel, failed or timeout)", "example": "ORDER_CLOSE" } }, "required": [ "acquiringOrderId", "merchantOrderId", "orderStatus", "paymentRequestId" ] }, "ResponseAcqOrderCancelResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqOrderCancelResponse" } } }, "AcqMerchantConfigRequest": { "type": "object", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 } }, "required": [ "merchantId" ] }, "AcqMerchantConfigInquiryResponse": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Merchant id assigned by Waffo" }, "totalDailyLimit": { "type": "string", "description": "Daily transaction limit setting. \n If there is a daily limit, it will be returned as json format as `{\"currencyCode1\":\"value1\", \"currencyCode2\":\"value2\"}`\n For example, \n`{\"PHP\":\"100000\", \"IDR\":\"2000000\"}`\nIf there is no limit setting, it will be empty " }, "remainingDailyLimit": { "type": "string", "description": "Remaining Daily transaction limit \nIf there is a remaining daily limit, it will be returned as json format as \n`{\"currencyCode1\":\"value1\", \"currencyCode2\":\"value2\"}` \nFor example, \n`{\"PHP\":\"10000\", \"IDR\":\"1000000\"}`\nIf there is no limit setting, it will be empty " }, "transactionLimit": { "type": "string", "description": "Single transaction limit setting. \nIf there is a limit setting, it will be returned as json format as \n`{\"currencyCode1\":\"value1\", \"currencyCode2\":\"value2\"}` \nFor example, \n`{\"PHP\":\"5000\", \"IDR\":\"100000\"}`\nIf there is no limit set, it will be empty " } }, "required": [ "merchantId" ] }, "ResponseAcqMerchantConfigInquiryResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/AcqMerchantConfigInquiryResponse" } } }, "FraudReportListRequest": { "type": "object", "description": "Reported Fraud list request", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "paymentMethod": { "type": "array", "description": "Card scheme filter. Pass VISA, MASTERCARD or both; a record matches when its card scheme is any of the values passed. Optional — omit it to return all card schemes", "items": { "type": "string" } }, "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order Id filter, to retrieve the fraud reports of a single transaction. Optional — omit it to return every transaction in the date range", "maxLength": 64, "minLength": 0 }, "startDate": { "type": "string", "format": "date", "description": "Start of the query range, inclusive. Filters on fraudReportDate, not on the original transaction time. Format yyyy-MM-dd. The range must not exceed 3 months", "example": "2026-01-01" }, "endDate": { "type": "string", "format": "date", "description": "End of the query range, inclusive. Filters on fraudReportDate, not on the original transaction time. Format yyyy-MM-dd. The range must not exceed 3 months", "example": "2026-03-28" }, "pageNum": { "type": "integer", "format": "int32", "description": "Page number to retrieve, starts from 1", "example": 1 }, "pageSize": { "type": "integer", "format": "int32", "description": "Number of records per page, between 1 and 100", "example": 20 } }, "required": [ "endDate", "merchantId", "pageNum", "pageSize", "startDate" ] }, "ApiPageResponseFraudReportResponse": { "type": "object", "description": "Paged data", "properties": { "records": { "type": "array", "description": "Records of the current page, empty array when nothing matches the query", "items": { "$ref": "#/components/schemas/FraudReportResponse" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of records matching the query", "example": 125 }, "size": { "type": "integer", "format": "int64", "description": "Page size, echoes pageSize in the request", "example": 20 }, "current": { "type": "integer", "format": "int64", "description": "Current page number, starts from 1", "example": 1 }, "pages": { "type": "integer", "format": "int64", "description": "Total number of pages, derived from total and size", "example": 7 } } }, "FraudReportResponse": { "type": "object", "description": "A fraud report raised by the card scheme against one of your transactions. \nReported fraud is the card scheme's own fraud signal and is independent of chargebacks: a reported transaction may never be charged back, and a chargeback may exist without a fraud report.", "properties": { "acquiringOrderId": { "type": "string", "description": "Waffo acquiring order Id, i.e. the transaction this fraud was reported against. Use it with the order inquiry API to retrieve the full order" }, "merchantUserId": { "type": "string", "description": "Merchant user id of the user who made the reported transaction" }, "transactionDateTime": { "type": "string", "description": "The time of the original transaction, always earlier than fraudReportDate. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "paymentRequestId": { "type": "string", "description": "Payment request ID sent from merchant when the reported order was created. Returned for non-subscription payments only — it and subscriptionId are mutually exclusive" }, "subscriptionId": { "type": "string", "description": "The associated Waffo subscription ID. Returned for subscription payments only — it and paymentRequestId are mutually exclusive" }, "merchantSubscriptionId": { "type": "string", "description": "Merchant subscription plan ID assigned to this user. Returned for subscription payments only" }, "fraudReportDate": { "type": "string", "description": "The time the card scheme reported the fraud. This is the field that the startDate and endDate filters apply to. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "fraudAmount": { "type": "string", "description": "Fraud amount reported by the card scheme, in fraudCurrency. May differ from orderAmount" }, "fraudCurrency": { "type": "string", "description": "Fraud amount currency, ISO 4217, e.g. USD. May differ from orderCurrency" }, "orderAmount": { "type": "string", "description": "Amount of the original transaction, in orderCurrency" }, "orderCurrency": { "type": "string", "description": "Original transaction amount currency, ISO 4217, e.g. IDR" }, "fraudReason": { "type": "string", "description": "Fraud reason returned by the card scheme, e.g. Account takeover" }, "fraudReasonCode": { "type": "string", "description": "Fraud reason code returned by the card scheme. The code is scheme-specific, e.g. VI:6 for Visa or MC:5 for Mastercard" }, "paymentMethod": { "type": "string", "description": "Card scheme of the reported transaction, VISA or MASTERCARD. Same value set as the paymentMethod filter in the request" }, "cardType": { "type": "string", "description": "Card type of the reported transaction, e.g. Credit, Debit, Prepaid. Unknown when the card scheme did not report it" }, "cardMaskedNo": { "type": "string", "description": "Masked card number of the reported transaction. Only the masked value is ever returned; Waffo does not expose the full card number" } } }, "ResponseApiPageResponseFraudReportResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ApiPageResponseFraudReportResponse" } } }, "ChargebackUpdateEvidenceRequest": { "type": "object", "description": "Chargeback evidence submission request. \nThis API serves two scenarios depending on the chargeback's lifeCycle: \n**FIRST_CYCLE** (status ACTION_REQUIRED): submit defense evidence. At least one evidence file is required — supply it through message.documents or evidence.othersFile. \n**SECOND_CYCLE** (status SECOND_CYCLE_RESPONSE_REQUIRED, Pre-Arbitration): calling this API — even with message and evidence omitted — defends the case. Evidence submission is not supported in Second Cycle, so message and evidence are ignored. \nOn success the chargeback status becomes UNDER_REVIEW. A successful response means the evidence has passed basic validation and has been accepted by Waffo; Waffo then forwards it to the payment channel for review according to the channel's rules. \nCalls after expiryDateTime are rejected.", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "chargebackId": { "type": "string", "description": "Waffo chargeback order Id", "maxLength": 32, "minLength": 0 }, "message": { "$ref": "#/components/schemas/MessageDto", "description": "Message submitted together with the evidence. \nmessage.documents carries the evidence attachments; in FIRST_CYCLE it satisfies the at-least-one-evidence-file requirement, as does evidence.othersFile. \nIgnored in SECOND_CYCLE." }, "evidence": { "$ref": "#/components/schemas/EvidenceField", "description": "Additional free-form evidence. \nFields are merged per field: a field with a non-blank value overwrites the previously submitted value, and a field that is omitted or blank leaves the previously submitted value unchanged. Repeated calls therefore replace a field's content rather than appending to it. \nIgnored in SECOND_CYCLE." } }, "required": [ "chargebackId", "merchantId" ] }, "EvidenceField": { "type": "object", "description": "Evidence info", "properties": { "othersText": { "type": "string", "description": "Any additional evidence text", "maxLength": 2048, "minLength": 0 }, "othersFile": { "type": "string", "description": "Additional evidence file IDs, comma-separated with no spaces. \nEach file ID must be the exact value returned by the chargeback file upload API. \nIn FIRST_CYCLE this field satisfies the at-least-one-evidence-file requirement on its own, so message.documents may be omitted", "example": "1766043210001/signature.jpg", "maxLength": 1024, "minLength": 0 } } }, "MessageDto": { "type": "object", "description": "Message attached to a chargeback", "properties": { "messageId": { "type": "string", "description": "Message id assigned by Waffo. Returned in responses only — it is ignored when supplied in a request", "maxLength": 64, "minLength": 0, "readOnly": true }, "notes": { "type": "string", "description": "Free-text notes describing the evidence or the reason for the response", "maxLength": 2048, "minLength": 0 }, "documents": { "type": "string", "description": "Attachment file IDs, comma-separated with no spaces, e.g. 1766043193910/receipt.pdf,1766043201234/tracking.png. \nEach file ID must be the exact value returned by the chargeback file upload API", "example": "1766043193910/receipt.pdf,1766043201234/tracking.png", "maxLength": 1024, "minLength": 0 } } }, "ChargebackDetailResponse": { "type": "object", "description": "Chargeback detail response. \nReturned by the chargeback inquiry / update / accept APIs, and used as the result object of the CHARGEBACK_NOTIFICATION webhook. \nIt extends the chargeback list item with the message and evidence objects, which the list API does not return.", "properties": { "chargebackId": { "type": "string", "description": "Chargeback order Id assigned by Waffo" }, "originalOrderId": { "type": "string", "description": "Waffo original order Id, i.e. the acquiring order this chargeback was raised against" }, "originalPaymentRequestId": { "type": "string", "description": "Original payment request ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only" }, "merchantId": { "type": "string", "description": "Merchant Id assigned by Waffo" }, "merchantOrderId": { "type": "string", "description": "Merchant order ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only" }, "lifeCycle": { "type": "string", "description": "Chargeback life cycle \n**FIRST_CYCLE** (First round of the chargeback dispute) \n**SECOND_CYCLE** (Second round (Pre-Arbitration), escalated from First Cycle)" }, "relevantChargebackId": { "type": "string", "description": "The associated chargeback ID between First Cycle and Second Cycle. \nOn a FIRST_CYCLE record it points to the Second Cycle chargeback it was escalated to; on a SECOND_CYCLE record it points back to the originating First Cycle chargeback" }, "chargebackStatus": { "type": "string", "description": "Chargeback status \n**ACTION_REQUIRED** (Submit evidence before expiryDateTime. Amount and fee are debited now) \n**UNDER_REVIEW** (Evidence submitted, under channel review) \n**SECOND_CYCLE_RESPONSE_REQUIRED** (Second Cycle, Pre-Arbitration. Defend or accept; evidence is not accepted. Only the fee is debited) \n**ESCALATE_TO_2ND_CYCLE** (Escalated to Second Cycle. No further debit) \n**CASE_WON** (Channel ruled for merchant. Amount refunded, fee retained) \n**CANCELED** (Withdrawn by the channel or payer. Amount refunded, fee retained) \n**SETTLED** (Settled offline. Amount refunded, fee retained) \n**CASE_LOST** (Channel ruled against merchant. Not refunded) \n**ACCEPTED** (Merchant accepted the chargeback. Not refunded) \n**EXPIRED** (No evidence submitted before expiryDateTime. Not refunded) \nFunds are debited when the chargeback is created, not when it closes. If it later closes in the merchant's favour the amount is refunded and the fee is retained. A case escalated to Second Cycle is not debited twice. CASE_LOST, ACCEPTED and EXPIRED can still change afterwards, so treat the latest notification as authoritative" }, "amount": { "type": "string", "description": "Chargeback order amount. Usually the original transaction amount, but it can be less when only part of the order is disputed" }, "currency": { "type": "string", "description": "Chargeback amount currency, ISO 4217, e.g. IDR" }, "feeAmount": { "type": "string", "description": "Chargeback fee amount charged by Waffo" }, "feeCurrency": { "type": "string", "description": "Chargeback fee currency, ISO 4217. May differ from currency" }, "reasonCode": { "type": "string", "description": "Chargeback reason code returned by the payment channel" }, "reason": { "type": "string", "description": "Chargeback reason returned by the payment channel" }, "description": { "type": "string", "description": "Chargeback description information" }, "chargebackDateTime": { "type": "string", "description": "The time the chargeback was created by the channel. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "expiryDateTime": { "type": "string", "description": "Evidence collection deadline. Evidence submitted after this time is rejected. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "merchantUserId": { "type": "string", "description": "Merchant user id of the user who made the disputed payment" }, "subscriptionInfo": { "$ref": "#/components/schemas/ChargebackQueryResponse.SubscriptionInfo", "description": "The associated subscription info. Present when the chargeback is linked to a subscription payment order." }, "message": { "$ref": "#/components/schemas/MessageDto", "description": "The latest message on this chargeback, from either the merchant or Waffo. Always returned; its fields are empty when there is no message yet" }, "evidence": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Evidence submitted for this chargeback, as key-value pairs of evidence field name to content. Possible keys are othersText (free-form evidence text) and othersFile (evidence file IDs, comma-separated). Always returned; an empty object when no evidence has been submitted" } } }, "ChargebackQueryResponse.SubscriptionInfo": { "type": "object", "description": "The associated subscription info", "properties": { "subscriptionId": { "type": "string", "description": "The associated Waffo subscription ID" }, "period": { "type": "string", "description": "Which period the subscription payment belong to. For example 2" }, "merchantRequest": { "type": "string", "description": "Legacy alias of subscriptionRequest, carrying the same value. Retained for backward compatibility; new integrations should read subscriptionRequest" }, "subscriptionRequest": { "type": "string", "description": "Subscription request id sent from Merchant when the subscription was created. It is also used for the subscription idempotent check" } }, "required": [ "merchantRequest", "period", "subscriptionId", "subscriptionRequest" ] }, "ResponseChargebackDetailResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ChargebackDetailResponse" } } }, "ChargebackListRequest": { "type": "object", "description": "Chargeback list request. \nNote: this API does not return the message and evidence objects. Call the chargeback inquiry API on a specific chargebackId to retrieve them.", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "chargebackStatus": { "type": "array", "description": "Chargeback status filter. Multiple values are combined with OR. \nAccepted values: **ACTION_REQUIRED**, **UNDER_REVIEW**, **SECOND_CYCLE_RESPONSE_REQUIRED**, **ESCALATE_TO_2ND_CYCLE**, **CASE_WON**, **CANCELED**, **SETTLED**, **CASE_LOST**, **ACCEPTED**, **EXPIRED**. \nRefer to chargebackStatus in the response for the meaning of each value. \nRecords in Waffo's internal pending status are never returned by this API, regardless of this filter.", "items": { "type": "string" } }, "lifeCycle": { "type": "string", "description": "Chargeback life cycle filter \n**FIRST_CYCLE** (First round of the chargeback dispute) \n**SECOND_CYCLE** (Second round (Pre-Arbitration), escalated from First Cycle) \nNot specified means both." }, "startTime": { "type": "string", "format": "date-time", "description": "Start time. Filters on the time the chargeback record was created by Waffo, NOT on the time its status was last updated. \nThe range between startTime and endTime must be within 3 months.", "x-gen": "DATETIME_ISO" }, "endTime": { "type": "string", "format": "date-time", "description": "End time. Filters on the time the chargeback record was created by Waffo, NOT on the time its status was last updated. \nThe range between startTime and endTime must be within 3 months.", "x-gen": "DATETIME_ISO" }, "pageNum": { "type": "integer", "format": "int32", "description": "Page number, starting from 1", "example": 1, "minimum": 1 }, "pageSize": { "type": "integer", "format": "int32", "description": "Number of records per page. Maximum: 100", "example": 20, "maximum": 100, "minimum": 1 } }, "required": [ "endTime", "merchantId", "pageNum", "pageSize", "startTime" ] }, "ApiPageResponseChargebackQueryResponse": { "type": "object", "description": "Paged data", "properties": { "records": { "type": "array", "description": "Records of the current page, empty array when nothing matches the query", "items": { "$ref": "#/components/schemas/ChargebackQueryResponse" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of records matching the query", "example": 125 }, "size": { "type": "integer", "format": "int64", "description": "Page size, echoes pageSize in the request", "example": 20 }, "current": { "type": "integer", "format": "int64", "description": "Current page number, starts from 1", "example": 1 }, "pages": { "type": "integer", "format": "int64", "description": "Total number of pages, derived from total and size", "example": 7 } } }, "ChargebackQueryResponse": { "type": "object", "description": "ChargebackQueryResponse", "properties": { "chargebackId": { "type": "string", "description": "Chargeback order Id assigned by Waffo" }, "originalOrderId": { "type": "string", "description": "Waffo original order Id, i.e. the acquiring order this chargeback was raised against" }, "originalPaymentRequestId": { "type": "string", "description": "Original payment request ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only" }, "merchantId": { "type": "string", "description": "Merchant Id assigned by Waffo" }, "merchantOrderId": { "type": "string", "description": "Merchant order ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only" }, "lifeCycle": { "type": "string", "description": "Chargeback life cycle \n**FIRST_CYCLE** (First round of the chargeback dispute) \n**SECOND_CYCLE** (Second round (Pre-Arbitration), escalated from First Cycle)" }, "relevantChargebackId": { "type": "string", "description": "The associated chargeback ID between First Cycle and Second Cycle. \nOn a FIRST_CYCLE record it points to the Second Cycle chargeback it was escalated to; on a SECOND_CYCLE record it points back to the originating First Cycle chargeback" }, "chargebackStatus": { "type": "string", "description": "Chargeback status \n**ACTION_REQUIRED** (Submit evidence before expiryDateTime. Amount and fee are debited now) \n**UNDER_REVIEW** (Evidence submitted, under channel review) \n**SECOND_CYCLE_RESPONSE_REQUIRED** (Second Cycle, Pre-Arbitration. Defend or accept; evidence is not accepted. Only the fee is debited) \n**ESCALATE_TO_2ND_CYCLE** (Escalated to Second Cycle. No further debit) \n**CASE_WON** (Channel ruled for merchant. Amount refunded, fee retained) \n**CANCELED** (Withdrawn by the channel or payer. Amount refunded, fee retained) \n**SETTLED** (Settled offline. Amount refunded, fee retained) \n**CASE_LOST** (Channel ruled against merchant. Not refunded) \n**ACCEPTED** (Merchant accepted the chargeback. Not refunded) \n**EXPIRED** (No evidence submitted before expiryDateTime. Not refunded) \nFunds are debited when the chargeback is created, not when it closes. If it later closes in the merchant's favour the amount is refunded and the fee is retained. A case escalated to Second Cycle is not debited twice. CASE_LOST, ACCEPTED and EXPIRED can still change afterwards, so treat the latest notification as authoritative" }, "amount": { "type": "string", "description": "Chargeback order amount. Usually the original transaction amount, but it can be less when only part of the order is disputed" }, "currency": { "type": "string", "description": "Chargeback amount currency, ISO 4217, e.g. IDR" }, "feeAmount": { "type": "string", "description": "Chargeback fee amount charged by Waffo" }, "feeCurrency": { "type": "string", "description": "Chargeback fee currency, ISO 4217. May differ from currency" }, "reasonCode": { "type": "string", "description": "Chargeback reason code returned by the payment channel" }, "reason": { "type": "string", "description": "Chargeback reason returned by the payment channel" }, "description": { "type": "string", "description": "Chargeback description information" }, "chargebackDateTime": { "type": "string", "description": "The time the chargeback was created by the channel. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "expiryDateTime": { "type": "string", "description": "Evidence collection deadline. Evidence submitted after this time is rejected. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z" }, "merchantUserId": { "type": "string", "description": "Merchant user id of the user who made the disputed payment" }, "subscriptionInfo": { "$ref": "#/components/schemas/ChargebackQueryResponse.SubscriptionInfo", "description": "The associated subscription info. Present when the chargeback is linked to a subscription payment order." } } }, "ResponseApiPageResponseChargebackQueryResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ApiPageResponseChargebackQueryResponse" } } }, "ChargebackInquiryRequest": { "type": "object", "description": "Chargeback inquiry request", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "chargebackId": { "type": "string", "description": "Chargeback order Id. \nProvide either chargebackId or originalOrderId. \nWhen the original order has more than one chargeback (for example after escalation to Second Cycle, which produces two chargeback records), query by chargebackId.", "maxLength": 32, "minLength": 0 }, "originalOrderId": { "type": "string", "description": "Waffo original order Id. \nProvide either chargebackId or originalOrderId. \nOnly applicable when the original order has a single chargeback. If both fields are provided they must refer to the same chargeback.", "maxLength": 32, "minLength": 0 } }, "required": [ "merchantId" ] }, "ChargebackFileUploadResponse": { "type": "object", "description": "Chargeback file upload response", "properties": { "fileId": { "type": "string", "description": "The unique ID of the file, e.g. 1766043193910/receipt.pdf. It contains a slash, so URL-encode it when passing it as a query parameter", "example": "1766043193910/receipt.pdf", "minLength": 1 } }, "required": [ "fileId" ] }, "ResponseChargebackFileUploadResponse": { "type": "object", "description": "response data", "properties": { "code": { "type": "string", "example": 0 }, "msg": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ChargebackFileUploadResponse" } } }, "ChargebackAcceptRequest": { "type": "object", "description": "Chargeback accept request. \nThe amount and fee were already debited when the chargeback was created, so accepting does not trigger a further debit — the case is closed, the merchant is not refunded, and the status becomes ACCEPTED. \n**This action is irreversible** — once accepted, no further evidence can be submitted to contest the case. \nOnly callable when the status is ACTION_REQUIRED or SECOND_CYCLE_RESPONSE_REQUIRED. \nAfter a successful call Waffo also pushes an ACCEPTED notification to the configured chargeback notify URL.", "properties": { "merchantId": { "type": "string", "default": "1000000201", "description": "Merchant Id assigned by Waffo", "example": 1000000201, "maxLength": 64, "minLength": 0 }, "chargebackId": { "type": "string", "description": "Waffo chargeback order Id", "maxLength": 32, "minLength": 0 } }, "required": [ "chargebackId", "merchantId" ] } } }, "x-openapi": { "x-markdownFiles": [] } }