[{"data":1,"prerenderedAt":4251},["ShallowReactive",2],{"docs-context:locales":3,"home-page:en:\u002F":4230},{"en":4,"zh":2130},{"navigation":5,"files":605,"visiblePaths":2129},[6,322,442,553],{"title":7,"deprecated":8,"path":9,"stem":10,"children":11,"page":111},"Payments",null,"\u002Fpayments","payments",[12,39,112],{"title":13,"path":14,"stem":15,"children":16,"deprecated":8},"Get Started","\u002Fpayments\u002Fget-started","payments\u002F01.get-started\u002F01.index",[17,19,23,27,31,35],{"title":18,"path":14,"stem":15,"deprecated":8},"Payments overview",{"title":20,"path":21,"stem":22,"deprecated":8},"Setup","\u002Fpayments\u002Fget-started\u002Fsetup","payments\u002F01.get-started\u002F02.setup",{"title":24,"path":25,"stem":26,"deprecated":8},"Request signing","\u002Fpayments\u002Fget-started\u002Frequest-signing","payments\u002F01.get-started\u002F03.request-signing",{"title":28,"path":29,"stem":30,"deprecated":8},"Webhooks","\u002Fpayments\u002Fget-started\u002Fwebhooks","payments\u002F01.get-started\u002F04.webhooks",{"title":32,"path":33,"stem":34,"deprecated":8},"Currency and amount validation","\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount","payments\u002F01.get-started\u002F06.currency-and-amount",{"title":36,"path":37,"stem":38,"deprecated":8},"Sandbox testing","\u002Fpayments\u002Fget-started\u002Ftesting","payments\u002F01.get-started\u002F07.testing",{"title":40,"deprecated":8,"path":41,"stem":42,"children":43,"page":111},"Online Payments","\u002Fpayments\u002Fonline-payments","payments\u002F02.online-payments",[44,51,58,65,84],{"title":45,"path":46,"stem":47,"children":48,"deprecated":8},"Checkout","\u002Fpayments\u002Fonline-payments\u002Fcheckout","payments\u002F02.online-payments\u002F01.checkout\u002F01.index",[49],{"title":50,"path":46,"stem":47,"deprecated":8},"Checkout integration",{"title":52,"path":53,"stem":54,"children":55,"deprecated":8},"Web SDK","\u002Fpayments\u002Fonline-payments\u002Fsdk","payments\u002F02.online-payments\u002F02.sdk\u002F01.index",[56],{"title":57,"path":53,"stem":54,"deprecated":8},"Web SDK integration",{"title":59,"path":60,"stem":61,"children":62,"deprecated":8},"Direct API","\u002Fpayments\u002Fonline-payments\u002Fapi","payments\u002F02.online-payments\u002F03.api\u002F01.index",[63],{"title":64,"path":60,"stem":61,"deprecated":8},"Direct API integration",{"title":66,"path":67,"stem":68,"children":69,"deprecated":8},"Payment methods","\u002Fpayments\u002Fonline-payments\u002Fpayment-methods","payments\u002F02.online-payments\u002F04.payment-methods\u002F01.index",[70,72,76,80],{"title":71,"path":67,"stem":68,"deprecated":8},"Payment methods overview",{"title":73,"path":74,"stem":75,"deprecated":8},"Apple Pay","\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay","payments\u002F02.online-payments\u002F04.payment-methods\u002F02.apple-pay",{"title":77,"path":78,"stem":79,"deprecated":8},"Google Pay","\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay","payments\u002F02.online-payments\u002F04.payment-methods\u002F03.google-pay",{"title":81,"path":82,"stem":83,"deprecated":8},"Local payment methods","\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods","payments\u002F02.online-payments\u002F04.payment-methods\u002F04.local-payment-methods",{"title":85,"path":86,"stem":87,"children":88,"deprecated":8},"Scenarios","\u002Fpayments\u002Fonline-payments\u002Fscenarios","payments\u002F02.online-payments\u002F05.scenarios\u002F01.index",[89,91,95,99,103,107],{"title":90,"path":86,"stem":87,"deprecated":8},"Scenario overview",{"title":92,"path":93,"stem":94,"deprecated":8},"Saved payment methods","\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods","payments\u002F02.online-payments\u002F05.scenarios\u002F02.saved-payment-methods",{"title":96,"path":97,"stem":98,"deprecated":8},"Subscription payments","\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions","payments\u002F02.online-payments\u002F05.scenarios\u002F03.subscriptions",{"title":100,"path":101,"stem":102,"deprecated":8},"Pre-authorization and capture","\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization","payments\u002F02.online-payments\u002F05.scenarios\u002F04.pre-authorization",{"title":104,"path":105,"stem":106,"deprecated":8},"Profit sharing","\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing","payments\u002F02.online-payments\u002F05.scenarios\u002F05.profit-sharing",{"title":108,"path":109,"stem":110,"deprecated":8},"Refunds","\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds","payments\u002F02.online-payments\u002F05.scenarios\u002F06.refunds",false,{"title":113,"deprecated":8,"path":114,"stem":115,"children":116,"page":111},"API Reference","\u002Fpayments\u002Fapi-reference","payments\u002F04.api-reference",[117,262,318],{"title":118,"deprecated":8,"path":119,"stem":120,"children":121,"page":111},"Endpoints","\u002Fpayments\u002Fapi-reference\u002Fendpoints","payments\u002F04.api-reference\u002F01.endpoints",[122,126,130,134,138,142,146,150,154,158,162,166,170,174,178,182,186,190,194,198,202,206,210,214,218,222,226,230,234,238,242,246,250,254,258],{"title":123,"path":124,"stem":125,"deprecated":8},"Create checkout payment","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-checkout-payment","payments\u002F04.api-reference\u002F01.endpoints\u002F01.create-checkout-payment",{"title":127,"path":128,"stem":129,"deprecated":8},"Create direct transaction","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdirect-create-transaction","payments\u002F04.api-reference\u002F01.endpoints\u002F02.direct-create-transaction",{"title":131,"path":132,"stem":133,"deprecated":8},"Create SDK transaction","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsdk-create-transaction","payments\u002F04.api-reference\u002F01.endpoints\u002F03.sdk-create-transaction",{"title":135,"path":136,"stem":137,"deprecated":8},"Create card token","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-card-token","payments\u002F04.api-reference\u002F01.endpoints\u002F04.create-card-token",{"title":139,"path":140,"stem":141,"deprecated":8},"Delete card token","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdelete-card-token","payments\u002F04.api-reference\u002F01.endpoints\u002F05.delete-card-token",{"title":143,"path":144,"stem":145,"deprecated":8},"Capture or void authorization","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcapture-or-void-authorization","payments\u002F04.api-reference\u002F01.endpoints\u002F06.capture-or-void-authorization",{"title":147,"path":148,"stem":149,"deprecated":8},"List available payment methods","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-available-payment-methods","payments\u002F04.api-reference\u002F01.endpoints\u002F07.list-available-payment-methods",{"title":151,"path":152,"stem":153,"deprecated":8},"Query payments","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-payments","payments\u002F04.api-reference\u002F01.endpoints\u002F08.query-payments",{"title":155,"path":156,"stem":157,"deprecated":8},"Query refunds","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-refunds","payments\u002F04.api-reference\u002F01.endpoints\u002F09.query-refunds",{"title":159,"path":160,"stem":161,"deprecated":8},"List saved tokens","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-saved-tokens","payments\u002F04.api-reference\u002F01.endpoints\u002F10.list-saved-tokens",{"title":163,"path":164,"stem":165,"deprecated":8},"Query subscription details","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-subscription-details","payments\u002F04.api-reference\u002F01.endpoints\u002F11.query-subscription-details",{"title":167,"path":168,"stem":169,"deprecated":8},"Cancel subscription contract","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcancel-subscription-contract","payments\u002F04.api-reference\u002F01.endpoints\u002F12.cancel-subscription-contract",{"title":171,"path":172,"stem":173,"deprecated":8},"Query fraud notifications","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-fraud-notifications","payments\u002F04.api-reference\u002F01.endpoints\u002F13.query-fraud-notifications",{"title":175,"path":176,"stem":177,"deprecated":8},"Query chargebacks","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-chargebacks","payments\u002F04.api-reference\u002F01.endpoints\u002F14.query-chargebacks",{"title":179,"path":180,"stem":181,"deprecated":8},"Query transactions","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-transactions","payments\u002F04.api-reference\u002F01.endpoints\u002F15.query-transactions",{"title":183,"path":184,"stem":185,"deprecated":8},"Create payment link","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-payment-link","payments\u002F04.api-reference\u002F01.endpoints\u002F16.create-payment-link",{"title":187,"path":188,"stem":189,"deprecated":8},"List payment links","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-payment-links","payments\u002F04.api-reference\u002F01.endpoints\u002F17.list-payment-links",{"title":191,"path":192,"stem":193,"deprecated":8},"Update payment link status","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-payment-link-status","payments\u002F04.api-reference\u002F01.endpoints\u002F18.update-payment-link-status",{"title":195,"path":196,"stem":197,"deprecated":8},"Create or cancel refund","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-or-cancel-refund","payments\u002F04.api-reference\u002F01.endpoints\u002F19.create-or-cancel-refund",{"title":199,"path":200,"stem":201,"deprecated":8},"Upload logistics information","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupload-logistics-info","payments\u002F04.api-reference\u002F01.endpoints\u002F20.upload-logistics-info",{"title":203,"path":204,"stem":205,"deprecated":8},"Download settlement file","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdownload-settlement-file","payments\u002F04.api-reference\u002F01.endpoints\u002F21.download-settlement-file",{"title":207,"path":208,"stem":209,"deprecated":8},"Submit Ethoca enrollment","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-ethoca-enrollment","payments\u002F04.api-reference\u002F01.endpoints\u002F22.submit-ethoca-enrollment",{"title":211,"path":212,"stem":213,"deprecated":8},"Query Ethoca enrollments","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-ethoca-enrollments","payments\u002F04.api-reference\u002F01.endpoints\u002F23.query-ethoca-enrollments",{"title":215,"path":216,"stem":217,"deprecated":8},"Update Ethoca enrollment status","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-ethoca-enrollment-status","payments\u002F04.api-reference\u002F01.endpoints\u002F24.update-ethoca-enrollment-status",{"title":219,"path":220,"stem":221,"deprecated":8},"Query Ethoca alerts","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-ethoca-alerts","payments\u002F04.api-reference\u002F01.endpoints\u002F25.query-ethoca-alerts",{"title":223,"path":224,"stem":225,"deprecated":8},"Submit Ethoca alert outcome","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-ethoca-alert-outcome","payments\u002F04.api-reference\u002F01.endpoints\u002F26.submit-ethoca-alert-outcome",{"title":227,"path":228,"stem":229,"deprecated":8},"Submit RDR enrollment","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-rdr-enrollment","payments\u002F04.api-reference\u002F01.endpoints\u002F27.submit-rdr-enrollment",{"title":231,"path":232,"stem":233,"deprecated":8},"Query RDR enrollments","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-rdr-enrollments","payments\u002F04.api-reference\u002F01.endpoints\u002F28.query-rdr-enrollments",{"title":235,"path":236,"stem":237,"deprecated":8},"Update RDR enrollment status","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-rdr-enrollment-status","payments\u002F04.api-reference\u002F01.endpoints\u002F29.update-rdr-enrollment-status",{"title":239,"path":240,"stem":241,"deprecated":8},"Query RDR alerts","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-rdr-alerts","payments\u002F04.api-reference\u002F01.endpoints\u002F30.query-rdr-alerts",{"title":243,"path":244,"stem":245,"deprecated":8},"Create or reverse profit share","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-or-reverse-profit-share","payments\u002F04.api-reference\u002F01.endpoints\u002F31.create-or-reverse-profit-share",{"title":247,"path":248,"stem":249,"deprecated":8},"Query profit share","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-profit-share","payments\u002F04.api-reference\u002F01.endpoints\u002F32.query-profit-share",{"title":251,"path":252,"stem":253,"deprecated":8},"Update SDK order","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsdk-update-order","payments\u002F04.api-reference\u002F01.endpoints\u002F33.sdk-update-order",{"title":255,"path":256,"stem":257,"deprecated":8},"Validate Apple Pay merchant","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fvalidate-apple-pay-merchant","payments\u002F04.api-reference\u002F01.endpoints\u002F34.validate-apple-pay-merchant",{"title":259,"path":260,"stem":261,"deprecated":8},"Check Google Pay PAN_ONLY token","\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcheck-google-pay-pan-only","payments\u002F04.api-reference\u002F01.endpoints\u002F35.check-google-pay-pan-only",{"title":28,"deprecated":8,"path":263,"stem":264,"children":265,"page":111},"\u002Fpayments\u002Fapi-reference\u002Fwebhooks","payments\u002F04.api-reference\u002F02.webhooks",[266,270,274,278,282,286,290,294,298,302,306,310,314],{"title":267,"path":268,"stem":269,"deprecated":8},"Fraud alert webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Ffraud-alert","payments\u002F04.api-reference\u002F02.webhooks\u002F01.fraud-alert",{"title":271,"path":272,"stem":273,"deprecated":8},"Ethoca alert webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fethoca-alert-created","payments\u002F04.api-reference\u002F02.webhooks\u002F02.ethoca-alert-created",{"title":275,"path":276,"stem":277,"deprecated":8},"Payment result webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fpayment-result","payments\u002F04.api-reference\u002F02.webhooks\u002F03.payment-result",{"title":279,"path":280,"stem":281,"deprecated":8},"Subscription payment webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fsubscription-payment","payments\u002F04.api-reference\u002F02.webhooks\u002F04.subscription-payment",{"title":283,"path":284,"stem":285,"deprecated":8},"Authorization, capture, and void webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fauthorization-capture","payments\u002F04.api-reference\u002F02.webhooks\u002F05.authorization-capture",{"title":287,"path":288,"stem":289,"deprecated":8},"Profit share result webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fprofit-share-result","payments\u002F04.api-reference\u002F02.webhooks\u002F06.profit-share-result",{"title":291,"path":292,"stem":293,"deprecated":8},"Saved payment method result webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fpayment-method-result","payments\u002F04.api-reference\u002F02.webhooks\u002F07.payment-method-result",{"title":295,"path":296,"stem":297,"deprecated":8},"Ethoca enrollment status webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fethoca-enrollment-changed","payments\u002F04.api-reference\u002F02.webhooks\u002F08.ethoca-enrollment-changed",{"title":299,"path":300,"stem":301,"deprecated":8},"RDR enrollment status webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frdr-enrollment-changed","payments\u002F04.api-reference\u002F02.webhooks\u002F09.rdr-enrollment-changed",{"title":303,"path":304,"stem":305,"deprecated":8},"Refund result webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frefund-result","payments\u002F04.api-reference\u002F02.webhooks\u002F10.refund-result",{"title":307,"path":308,"stem":309,"deprecated":8},"Refund request rejection webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frefund-audit-rejected","payments\u002F04.api-reference\u002F02.webhooks\u002F11.refund-audit-rejected",{"title":311,"path":312,"stem":313,"deprecated":8},"Chargeback alert webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fchargeback-alert-created","payments\u002F04.api-reference\u002F02.webhooks\u002F12.chargeback-alert-created",{"title":315,"path":316,"stem":317,"deprecated":8},"Chargeback status change webhook","\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fchargeback-status-changed","payments\u002F04.api-reference\u002F02.webhooks\u002F13.chargeback-status-changed",{"title":319,"path":320,"stem":321,"deprecated":8},"Response codes","\u002Fpayments\u002Fapi-reference\u002Fresponse-codes","payments\u002F04.api-reference\u002F03.response-codes",{"title":323,"deprecated":8,"path":324,"stem":325,"children":326,"page":111},"Transfer","\u002Ftransfer","transfer",[327,348],{"title":13,"path":328,"stem":329,"children":330,"deprecated":8},"\u002Ftransfer\u002Fget-started","transfer\u002F01.get-started\u002F01.index",[331,333,336,340,344],{"title":332,"path":328,"stem":329,"deprecated":8},"Overview",{"title":24,"path":334,"stem":335,"deprecated":8},"\u002Ftransfer\u002Fget-started\u002Frequest-signing","transfer\u002F01.get-started\u002F03.request-signing",{"title":337,"path":338,"stem":339,"deprecated":8},"Integration flow","\u002Ftransfer\u002Fget-started\u002Fintegration-flow","transfer\u002F01.get-started\u002F04.integration-flow",{"title":341,"path":342,"stem":343,"deprecated":8},"Testing and go-live","\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live","transfer\u002F01.get-started\u002F05.testing-and-go-live",{"title":345,"path":346,"stem":347,"deprecated":8},"Change log","\u002Ftransfer\u002Fget-started\u002Fchange-log","transfer\u002F01.get-started\u002F08.change-log",{"title":113,"deprecated":8,"path":349,"stem":350,"children":351},"\u002Ftransfer\u002Fapi-reference","transfer\u002F04.api-reference\u002F01.index",[352,354,430,438],{"title":353,"path":349,"stem":350,"deprecated":8},"Integration Guide",{"title":118,"deprecated":8,"path":355,"stem":356,"children":357,"page":111},"\u002Ftransfer\u002Fapi-reference\u002Fendpoints","transfer\u002F04.api-reference\u002F01.endpoints",[358,362,366,370,374,378,382,386,390,394,398,402,406,410,414,418,422,426],{"title":359,"path":360,"stem":361,"deprecated":8},"Transfer Method Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfer-methods","transfer\u002F04.api-reference\u002F01.endpoints\u002F01.query-transfer-methods",{"title":363,"path":364,"stem":365,"deprecated":8},"Beneficiary Required Fields Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-required-fields","transfer\u002F04.api-reference\u002F01.endpoints\u002F02.query-required-fields",{"title":367,"path":368,"stem":369,"deprecated":8},"Beneficiary Add","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fcreate-beneficiary","transfer\u002F04.api-reference\u002F01.endpoints\u002F03.create-beneficiary",{"title":371,"path":372,"stem":373,"deprecated":8},"Beneficiary Details Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fget-beneficiary-details","transfer\u002F04.api-reference\u002F01.endpoints\u002F04.get-beneficiary-details",{"title":375,"path":376,"stem":377,"deprecated":8},"Payer Add","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fcreate-payer","transfer\u002F04.api-reference\u002F01.endpoints\u002F05.create-payer",{"title":379,"path":380,"stem":381,"deprecated":8},"Transfer with beneficiary ID","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Finitiate-transfer-by-beneficiary-id","transfer\u002F04.api-reference\u002F01.endpoints\u002F06.initiate-transfer-by-beneficiary-id",{"title":383,"path":384,"stem":385,"deprecated":8},"Transfer Single Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfer","transfer\u002F04.api-reference\u002F01.endpoints\u002F08.query-transfer",{"title":387,"path":388,"stem":389,"deprecated":8},"Transfer Batch Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfers","transfer\u002F04.api-reference\u002F01.endpoints\u002F09.query-transfers",{"title":391,"path":392,"stem":393,"deprecated":8},"Transfer Voucher Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdownload-transfer-voucher","transfer\u002F04.api-reference\u002F01.endpoints\u002F10.download-transfer-voucher",{"title":395,"path":396,"stem":397,"deprecated":8},"Beneficiary List Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Flist-beneficiaries","transfer\u002F04.api-reference\u002F01.endpoints\u002F11.list-beneficiaries",{"title":399,"path":400,"stem":401,"deprecated":8},"Beneficiary Edit","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fupdate-beneficiary","transfer\u002F04.api-reference\u002F01.endpoints\u002F12.update-beneficiary",{"title":403,"path":404,"stem":405,"deprecated":8},"Beneficiary Delete","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdelete-beneficiary","transfer\u002F04.api-reference\u002F01.endpoints\u002F13.delete-beneficiary",{"title":407,"path":408,"stem":409,"deprecated":8},"Payer Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-payer","transfer\u002F04.api-reference\u002F01.endpoints\u002F14.query-payer",{"title":411,"path":412,"stem":413,"deprecated":8},"Payer Edit","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fupdate-payer","transfer\u002F04.api-reference\u002F01.endpoints\u002F15.update-payer",{"title":415,"path":416,"stem":417,"deprecated":8},"Payer Delete","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdelete-payer","transfer\u002F04.api-reference\u002F01.endpoints\u002F16.delete-payer",{"title":419,"path":420,"stem":421,"deprecated":8},"Account Currency Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-account-currencies","transfer\u002F04.api-reference\u002F01.endpoints\u002F17.query-account-currencies",{"title":423,"path":424,"stem":425,"deprecated":8},"Account Detail Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-account-details","transfer\u002F04.api-reference\u002F01.endpoints\u002F18.query-account-details",{"title":427,"path":428,"stem":429,"deprecated":8},"FX Rate Query","\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-exchange-rate","transfer\u002F04.api-reference\u002F01.endpoints\u002F19.query-exchange-rate",{"title":28,"deprecated":8,"path":431,"stem":432,"children":433,"page":111},"\u002Ftransfer\u002Fapi-reference\u002Fwebhooks","transfer\u002F04.api-reference\u002F02.webhooks",[434],{"title":435,"path":436,"stem":437,"deprecated":8},"Transfer Callback","\u002Ftransfer\u002Fapi-reference\u002Fwebhooks\u002Ftransfer-result","transfer\u002F04.api-reference\u002F02.webhooks\u002F01.transfer-result",{"title":439,"path":440,"stem":441,"deprecated":8},"Enumeration Descriptions","\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes","transfer\u002F04.api-reference\u002F03.response-codes",{"title":443,"deprecated":8,"path":444,"stem":445,"children":446,"page":111},"Issuing","\u002Fissuing","issuing",[447,455],{"title":13,"path":448,"stem":449,"children":450,"deprecated":8},"\u002Fissuing\u002Fget-started","issuing\u002F01.get-started\u002F01.index",[451,452],{"title":332,"path":448,"stem":449,"deprecated":8},{"title":20,"path":453,"stem":454,"deprecated":8},"\u002Fissuing\u002Fget-started\u002Fsetup","issuing\u002F01.get-started\u002F02.setup",{"title":113,"path":456,"stem":457,"children":458,"deprecated":8},"\u002Fissuing\u002Fapi-reference","issuing\u002F04.api-reference\u002F01.index",[459,461,533,537],{"title":460,"path":456,"stem":457,"deprecated":8},"API specifications",{"title":118,"deprecated":8,"path":462,"stem":463,"children":464,"page":111},"\u002Fissuing\u002Fapi-reference\u002Fendpoints","issuing\u002F04.api-reference\u002F02.endpoints",[465,469,473,477,481,485,489,493,497,501,505,509,513,517,521,525,529],{"title":466,"path":467,"stem":468,"deprecated":8},"Create card","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcreate-card","issuing\u002F04.api-reference\u002F02.endpoints\u002F01.create-card",{"title":470,"path":471,"stem":472,"deprecated":8},"Operate card","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Foperate-card","issuing\u002F04.api-reference\u002F02.endpoints\u002F02.operate-card",{"title":474,"path":475,"stem":476,"deprecated":8},"Deposit card","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fdeposit-card","issuing\u002F04.api-reference\u002F02.endpoints\u002F03.deposit-card",{"title":478,"path":479,"stem":480,"deprecated":8},"Withdraw card balance","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Freturn-card-balance","issuing\u002F04.api-reference\u002F02.endpoints\u002F04.return-card-balance",{"title":482,"path":483,"stem":484,"deprecated":8},"Query card operation records","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-operate-record-list","issuing\u002F04.api-reference\u002F02.endpoints\u002F05.get-operate-record-list",{"title":486,"path":487,"stem":488,"deprecated":8},"Get card basic info","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-basic-info","issuing\u002F04.api-reference\u002F02.endpoints\u002F06.get-basic-info",{"title":490,"path":491,"stem":492,"deprecated":8},"Get card balance","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-balance-info","issuing\u002F04.api-reference\u002F02.endpoints\u002F07.get-balance-info",{"title":494,"path":495,"stem":496,"deprecated":8},"Get card sensitive info","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-sensitive-info","issuing\u002F04.api-reference\u002F02.endpoints\u002F08.get-sensitive-info",{"title":498,"path":499,"stem":500,"deprecated":8},"Create cardholder","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcreate-cardholder","issuing\u002F04.api-reference\u002F02.endpoints\u002F09.create-cardholder",{"title":502,"path":503,"stem":504,"deprecated":8},"Update cardholder","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fupdate-cardholder","issuing\u002F04.api-reference\u002F02.endpoints\u002F10.update-cardholder",{"title":506,"path":507,"stem":508,"deprecated":8},"Query cardholders","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-cardholders","issuing\u002F04.api-reference\u002F02.endpoints\u002F12.query-cardholders",{"title":510,"path":511,"stem":512,"deprecated":8},"Region list","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fregion-list","issuing\u002F04.api-reference\u002F02.endpoints\u002F13.region-list",{"title":514,"path":515,"stem":516,"deprecated":8},"City list","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcity-list","issuing\u002F04.api-reference\u002F02.endpoints\u002F14.city-list",{"title":518,"path":519,"stem":520,"deprecated":8},"Mobile area code list","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fmobile-area-code-list","issuing\u002F04.api-reference\u002F02.endpoints\u002F15.mobile-area-code-list",{"title":522,"path":523,"stem":524,"deprecated":8},"Query transaction records","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-transaction-records","issuing\u002F04.api-reference\u002F02.endpoints\u002F16.query-transaction-records",{"title":526,"path":527,"stem":528,"deprecated":8},"Query 3DS records","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-3ds-records","issuing\u002F04.api-reference\u002F02.endpoints\u002F17.query-3ds-records",{"title":530,"path":531,"stem":532,"deprecated":8},"List card products","\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Flist-card-products","issuing\u002F04.api-reference\u002F02.endpoints\u002F18.list-card-products",{"title":534,"path":535,"stem":536,"deprecated":8},"WEBHOOK description","\u002Fissuing\u002Fapi-reference\u002Fwebhook-description","issuing\u002F04.api-reference\u002F03.webhook-description",{"title":28,"deprecated":8,"path":538,"stem":539,"children":540,"page":111},"\u002Fissuing\u002Fapi-reference\u002Fwebhooks","issuing\u002F04.api-reference\u002F06.webhooks",[541,545,549],{"title":542,"path":543,"stem":544,"deprecated":8},"Card operation event","\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-operation-event","issuing\u002F04.api-reference\u002F06.webhooks\u002F01.card-operation-event",{"title":546,"path":547,"stem":548,"deprecated":8},"Card transaction event","\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-transaction-event","issuing\u002F04.api-reference\u002F06.webhooks\u002F02.card-transaction-event",{"title":550,"path":551,"stem":552,"deprecated":8},"3DS Event","\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-threeds-event","issuing\u002F04.api-reference\u002F06.webhooks\u002F03.card-threeds-event",{"title":554,"deprecated":8,"path":555,"stem":556,"children":557,"page":111},"Account","\u002Faccount","account",[558,566],{"title":13,"path":559,"stem":560,"children":561,"deprecated":8},"\u002Faccount\u002Fget-started","account\u002F01.get-started\u002F01.index",[562,563],{"title":332,"path":559,"stem":560,"deprecated":8},{"title":20,"path":564,"stem":565,"deprecated":8},"\u002Faccount\u002Fget-started\u002Fsetup","account\u002F01.get-started\u002F02.setup",{"title":113,"deprecated":8,"path":567,"stem":568,"children":569,"page":111},"\u002Faccount\u002Fapi-reference","account\u002F04.api-reference",[570,602],{"title":118,"deprecated":8,"path":571,"stem":572,"children":573,"page":111},"\u002Faccount\u002Fapi-reference\u002Fendpoints","account\u002F04.api-reference\u002F01.endpoints",[574,578,582,586,590,594,598],{"title":575,"path":576,"stem":577,"deprecated":8},"Create a Global Account","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fcreate-global-account","account\u002F04.api-reference\u002F01.endpoints\u002F01.create-global-account",{"title":579,"path":580,"stem":581,"deprecated":8},"Get Global Account details","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fget-global-account-details","account\u002F04.api-reference\u002F01.endpoints\u002F02.get-global-account-details",{"title":583,"path":584,"stem":585,"deprecated":8},"Query account balance movements","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-transactions","account\u002F04.api-reference\u002F01.endpoints\u002F03.query-account-transactions",{"title":587,"path":588,"stem":589,"deprecated":8},"Query account transactions by transaction order number","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-transactions-by-service-id","account\u002F04.api-reference\u002F01.endpoints\u002F04.query-account-transactions-by-service-id",{"title":591,"path":592,"stem":593,"deprecated":8},"Query account balance","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-balance","account\u002F04.api-reference\u002F01.endpoints\u002F05.query-account-balance",{"title":595,"path":596,"stem":597,"deprecated":8},"Query account balance overview","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-balance-overview","account\u002F04.api-reference\u002F01.endpoints\u002F06.query-account-balance-overview",{"title":599,"path":600,"stem":601,"deprecated":8},"Export daily account statement","\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fexport-daily-statement","account\u002F04.api-reference\u002F01.endpoints\u002F07.export-daily-statement",{"title":319,"path":603,"stem":604,"deprecated":8},"\u002Faccount\u002Fapi-reference\u002Fresponse-codes","account\u002F04.api-reference\u002F03.response-codes",[606,610,616,619,624,629,632,637,642,647,652,657,662,668,673,678,683,688,691,696,701,706,711,716,721,726,731,734,739,744,749,754,759,762,767,772,777,782,785,789,794,799,804,809,813,818,821,825,830,835,840,845,850,855,860,865,870,875,880,885,890,895,900,904,909,914,918,922,925,930,934,939,943,947,952,956,960,964,967,972,977,982,985,990,995,999,1004,1009,1013,1018,1023,1028,1032,1035,1039,1043,1048,1053,1058,1063,1068,1073,1077,1082,1086,1090,1094,1098,1101,1106,1110,1114,1119,1124,1129,1134,1138,1141,1146,1151,1154,1159,1164,1169,1172,1176,1180,1185,1190,1194,1197,1201,1205,1209,1212,1216,1220,1225,1230,1234,1237,1241,1246,1251,1256,1259,1262,1265,1268,1271,1274,1277,1280,1283,1286,1289,1292,1295,1298,1301,1304,1307,1310,1313,1316,1319,1322,1325,1328,1331,1334,1337,1340,1343,1346,1349,1352,1355,1358,1361,1364,1367,1370,1373,1376,1379,1382,1385,1388,1391,1394,1397,1400,1403,1408,1413,1418,1423,1428,1433,1438,1443,1448,1453,1458,1463,1466,1470,1475,1480,1485,1490,1495,1500,1503,1508,1512,1517,1522,1527,1532,1537,1542,1546,1550,1554,1559,1563,1567,1571,1576,1579,1583,1587,1592,1597,1601,1606,1610,1616,1621,1626,1631,1636,1641,1646,1651,1656,1660,1665,1670,1675,1680,1685,1688,1693,1698,1703,1708,1713,1717,1722,1727,1732,1736,1739,1744,1747,1750,1753,1756,1759,1762,1767,1770,1773,1776,1779,1782,1785,1788,1791,1794,1797,1800,1803,1806,1811,1816,1820,1825,1830,1835,1840,1843,1846,1851,1856,1861,1866,1871,1876,1881,1886,1891,1896,1901,1905,1910,1913,1918,1923,1927,1930,1935,1939,1943,1946,1951,1956,1960,1965,1969,1972,1975,1978,1981,1984,1987,1990,1993,1996,1999,2002,2005,2008,2011,2014,2017,2020,2023,2027,2032,2037,2042,2045,2048,2051,2054,2059,2064,2069,2074,2077,2081,2086,2091,2095,2098,2101,2104,2107,2110,2113,2116,2119,2124],{"id":14,"title":18,"titles":607,"content":608,"level":609},[],"Onerway payment acceptance guides and API reference. Use Onerway Payments to accept online payments, prepare API credentials, validate payment requests, and connect your server-side integration with Checkout, webhooks, refunds, disputes, and API Reference pages.",1,{"id":611,"title":612,"titles":613,"content":614,"level":615},"\u002Fpayments\u002Fget-started#start-here","Start here",[18],"Setup — activate your sandbox account, obtain API credentials, configure the IP allowlist for the target environment, and prepare to go liveRequest signing — generate the sign value required by Payments API requestsWebhooks — verify, acknowledge, and deduplicate payment notifications, and fall back to query APIs when no notification arrivesScenarios — saved payment methods, subscriptions, and pre-authorization by concept, lifecycle, and notifications, with parameter differences across integration methodsPayment methods — how cards, wallets, and each local payment method are supported by each integration method, plus Apple Pay and Google Pay setup and flowsCurrency and amount validation — validate currency and amount formats before creating payment requestsCheckout API Reference — review the endpoint contract for creating a Checkout payment",2,{"id":21,"title":20,"titles":617,"content":618,"level":609},[],"Activate a sandbox account, obtain API credentials, configure your IP allowlist, and send your first test transaction before going live. To integrate with Onerway Payments, first activate a sandbox account, obtain API credentials, and configure the sandbox IP allowlist. Develop and test your integration in the sandbox before configuring the production environment and going live.",{"id":620,"title":621,"titles":622,"content":623,"level":615},"\u002Fpayments\u002Fget-started\u002Fsetup#integration-steps","Integration steps",[20],"Activate your sandbox accountContact Onerway technical support with your email address and test domain to receive a dashboard invitation. Once you click the link in that email, your merchant account is active in the sandbox.If you show the Apple Pay button on your own pages through the Web SDK or the Direct API, every sandbox and production domain involved must pass Apple domain verification, either through your own Apple Developer account or registered by Onerway; the Onerway-hosted checkout page does not need this step. See Apple Pay setup.For Google Pay through the Direct API, complete website registration before going live; Checkout and the Web SDK need no registration.Retrieve your credentialsLog in to the merchant portal and obtain the following API credentials for server-side API calls.CredentialPathDirect linkmerchantNoSettings → User infoSandbox · ProductionappIdSettings → Payment → Application listSandbox · ProductionsecretDevelopers → API credentialsSandbox · ProductionKeep your secret on the server side. Never embed it in client-side code, mobile binaries, or version control.Configure your IP allowlistBefore making your first server-side API request in the sandbox, you must add every public IP address from which your server calls Onerway to the sandbox IP allowlist. In the sandbox merchant portal, go to Developers → IP allowlist and add these addresses. Use your server's outbound IP addresses, not the IP addresses of customers visiting your website.Configure the IP allowlist separately for the sandbox and production environments. Before going live, you must add all public outbound IP addresses used by your production servers in the production merchant portal. Add the IP addresses in each environment even if they are the same.EnvironmentWhen to configurePortal linkSandboxBefore your first server-side API request in the sandboxSandbox IP allowlistProductionBefore your first server-side API request in productionProduction IP allowlistWhen the IP allowlist is enabled, requests from IP addresses that are not on the allowlist for the target environment may be rejected.Build and testAfter configuring the sandbox IP allowlist, use your sandbox credentials to develop and test your integration. Verify all payment flows, error handling, and webhooks. Before switching to the production API base URL and credentials, you must add your production servers' public outbound IP addresses to the production IP allowlist. Also complete any required payment method setup, such as Apple Pay domain verification or Google Pay website registration.",{"id":625,"title":626,"titles":627,"content":628,"level":615},"\u002Fpayments\u002Fget-started\u002Fsetup#next-steps","Next steps",[20],"Request signing — learn how Onerway authenticates requests via signatures and how to generate signCurrency and amount validation — validate orderCurrency, orderAmount, and payment method limits before creating a payment requestSandbox testing — use sandbox test cards to validate success, failure, subscription, and token payment scenarios",{"id":25,"title":24,"titles":630,"content":631,"level":609},[],"Learn how Onerway authenticates API requests with request signatures, how to generate the sign field, and how to verify webhook notifications. Onerway authenticates API requests using the sign field. Generate the sign dynamically on your server using the environment-specific SECRET. Never expose the SECRET in frontend code, mobile applications, or public repositories. Before sending server-side API requests, you must also configure the IP allowlist for the target environment. Configure sandbox and production allowlists separately.",{"id":633,"title":634,"titles":635,"content":636,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#signing-rules","Signing rules",[24],"Generate the sign dynamically using the following rules: Exclude the sign field.Exclude fields with null, undefined, or empty string values.Serialize object (Object) and array (Array) values into compact JSON strings (without extra spaces or line breaks); see Object and array fields for nested structures.Sort field names in ascending ASCII order.Concatenate only the sorted field values directly. Do not include field names, equals signs (=), ampersands (&), or any other separators. The resulting string is called the Canonical String.Append the SECRET to the end of the Canonical String.Compute the SHA-256 hash of the final string and output the result as a lowercase hexadecimal string. Non-string scalars are concatenated as strings: booleans become true \u002F false; numbers use their decimal string form without trailing zeros or scientific notation (for example 1.10 is concatenated as 1.1).",{"id":638,"title":639,"titles":640,"content":641,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#object-and-array-fields","Object and array fields",[24],"Object and array fields must be serialized into compact JSON strings: {\n \"billingInformation\": {\n \"country\": \"US\",\n \"email\": \"customer@test.com\"\n }\n} After conversion, the value used for signing and sending is: {\n \"billingInformation\": \"{\\\"country\\\":\\\"US\\\",\\\"email\\\":\\\"customer@test.com\\\"}\"\n} Nested values are serialized from the inside out. For example, txnOrderMsg.products is an array, so it becomes a JSON string inside the txnOrderMsg string: {\n \"txnOrderMsg\": \"{\\\"appId\\\":\\\"replace_with_app_id\\\",\\\"products\\\":\\\"[{\\\\\\\"currency\\\\\\\":\\\\\\\"USD\\\\\\\",\\\\\\\"name\\\\\\\":\\\\\\\"test product\\\\\\\",\\\\\\\"num\\\\\\\":\\\\\\\"1\\\\\\\",\\\\\\\"price\\\\\\\":\\\\\\\"1\\\\\\\"}]\\\",\\\"returnUrl\\\":\\\"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\\\"}\"\n}",{"id":643,"title":644,"titles":645,"content":646,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#request-example","Request example",[24],"The original request can retain object structures with an empty sign field: {\n \"merchantNo\": \"replace_with_merchant_no\",\n \"merchantTxnId\": \"replace_with_unique_transaction_id\",\n \"merchantTxnTime\": \"2026-04-24 15:37:39\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"billingInformation\": {\n \"country\": \"US\",\n \"email\": \"customer@test.com\",\n \"province\": \"CA\"\n },\n \"txnOrderMsg\": {\n \"appId\": \"replace_with_app_id\",\n \"products\": [\n {\n \"currency\": \"USD\",\n \"name\": \"test product\",\n \"num\": \"1\",\n \"price\": \"1\"\n }\n ],\n \"returnUrl\": \"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\"\n },\n \"productType\": \"CARD\",\n \"subProductType\": \"DIRECT\",\n \"txnType\": \"SALE\",\n \"sign\": null\n} Before sending, convert object values to strings and fill in the calculated sign: {\n \"billingInformation\": \"{\\\"country\\\":\\\"US\\\",\\\"email\\\":\\\"customer@test.com\\\",\\\"province\\\":\\\"CA\\\"}\",\n \"merchantNo\": \"replace_with_merchant_no\",\n \"merchantTxnId\": \"replace_with_unique_transaction_id\",\n \"merchantTxnTime\": \"2026-04-24 15:37:39\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"productType\": \"CARD\",\n \"sign\": \"replace_with_calculated_signature\",\n \"subProductType\": \"DIRECT\",\n \"txnOrderMsg\": \"{\\\"appId\\\":\\\"replace_with_app_id\\\",\\\"products\\\":\\\"[{\\\\\\\"currency\\\\\\\":\\\\\\\"USD\\\\\\\",\\\\\\\"name\\\\\\\":\\\\\\\"test product\\\\\\\",\\\\\\\"num\\\\\\\":\\\\\\\"1\\\\\\\",\\\\\\\"price\\\\\\\":\\\\\\\"1\\\\\\\"}]\\\",\\\"returnUrl\\\":\\\"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\\\"}\",\n \"txnType\": \"SALE\"\n} You may sort the final request body by field name for easier troubleshooting. Signature validity strictly depends on the sorting and concatenation rules, not on the displayed body order.",{"id":648,"title":649,"titles":650,"content":651,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#worked-example","Worked example",[24],"Use this minimal request with the example secret example_secret to check your implementation: {\n \"merchantNo\": \"demo_merchant_no\",\n \"merchantTxnId\": \"demo_txn_id_001\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"sign\": null\n} Canonical String: demo_merchant_nodemo_txn_id_0011USD\nString to hash: demo_merchant_nodemo_txn_id_0011USDexample_secret\nsign: 8af506acd9322fcab9d676dd9b861512f194d9ab724eacdb358d90d087d9caac",{"id":653,"title":654,"titles":655,"content":656,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#code-examples","Code examples",[24],"The examples below assume the input is a server-side map (Map) or object (Object); if a field is already a JSON string, ensure it has been serialized with the same inside-out rule. Use the normalizeValue result for both signing and the final request body; do not rebuild object or array fields with a different serializer after calculating the signature — this causes verification failures on the gateway. \u003C?php\n\nfunction is_assoc_array(array $value): bool {\n if ($value === []) {\n return false;\n }\n return array_keys($value) !== range(0, count($value) - 1);\n}\n\nfunction normalize_nested($value) {\n if (!is_array($value)) {\n return $value;\n }\n\n if (!is_assoc_array($value)) {\n return array_map('normalize_nested', $value);\n }\n\n $result = [];\n foreach ($value as $key => $child) {\n $result[$key] = is_array($child)\n ? json_encode(normalize_nested($child), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)\n : $child;\n }\n return $result;\n}\n\nfunction normalize_value($value) {\n if ($value === null || $value === '') {\n return $value;\n }\n if (is_bool($value)) {\n return $value ? 'true' : 'false';\n }\n return is_array($value)\n ? json_encode(normalize_nested($value), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)\n : (string) $value;\n}\n\nfunction generate_signature(array $payload, string $secret): string {\n $normalized = [];\n foreach ($payload as $key => $value) {\n if ($key !== 'sign') {\n $normalized[$key] = normalize_value($value);\n }\n }\n\n ksort($normalized, SORT_STRING);\n\n $canonical = '';\n foreach ($normalized as $value) {\n if ($value !== null && $value !== '') {\n $canonical .= $value;\n }\n }\n\n return hash('sha256', $canonical . $secret);\n}\nimport com.fasterxml.jackson.core.JsonProcessingException;\nimport com.fasterxml.jackson.databind.ObjectMapper;\n\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.util.ArrayList;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.TreeMap;\n\npublic final class OnerwaySign {\n private static final ObjectMapper JSON = new ObjectMapper();\n\n private static Object normalizeNested(Object value) throws JsonProcessingException {\n if (value instanceof List\u003C?> list) {\n List\u003CObject> result = new ArrayList\u003C>();\n for (Object item : list) {\n result.add(normalizeNested(item));\n }\n return result;\n }\n\n if (value instanceof Map\u003C?, ?> map) {\n TreeMap\u003CString, Object> result = new TreeMap\u003C>();\n for (Map.Entry\u003C?, ?> entry : map.entrySet()) {\n Object child = entry.getValue();\n result.put(\n String.valueOf(entry.getKey()),\n child instanceof Map\u003C?, ?> || child instanceof List\u003C?>\n ? JSON.writeValueAsString(normalizeNested(child))\n : child\n );\n }\n return result;\n }\n\n return value;\n }\n\n private static String normalizeValue(Object value) throws JsonProcessingException {\n if (value == null) {\n return null;\n }\n if (value instanceof String text) {\n return text.isEmpty() ? null : text;\n }\n if (value instanceof Map\u003C?, ?> || value instanceof List\u003C?>) {\n return JSON.writeValueAsString(normalizeNested(value));\n }\n return String.valueOf(value);\n }\n\n public static String generateSignature(Map\u003CString, Object> payload, String secret) throws Exception {\n TreeMap\u003CString, String> normalized = new TreeMap\u003C>();\n for (Map.Entry\u003CString, Object> entry : payload.entrySet()) {\n if (!\"sign\".equals(entry.getKey())) {\n normalized.put(entry.getKey(), normalizeValue(entry.getValue()));\n }\n }\n\n StringBuilder canonical = new StringBuilder();\n for (String value : normalized.values()) {\n if (value != null && !value.isEmpty()) {\n canonical.append(value);\n }\n }\n\n MessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\n byte[] hash = digest.digest((canonical + secret).getBytes(StandardCharsets.UTF_8));\n\n StringBuilder hex = new StringBuilder();\n for (byte b : hash) {\n hex.append(String.format(\"%02x\", b));\n }\n return hex.toString();\n }\n}\npackage signing\n\nimport (\n \"crypto\u002Fsha256\"\n \"encoding\u002Fhex\"\n \"encoding\u002Fjson\"\n \"fmt\"\n \"sort\"\n)\n\nfunc normalizeNested(value any) any {\n switch typed := value.(type) {\n case []any:\n result := make([]any, len(typed))\n for i, item := range typed {\n result[i] = normalizeNested(item)\n }\n return result\n case map[string]any:\n result := map[string]any{}\n for key, child := range typed {\n switch child.(type) {\n case map[string]any, []any:\n bytes, _ := json.Marshal(normalizeNested(child))\n result[key] = string(bytes)\n default:\n result[key] = child\n }\n }\n return result\n default:\n return value\n }\n}\n\nfunc normalizeValue(value any) *string {\n if value == nil {\n return nil\n }\n\n switch typed := value.(type) {\n case string:\n if typed == \"\" {\n return nil\n }\n return &typed\n case map[string]any, []any:\n bytes, _ := json.Marshal(normalizeNested(value))\n text := string(bytes)\n return &text\n default:\n text := fmt.Sprint(typed)\n return &text\n }\n}\n\nfunc GenerateSignature(payload map[string]any, secret string) string {\n keys := make([]string, 0, len(payload))\n normalized := map[string]*string{}\n\n for key, value := range payload {\n if key == \"sign\" {\n continue\n }\n normalized[key] = normalizeValue(value)\n keys = append(keys, key)\n }\n\n sort.Strings(keys)\n\n canonical := \"\"\n for _, key := range keys {\n if value := normalized[key]; value != nil {\n canonical += *value\n }\n }\n\n sum := sha256.Sum256([]byte(canonical + secret))\n return hex.EncodeToString(sum[:])\n}\nimport { createHash } from 'node:crypto'\n\nfunction isPlainObject(value) {\n return Object.prototype.toString.call(value) === '[object Object]'\n}\n\nfunction normalizeNested(value) {\n if (Array.isArray(value)) {\n return value.map((item) => normalizeNested(item))\n }\n\n if (isPlainObject(value)) {\n const result = {}\n Object.keys(value).forEach((key) => {\n const child = value[key]\n result[key] = child !== null && typeof child === 'object'\n ? JSON.stringify(normalizeNested(child))\n : child\n })\n return result\n }\n\n return value\n}\n\nfunction normalizeValue(value) {\n if (value === null || value === undefined || value === '') {\n return value\n }\n if (typeof value === 'object') {\n return JSON.stringify(normalizeNested(value))\n }\n return String(value)\n}\n\nexport function generateSignature(payload, secret) {\n const canonical = Object.keys(payload)\n .filter((key) => key !== 'sign')\n .sort()\n .map((key) => normalizeValue(payload[key]))\n .filter((value) => value !== null && value !== undefined && value !== '')\n .join('')\n\n return createHash('sha256')\n .update(canonical + secret, 'utf8')\n .digest('hex')\n}",{"id":658,"title":659,"titles":660,"content":661,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#webhook-signature-verification","Webhook signature verification",[24],"Profit share, reversal, and Ethoca \u002F RDR enrollment status notifications use the body sign field for verification. Other notifications use the X-Rh-Signature header described below. See each webhook’s API Reference for the fields that participate in its signature.",{"id":663,"title":664,"titles":665,"content":666,"level":667},"\u002Fpayments\u002Fget-started\u002Frequest-signing#profit-share-and-reversal-notifications","Profit share and reversal notifications",[24,659],"Use the SECRET for the current environment to compute the received notification’s signature following the signing rules, then compare it with the body sign. Exclude sign itself. Include relatedTxnId and relatedMerchantTxnId, excluding them when their value is null as specified by the signing rules. Use the raw receivers JSON string exactly as received; do not parse and re-serialize it. See the Profit share result webhook for the complete payload. The \u002Fprofit\u002Fquery response also returns data.sign, but merchants do not need to verify query response signatures.",3,{"id":669,"title":670,"titles":671,"content":672,"level":667},"\u002Fpayments\u002Fget-started\u002Frequest-signing#ethoca-rdr-enrollment-status-notifications","Ethoca \u002F RDR enrollment status notifications",[24,659],"Use the SECRET for the current environment to compute the received notification’s signature following the signing rules, then compare it with the body sign. Exclude sign itself; all other fields follow the general signing rules, including the exclusion of null and empty-string values. The notification sends id as a JSON number, which can exceed JavaScript’s safe integer range. Parse the payload with a parser that preserves large integers without losing precision, and retain the original decimal value for signature verification and acknowledgement. Do not first convert it to a JavaScript number that may lose precision. See the Ethoca enrollment status webhook and RDR enrollment status webhook for the complete payloads and acknowledgement requirements. Ethoca alert notifications continue to use the header verification described below.",{"id":674,"title":675,"titles":676,"content":677,"level":667},"\u002Fpayments\u002Fget-started\u002Frequest-signing#other-notifications","Other notifications",[24,659],"Onerway carries webhook signatures in the X-Rh-Signature notification header: one or more comma-separated v1=\u003Csignature> entries, where v1 identifies the signature scheme version. When multiple keys are active at the same time (for example during key rotation), each active key produces one entry: X-Rh-Signature: v1=4bde57c3350c402ca8c3728697cd5d7dbd78c8f0313761607e7f538be3349c39, v1=6b543c2e887e20a98dd4629242dd60050a4cfdda3372cdc17b4422c8fe98d5fa To verify, compute the signature of the received notification with your currently configured SECRET following the signing rules; verification passes if the result matches any entry in X-Rh-Signature. Field selection and concatenation follow the same rules, with two differences: Also exclude the fields marked as excluded from the signature in the webhook's API Reference \"Signature coverage\" section, even when the notification returns values for them. Notification fields added in the future participate by default.Object and array fields arrive as compact JSON strings; use the raw string values exactly as received — do not re-parse and re-serialize them. The notification body still returns a sign field, but it is computed with the first active key only and may differ from the signature you calculate using your configured SECRET during key rotation. For these notifications, verify against X-Rh-Signature rather than the body sign. For notifications that use the body sign, follow the corresponding section above.",{"id":679,"title":680,"titles":681,"content":682,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#common-mistakes","Common mistakes",[24],"Failing to serialize object (Object) or array (Array) fields into compact JSON strings.Leaving txnOrderMsg.products as an array object instead of a JSON string inside the txnOrderMsg string.Sending fields that are not defined for the endpoint: the gateway computes the signature over the fields defined by the API, so extra fields enter only your calculation and cause a mismatch; field structures that deviate from the documentation fail the same way.Environment mismatch, such as using a sandbox merchantNo \u002F SECRET with the production API, or production credentials with the sandbox API.",{"id":684,"title":685,"titles":686,"content":687,"level":615},"\u002Fpayments\u002Fget-started\u002Frequest-signing#when-you-need-support","When you need support",[24],"When request signing fails, print and provide the following server-side information: The final concatenated string before signature calculation (Canonical String).The generated sign.The request environment: sandbox or production.The API endpoint and full request body. You may mask sensitive information, but do not modify the values of the fields participating in the signature. When webhook verification fails, provide the full notification payload as received, the body sign or X-Rh-Signature specified by the webhook’s API Reference, and the Canonical String and signature you computed. html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .sizmJ, html code.shiki .sizmJ{--shiki-light:#E2931D;--shiki-default:#024C1A;--shiki-dark:#FFCB6B}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html pre.shiki code .szWXl, html code.shiki .szWXl{--shiki-light:#F76D47;--shiki-default:#024C1A;--shiki-dark:#F78C6C}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .ssWmh, html code.shiki .ssWmh{--shiki-light:#6182B8;--shiki-default:#023B95;--shiki-dark:#82AAFF}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}",{"id":29,"title":28,"titles":689,"content":690,"level":609},[],"Receive and verify Onerway payment notifications, acknowledge and deduplicate them correctly, and fall back to query APIs when no notification arrives. Onerway pushes the final results of payments, tokenization, subscriptions, pre-authorizations, and refunds to your server through webhooks. This page describes the notification handling contract shared by every integration method; the Checkout, Web SDK, and Direct API integration guides only add the notification types and additional considerations for that integration method. The delivery, verification, acknowledgement, and deduplication rules on this page apply to the notifications listed below. Profit share and reversal notifications use the body sign for verification; see the Profit share result webhook for their notification URLs and acknowledgement requirements. Ethoca \u002F RDR enrollment status notifications also use the body sign. Configure their notification URLs in the merchant portal and return the received id in the acknowledgement. See the Ethoca enrollment status webhook and RDR enrollment status webhook for the complete requirements.",{"id":692,"title":693,"titles":694,"content":695,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#delivery","Delivery",[28],"Onerway sends notifications via HTTP POST to the notifyUrl submitted when the transaction was created. The payload for each scenario is documented separately: WebhookScenarioPayment result webhookOrdinary payments that succeeded, failed, timed out, or were canceledSaved payment method result webhookResults of saving a payment method (tokenization, txnType=BIND_CARD)Subscription payment webhookSubscription lifecycle events such as initial subscription, renewal, change, and cancellationAuthorization, capture, and void webhookPre-authorization (txnType=AUTH), capture (txnType=CAPTURE), and void (txnType=VOID) resultsRefund result webhookRefund results (txnType=REFUND)Refund request rejection webhookA refund request rejected by Onerway (notifyType=REFUND_AUDIT) Refund notifications are sent to the original transaction’s notifyUrl. Onerway sends REFUND_AUDIT only when it rejects a refund request during review. A successful cancellation of a refund request does not trigger a notification; use the Create or cancel refund response. Confirm payment results through Webhooks or query APIs. Do not treat a redirect to returnUrl or a client-side event as confirmation that a payment succeeded. For a refund request (refundType=0), respCode=20000 means that Onerway accepted the request; it does not mean that the refund succeeded.",{"id":697,"title":698,"titles":699,"content":700,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#verify-the-signature","Verify the signature",[28],"You must verify the notifications in the table above with the X-Rh-Signature header — do not rely on the sign field in the notification body. sign is computed with only the first enabled key and may differ from the signature you calculate using your configured SECRET during key rotation. See Request signing for the verification rules and the fields excluded from verification.",{"id":702,"title":703,"titles":704,"content":705,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#acknowledge-and-retries","Acknowledge and retries",[28],"After processing, return HTTP 200 with Content-Type: text\u002Fplain and the notification's transactionId unchanged in the response body. Without a successful response, Onerway retries at 30-minute intervals, up to 3 times.",{"id":707,"title":708,"titles":709,"content":710,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#deduplicate","Deduplicate",[28],"A single transaction may receive multiple notifications. Handle them idempotently by transactionId: process a repeated notification with the same transactionId only once, but still acknowledge it. Tokenization, subscription-with-binding, and pre-authorization flows with a later capture or void produce several related notifications with different transactionId values. Handle each idempotently on its own and associate them with the same payment intent or subscription contract through business identifiers such as paymentId and contractId.",{"id":712,"title":713,"titles":714,"content":715,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#interpret-the-status","Interpret the status",[28],"status is the result of the current operation, such as S for success and F for failure.paymentStatus is the payment intent state, such as A after a successful pre-authorization, S after a successful capture, and N (closed) after a successful void. For pre-authorization, capture, and void results, use paymentId plus paymentStatus to determine whether the funds are held, captured, or released. Process a refund result using its refund transactionId and status. See the API Reference page of each webhook for the corresponding fields and values.",{"id":717,"title":718,"titles":719,"content":720,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#handle-differences-between-query-results-and-webhooks","Handle differences between query results and Webhooks",[28],"These rules apply to payments, refunds, and other scenarios. When a query result differs from a Webhook already received, compare results for the same transaction and operation: Use the Webhook result if the query returns a status other than success (S) or failure (F), but the Webhook reports success or failure.Otherwise, use the query result, including when the query returns success (S) or failure (F).",{"id":722,"title":723,"titles":724,"content":725,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#query-results-when-needed","Query results when needed",[28],"Once you receive a Webhook reporting success (S) or failure (F), process the corresponding payment or refund result. No confirming query is needed. For payments, if the customer has returned to your page but no Webhook has arrived, or you need to reconcile records, you can query at increasing intervals until the query returns success (S) or failure (F), or a Webhook arrives. For refunds, wait for a Webhook; continuous polling is not required. When you need to check progress or reconcile records, use Query refunds with the refund transaction ID or the original payment transaction ID. For payment results, the query API depends on the integration method: the Checkout and Direct API integrations use Query transactions; the Web SDK integration calls Query payments with the paymentId saved when the payment was created.",{"id":727,"title":728,"titles":729,"content":730,"level":615},"\u002Fpayments\u002Fget-started\u002Fwebhooks#go-live-checklist","Go-live checklist",[28],"The notifications in the table above are verified with X-Rh-Signature, and notifications that fail verification are not processed.For the notifications in the table above, your endpoint returns HTTP 200 with the transactionId after processing and deduplicates by transactionId.Your webhook endpoint accepts every notification type involved in the scenarios you use.Success, failure, and retry scenarios are verified in the sandbox with the test cards.",{"id":33,"title":32,"titles":732,"content":733,"level":609},[],"Validate transaction currency, amount precision, and payment method availability before creating a payment request. Before you create a payment request, validate orderCurrency, orderAmount, and available payment methods on your server. orderCurrency is a three-letter ISO 4217 transaction currency. orderAmount is a positive decimal string in the transaction currency's display unit: send USD 99.99 as 99.99, and send JPY 1000 as 1000 or 1000.00. Do not generate orderAmount directly from JavaScript number, binary floating point values, or ad hoc rounded values. Calculate internally with integer values in the minor unit or a decimal library, confirm the amount, then format it as the string expected by the Onerway API.",{"id":735,"title":736,"titles":737,"content":738,"level":615},"\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#validation-order","Validation order",[32],"Validate the currency codeorderCurrency must be an uppercase three-letter ISO 4217 alphabetic code, such as USD, EUR, or JPY. Do not pass currency symbols, country codes, unofficial abbreviations, or mixed-case values.Do not use fund, precious metal, testing, or no-currency codes such as XAU, XTS, or XXX in payment requests unless Onerway has explicitly enabled them for your merchant, payment method, and transaction scenario.Validate amount format and precisionorderAmount must be a positive decimal string that uses . as the decimal separator. Do not include commas, spaces, currency symbols, plus or minus signs, or exponential notation.Minor unitValidation ruleCommon examples0Must represent a whole amount; the decimal part may be omitted or contain zeros onlyJPY accepts 1000 or 1000.00; do not send 4.122Up to two decimals; integer amounts do not need .00USD accepts 100, 100.00, or 99.993Up to three decimals; payment methods may still enforce additional limitsKWD accepts 10, 10.500, or 0.001Currency precision should come from your enabled-currency configuration or ISO 4217 minor unit data. Do not hard-code all currencies as two-decimal currencies; zero-decimal currency and three-decimal currency values need separate handling.Validate payment method availabilityValid amount format does not guarantee that the transaction can be processed. Availability can also depend on the payment method, country or region, issuer, local payment provider, merchant configuration, and per-transaction limits.Before you display a currency or let the customer enter an amount, call List available payment methods to filter methods by country or region, currency, amount, and merchant configuration. For each local payment method, never rely on currency alone.Validate the order totalIf the request includes txnOrderMsg.products, discounts, shipping fees, or other order lines, calculate every line with the same currency and precision and make sure the line total matches orderAmount. Discount lines should use negative amounts when required by the endpoint field contract.",{"id":740,"title":741,"titles":742,"content":743,"level":615},"\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#request-examples","Request examples",[32],"{\n \"orderAmount\": \"99.99\",\n \"orderCurrency\": \"USD\"\n} {\n \"orderAmount\": \"1000.00\",\n \"orderCurrency\": \"JPY\"\n} {\n \"orderAmount\": \"10.500\",\n \"orderCurrency\": \"KWD\"\n}",{"id":745,"title":746,"titles":747,"content":748,"level":615},"\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#server-side-validation-example","Server-side validation example",[32],"The example below only demonstrates amount format validation. In production, read enabled currencies, the minor unit, minimum amount, maximum amount, and available payment methods from your merchant configuration. type CurrencyRule = {\n minorUnit: number\n minAmount?: string\n maxAmount?: string\n}\n\nconst enabledCurrencies: Record\u003Cstring, CurrencyRule> = {\n USD: { minorUnit: 2, minAmount: '0.01' },\n JPY: { minorUnit: 0, minAmount: '1' },\n KWD: { minorUnit: 3, minAmount: '0.001' }\n}\n\nfunction validateOrderAmount(amount: string, currency: string) {\n const code = currency.trim().toUpperCase()\n const rule = enabledCurrencies[code]\n\n if (!rule) {\n return { valid: false, reason: 'invalid_currency_code' }\n }\n\n if (!\u002F^\\d+(?:\\.\\d+)?$\u002F.test(amount)) {\n return { valid: false, reason: 'invalid_amount_format' }\n }\n\n const [, fraction = ''] = amount.split('.')\n const hasTooManyDecimals = fraction.length > rule.minorUnit\n const isWholeAmountWithZeroFraction = rule.minorUnit === 0 && \u002F^0*$\u002F.test(fraction)\n if (hasTooManyDecimals && !isWholeAmountWithZeroFraction) {\n return { valid: false, reason: 'invalid_minor_unit' }\n }\n\n if (\u002F^0+(?:\\.0+)?$\u002F.test(amount)) {\n return { valid: false, reason: 'amount_must_be_positive' }\n }\n\n return { valid: true, code, minorUnit: rule.minorUnit }\n} Your frontend can limit decimal places and display formatting dynamically by currency. Treat the server-side result as authoritative, and do not silently truncate or round a customer-confirmed amount immediately before the API request.",{"id":750,"title":751,"titles":752,"content":753,"level":615},"\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#common-rejection-reasons","Common rejection reasons",[32],"ScenarioCauseHow to fix itJPY is sent as 4.12Zero-decimal currencies cannot contain non-zero decimalsSend a whole amount or an all-zero decimal form, such as 1000 or 1000.00; otherwise the API may return respCode=40000 with Illegal parameter orderAmountUSD is sent as 99.999More than two decimal placesResolve precision before the customer confirms the amountKWD is forced to two decimalsA generic amount component ignored three-decimal currency rulesSet precision dynamically in both the input component and server validation1,000.00 is submittedAPI amounts do not accept thousands separatorsStrip display formatting before submission and send only the decimal stringPayment method is unavailableCurrency format is valid, but method, region, or limits do not matchQuery available payment methods first or confirm merchant configuration with Onerway",{"id":755,"title":756,"titles":757,"content":758,"level":615},"\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#references","References",[32],"ISO 4217 currency codes — check alphabetic codes, numeric codes, and the minor unitSIX Financial Data Standards — download ISO 4217 List OneList available payment methods — filter available payment methods by transaction conditions html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s1VmB, html code.shiki .s1VmB{--shiki-light:#E53935;--shiki-default:#702C00;--shiki-dark:#F07178}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sO9CA, html code.shiki .sO9CA{--shiki-light:#FF5370;--shiki-default:#023B95;--shiki-dark:#FF9CAC}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .stp_H, html code.shiki .stp_H{--shiki-light:#90A4AE;--shiki-light-font-weight:inherit;--shiki-default:#024C1A;--shiki-default-font-weight:bold;--shiki-dark:#BABED8;--shiki-dark-font-weight:inherit}",{"id":37,"title":36,"titles":760,"content":761,"level":609},[],"Use sandbox test cards to validate card payment flows, 3DS scenarios, failure responses, subscriptions, token payments, and wallet payments. Use the following test cards in the sandbox to validate your payment flows. Test cards are for sandbox use only. Do not use them in production, and do not replace them with real cardholder data. Response shows the typical response used to validate success or failure branches. Actual API responses still depend on the current sandbox configuration.",{"id":763,"title":764,"titles":765,"content":766,"level":615},"\u002Fpayments\u002Fget-started\u002Ftesting#card-payment-test-cards","Card payment test cards",[36],"Use these card numbers to validate one-time payments, 3DS authentication flows, exemption scenarios, failure responses, subscription payments, and token payments. The 3DS test scenario describes the authentication flow or exemption path simulated by the sandbox test card. Challenge flow and Frictionless flow are 3DS authentication flows. Exemption describes an exemption scenario. These labels are not fixed properties of the card itself, and they do not mean every transaction from the same country or region will trigger the same result. Card numberCountryCard brand3DS test scenarioResponseSubscriptionSave payment method4000020951595032🇺🇸 USChallenge flowSuccess4761344136141390🇸🇬 SGExemptionSuccess4000319872807223🇺🇸 USFrictionless flowSuccess4000128449498204🇺🇸 USFrictionless flowDo not honor4021937195658141🇬🇧 GBFrictionless flowInsufficient funds4000164166749263🇮🇳 INFrictionless flowSuspected fraud2221008123677736🇺🇸 USChallenge flowSuccess5333302221254276🇹🇷 TRExemptionSuccess5333418445863914🇲🇽 MXFrictionless flowSuccess5109486948867999🇺🇸 USFrictionless flowRestricted Card4998170000000015🇧🇷 BRChallenge flowSuccess4998170000000023🇧🇷 BRChallenge flowSuspected fraud",{"id":768,"title":769,"titles":770,"content":771,"level":615},"\u002Fpayments\u002Fget-started\u002Ftesting#apple-pay-sandbox-testing","Apple Pay sandbox testing",[36],"Before testing Apple Pay in the sandbox, complete the following preparation: Domain verification: If you show the Apple Pay button on your own pages through the Web SDK or the Direct API, the test domain must first pass Apple domain verification, either through your own Apple Developer account or registered by Onerway; see Apple Pay setup. The Onerway-hosted checkout page does not need this step.Sandbox tester account: Create a sandbox tester account in App Store Connect. Sign out of iCloud on the test device, then sign in with the tester account.Device country and region: Set the test device's country and region to one that the Apple Pay sandbox supports and that matches the card network of the test card; Wallet in the China mainland region supports UnionPay test cards only. Test cards are provided by Apple and replaced in batches, so use the latest cards on the Apple Pay sandbox testing page and add them manually in the Wallet app on the test device.",{"id":773,"title":774,"titles":775,"content":776,"level":615},"\u002Fpayments\u002Fget-started\u002Ftesting#google-pay-test-cards","Google Pay test cards",[36],"Before testing Google Pay, join the Google Pay test card suite group with your Google account. Once joined, Google Pay on that account automatically presents a set of test cards, so there is no need to add cards manually.",{"id":778,"title":779,"titles":780,"content":781,"level":615},"\u002Fpayments\u002Fget-started\u002Ftesting#suggested-test-scenarios","Suggested test scenarios",[36],"Use test cards with an expected Success response to validate payment creation and payment confirmation.Verify that your server receives payment webhooks: verify each notification with the X-Rh-Signature header per request signing, then return the acknowledgement response so the notification is not redelivered.Use test cards with an expected failure response to validate error display, retry handling, and order status rollback.Use cards that support subscriptions to validate subscription payments.Use cards that support saving payment methods to validate save payment method flows and later token payments.Use the Apple Pay and Google Pay test cards to validate wallet payment flows.",{"id":46,"title":50,"titles":783,"content":784,"level":609},[],"Create a checkout payment on your server, redirect the customer to the Onerway-hosted page to pay, and confirm the result through webhooks. Create every Checkout payment on your server: call the create checkout payment API to obtain a redirectUrl, then redirect the customer's browser to the Onerway-hosted checkout page to complete the payment. Onerway handles the payment page, 3DS authentication, and PCI compliance. Browser, device, and cardholder IP data are collected by the hosted checkout page — do not collect or submit them from your server. Before you begin, follow Setup to obtain your API credentials and add your server's public outbound IP addresses to the allowlist for the target environment. Generate sign for each request according to Request signing. Before going live, follow Sandbox testing to verify all scenarios used by your integration in the sandbox. Checkout uses Onerway's Google Pay integration, so no Google Pay website registration is needed; that applies only to Direct API integrations.",{"id":786,"title":337,"titles":787,"content":788,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#integration-flow",[50],"Create a payment on your serverCreate the transaction through Create checkout payment. The txnOrderMsg field must include returnUrl (synchronous return address) and notifyUrl (webhook notification address). In the products field, product amounts, discounts, and shipping fees must add up to orderAmount.After creation the transaction status is U (unpaid), and the response returns the redirectUrl field.Redirect to the checkout pageRedirect the customer's browser to redirectUrl. The customer selects a payment method and completes the payment on the hosted page; when 3DS authentication is required, the checkout page guides the customer through it — no merchant handling is needed.Handle the payment returnAfter payment the customer returns to your site through returnUrl. The synchronous return is for page flow only: add your order ID to returnUrl, show the customer a \"processing\" state when they return, and process the order once the webhook arrives. The final payment result is determined by webhooks.",{"id":790,"title":791,"titles":792,"content":793,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#payment-method-display-scope","Payment method display scope",[50],"Which payment methods the checkout page displays is controlled by the productType field; the actual processing model is further determined by subProductType and txnType. GoalServer-side inputDisplay card payment methods onlyproductType=CARDDisplay all available payment methodsproductType=ALL; the customer chooses on the checkout page.Lock to a single local payment method or walletproductType=ALL together with the lpmsInfo.lpmsType field; the checkout page displays only that payment method, with ApplePay and GooglePay for the wallets. How each payment method is supported on the checkout page and what to prepare is covered in Payment methods.",{"id":795,"title":796,"titles":797,"content":798,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#saved-card-option","Saved card option",[50],"When you submit a stable merchantCustId field, the checkout page offers the customer the option to save their card information. The option is not selected by default; the card is saved only after the customer opts in and completes the payment. Submit the subProductType field according to the scenario — DIRECT, SUBSCRIBE, or INSTALLMENT; no dedicated value is needed for saving cards. Keep submitting the same merchantCustId on later payments, and the checkout page presents the customer's available saved cards. Additional considerations for the Checkout integration: for subscription checkout, submit the customer identifier in the top-level merchantCustId; the subscription.merchantCustId field is optional, and when it is also submitted the two values must match. The requirements for merchantCustId, the saved payment method result webhook, and listing and deleting saved tokens are covered in Saved payment methods.",{"id":800,"title":801,"titles":802,"content":803,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#subscriptions","Subscriptions",[50],"Initial subscriptions are completed on the checkout page: submit the subProductType field =SUBSCRIBE together with the subscription field (requestType=0); the billing model is determined by the subscription.selfExecute field. Renewals and plan changes are initiated by your server through the Direct API; the checkout page is not involved. Choosing between managed and self-managed subscriptions, contract credentials, lifecycle notifications, and plan change rules are covered in Subscription payments.",{"id":805,"title":806,"titles":807,"content":808,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#pre-authorization","Pre-authorization",[50],"When the txnType field is AUTH, the checkout page performs a pre-authorization: the order amount is held on the customer's card without an immediate charge, and any 3DS authentication is guided by the checkout page. After the pre-authorization succeeds, store the transactionId and paymentId from the response; your server later captures or voids through Capture or void authorization. Scope, the lifecycle from authorization to capture or void, notifications, boundaries, and status handling are covered in Pre-authorization and capture.",{"id":810,"title":104,"titles":811,"content":812,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#profit-sharing",[50],"Profit sharing applies to the platform model: the platform merchant creates the payment with the receiving sub-merchant's merchantNo, and the payment is eligible for profit sharing only when you submit the paymentMethodOptions field with profitShare=true in its share object; the checkout payment flow is the same as an ordinary payment. When you also set profitShareRate, Onerway allocates funds automatically after a successful SALE or CAPTURE; without it, your server initiates profit sharing through the API. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Submit paymentMethodOptions as a JSON string as required by the API. Choosing between automatic and API-initiated profit sharing, result notifications, queries, and reversals are covered in Profit sharing.",{"id":814,"title":815,"titles":816,"content":817,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fcheckout#confirm-the-payment-result","Confirm the payment result",[50],"The final result of a Checkout payment is determined by webhooks: the payment result webhook for ordinary payments, the subscription payment webhook for subscriptions, and the authorization, capture, and void webhook for pre-authorizations. When the customer opts in to saving a card, the tokenization result arrives separately in the saved payment method result webhook. Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in Webhooks. Additional considerations for the Checkout integration: the returnUrl return is not guaranteed to carry transaction parameters, so do not use any parameter on the return URL to drive order processing; if the customer has returned but no webhook has arrived, fall back to Query transactions. Transaction status is determined by the status response field and the same field in webhooks; see the API Reference for all values.",{"id":53,"title":57,"titles":819,"content":820,"level":609},[],"Create a server-side payment, initialize the Web SDK with paymentId, and handle custom buttons, wallets, redirects, and final result verification. A Web SDK integration has two parts: your server creates the payment and stores the order-to-paymentId mapping; the browser loads the SDK and creates Checkout with that paymentId. Keep the secret, request signing, customer mapping, and final payment verification on the server. Before you begin, follow Setup to obtain your API credentials and add your server's public outbound IP addresses to the allowlist for the target environment. Generate sign for each request according to Request signing. Before going live, follow Sandbox testing to verify all scenarios used by your integration in the sandbox. The Web SDK uses Onerway's Google Pay integration, so no Google Pay website registration is needed; that applies only to Direct API integrations.",{"id":822,"title":337,"titles":823,"content":824,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#integration-flow",[57],"Call Create SDK transaction from your server and store the returned paymentId.Load the CDN script that matches the transaction environment.Create Checkout with paymentId, subscribe to events, and then mount the Payment Element.Call confirmPayment() for cards, each local payment method, and other custom payment buttons. For SDK-owned Apple Pay and Google Pay buttons, listen only for payment_result.Use client events to update the page. Confirm the final status on your server through Query payments or a payment webhook.",{"id":826,"title":827,"titles":828,"content":829,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#create-a-payment-on-your-server","Create a payment on your server",[57],"For an ordinary Web SDK v4 payment, submit productType=ALL, subProductType=DIRECT, and txnType=SALE to Create SDK transaction. The standard one-time payment example omits billingInformation, shippingInformation, paymentMode, and osType. Both billingInformation and shippingInformation are optional when you create the transaction. You can provide either object when the information is available, or add it through Update SDK order before payment confirmation when your business flow requires it. If you submit an object, its nested required fields and conditions still apply. When updating the order, reuse the merchantTxnId of the original transaction creation on your server, and wait for a successful update response before the customer confirms payment. For the current Web SDK, txnOrderMsg contains only returnUrl, products, appId, customerPlatform, periodValue, and notifyUrl. See the API Reference for whether each field is required and its conditions. Do not collect or send browser, device, or cardholder IP fields from your server; the Web SDK collects that context. Omit paymentMode for ordinary Web SDK payments; you do not need to distinguish desktop and mobile browsers. If you send a value other than WEB, you must also send osType. Pass only the paymentId from the create-payment response to the browser. You may use transactionId for server-side order correlation, but it cannot replace paymentId when initializing the SDK. The response also still returns redirectUrl; the current Web SDK does not consume it during initialization.",{"id":831,"title":832,"titles":833,"content":834,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#load-the-sdk","Load the SDK",[57],"The CDN and environment must match: EnvironmentCDNenvironmentSandboxhttps:\u002F\u002Fsandbox-checkout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.jssandboxProductionhttps:\u002F\u002Fcheckout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.jsproduction, the default v4\u002Flatest is the officially recommended long-term Production URL. Although environment defaults to production, pass it explicitly to prevent environment mix-ups when copying configuration. \u003Cscript src=\"https:\u002F\u002Fcheckout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.js\">\u003C\u002Fscript>\n\n\u003Cdiv id=\"onerway_checkout\">\u003C\u002Fdiv>\n\u003Cbutton id=\"pay_button\" type=\"button\">Pay now\u003C\u002Fbutton>",{"id":836,"title":837,"titles":838,"content":839,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#initialize-subscribe-and-mount","Initialize, subscribe, and mount",[57],"const checkout = await Onerway.createCheckout(paymentId, {\n environment: 'production',\n locale: 'en'\n})\n\nconst paymentElement = checkout.createPaymentElement()\n\npaymentElement.on('ready', (event) => {\n console.log(event.availablePaymentMethods)\n})\n\npaymentElement.on('loaderror', (event) => {\n console.error(event.error.code, event.error.message)\n})\n\ncheckout.on('payment_result', handlePaymentResult)\n\npaymentElement.mount('#onerway_checkout') Subscribe before calling mount(): ready.availablePaymentMethods is the displayable set determined by the order, server configuration, and browser wallet capabilities. Do not treat example values as a fixed enum. The SDK hides wallet buttons when a wallet is unavailable.loaderror means that Checkout initialization failed. Branch on event.error.code; use event.error.message for display only. The only public codes are checkout_load_failed (the first load of payment methods failed; let the customer reinitialize) and no_available_payment_methods (no payment method remains after filtering; check the server-side configuration and paymentMethod).Validation failures, payment API errors, wallet cancellation, and 3DS or redirect errors are not loaderror events. Handle them through the confirmPayment() result or payment_result.",{"id":841,"title":842,"titles":843,"content":844,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#configure-the-payment-element","Configure the Payment Element",[57],"Every child field of config is optional, but each merchant should decide which fields to provide based on its payment-method, form, and branding requirements. Do not assume that the default presentation fits every integration. The SDK reads the configuration when paymentElement.mount() runs. Recreate and remount the Payment Element after changing it. FieldTypeDefaultPurposepaymentMethodString[]OmittedDisplay allowlist that retains only methods also returned by the servershowBillingAddressBooleantrueWhether to display and validate the billing-address formdisplayCardholdernameBooleantrueWhether to display and validate the cardholder-name inputwalletButtonsObjectSee belowSupported appearance settings for the official Apple Pay and Google Pay buttonscheckoutThemeStringlightSDK theme preset; light is currently the only public themevariablesObject{}Theme-variable overrides and the recommended customization layerstylesObject{}CSS-selector overrides with the highest prioritycustomCssURLStringSDK default CSSReplaces the SDK base stylesheet; variables and styles still apply For example, a merchant can display only the methods accepted by its checkout, hide the SDK billing-address form, and apply branding to SDK-controlled content: const checkout = await Onerway.createCheckout(paymentId, {\n environment: 'production',\n locale: 'en',\n config: {\n paymentMethod: ['CARD', 'DOKU_VA', 'GooglePay'],\n showBillingAddress: false,\n displayCardholdername: true,\n checkoutTheme: 'light',\n variables: {\n colorPrimary: '#2563eb',\n colorText: '#1a202c',\n borderRadius: '8px'\n },\n walletButtons: {\n googlePay: { type: 'pay', color: 'black', height: '44px' },\n applePay: { type: 'pay', color: 'black', height: '44px' }\n }\n }\n})",{"id":846,"title":847,"titles":848,"content":849,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#restrict-payment-methods","Restrict payment methods",[57,842],"paymentMethod only filters the browser presentation. It does not enable a payment method for the merchant: ValueBehaviorOmittedDisplay every server-returned method that is available on the current device['CARD', 'FPX', 'GooglePay']Display CARD, FPX, and GooglePay only when the server also returns them[]Display no methods and emit loaderror with event.error.code set to no_available_payment_methods Each value must exactly match the payment-method identifier returned by the server. Array order does not control display order; the server payment-method configuration and the SDK wallet region still determine the actual order. Use ready.availablePaymentMethods as the final indication that a method loaded successfully.",{"id":851,"title":852,"titles":853,"content":854,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#configure-form-visibility","Configure form visibility",[57,842],"showBillingAddress: false hides the billing address and stops its client-side validation. It does not change server-side field requirements for Create transaction or Update order. If your business requires billing information, collect it and update the order before payment confirmation.displayCardholdername: false hides the cardholder name and stops its client-side validation.",{"id":856,"title":857,"titles":858,"content":859,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#configure-wallet-buttons","Configure wallet buttons",[57,842],"FieldDefaultSupported values or rulegooglePay.typepaybook, buy, checkout, donate, order, pay, plain, subscribegooglePay.colorblackblack, whiteapplePay.typepayadd-money, book, buy, check-out, continue, contribute, donate, order, plain, reload, rent, subscribe, support, tip, top-up, payapplePay.colorblackblack, white, white-outlinegooglePay.width \u002F applePay.width100%CSS size stringgooglePay.height \u002F applePay.height44pxCSS size stringgooglePay.radius \u002F applePay.radius8pxCSS size string; the Apple \u002F Google platforms may constrain the final appearance These options customize only the supported appearance of official SDK wallet buttons. They cannot make a wallet available on an unsupported device, and variables, styles, or custom CSS cannot force an appearance that the wallet platform does not allow. Setup for wallets, such as Apple Pay domain verification, is covered in Payment methods.",{"id":861,"title":862,"titles":863,"content":864,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#configure-themes-and-styles","Configure themes and styles",[57,842],"checkoutTheme currently supports only light.variables is the recommended branding layer. Common supported variables are containerBackground, cardBackground, inputBackground, inputBrandBackground, aggregateHeaderBackground, dialogBackground, colorText, colorPrimary, colorDanger, fontFamily, fontSizeBase, and borderRadius. fontSizeBase accepts 12px–24px; borderRadius accepts 0px–24px.styles maps CSS selectors to CSS property objects, such as { '.onerway-checkout__input': { color: '#1a202c' } }, for local adjustments that variables cannot express.customCssURL replaces the SDK base stylesheet; variables and styles can still override it. Themes and styles affect SDK-controlled content only. The legacy showPayButton and payButtonText options are no longer supported and are ignored by the SDK.",{"id":866,"title":867,"titles":868,"content":869,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#locale","Locale",[57],"When locale is omitted, the SDK uses the browser language. If the explicit value or browser language is not supported by the current payment method, the SDK falls back to English (en). Non-wallet payment methods support the following locale values (alphabetical): CodeLanguageCodeLanguagearArabicdeGermanenEnglishesSpanishfiFinnishfrFrenchitItalianjaJapanesekoKoreannlDutchnoNorwegianplPolishptPortugueseruRussiansvSwedishthThaizh-cnSimplified Chinesezh-twTraditional Chinese Wallets use their own locale enums and casing. The two wallets support the same locales except for these differences: SupportLocalesBoth walletsar, ca, cs, da, de, el, en, es, fi, fr, hr, id, it, ja, ko, ms, nl, no, pl, pt, ru, sk, sv, th, tr, uk, zhGoogle Pay onlybg, et, sl, srApple Pay onlyhe, hi, hu, ro, vi, zh-TW Wallets also fall back to English (en) when a locale is unsupported. For example, Simplified Chinese is zh-cn for non-wallet methods and zh for wallets; Traditional Chinese is zh-tw for non-wallet methods and zh-TW for wallets. Do not invent conversions for values that are not listed.",{"id":871,"title":872,"titles":873,"content":874,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#confirm-the-payment","Confirm the payment",[57],"",{"id":876,"title":877,"titles":878,"content":879,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#cards-local-payment-method-flows-and-custom-buttons","Cards, local payment method flows, and custom buttons",[57,872],"These payment methods require your button to call confirmPayment(): document.querySelector('#pay_button').addEventListener('click', async () => {\n const result = await checkout.confirmPayment()\n handleConfirmResult(result)\n}) Do not create another Checkout or another order when retrying. Keep the same paymentId, Checkout, and Payment Element while the payment remains retryable.",{"id":881,"title":882,"titles":883,"content":884,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#sdk-owned-apple-pay-and-google-pay-buttons","SDK-owned Apple Pay and Google Pay buttons",[57,872],"SDK-owned wallet buttons cannot call confirmPayment(). After the customer clicks an official button rendered by the SDK, receive the client result only through payment_result: checkout.on('payment_result', (result) => {\n if (result.reason?.type === 'canceled') {\n \u002F\u002F The customer closed the wallet. Restore the UI; do not map this to a payment failure.\n return\n }\n\n renderClientResult(result)\n}) Wallet visibility also depends on server configuration, browser, device, and wallet capabilities.",{"id":886,"title":887,"titles":888,"content":889,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#google-pay-in-embedded-app-webviews","Google Pay in embedded app WebViews",[57,872],"Google Pay availability is capability-detected: when the requirements are not met, ready.availablePaymentMethods does not include GooglePay and the SDK does not render its button. This is expected behavior, not a failure. Android WebView officially supports Google Pay, but the host app must cooperate: Android WebView 137+, Google Play services 25.18.30+, the androidx.webkit:webkit:1.14.0 dependency, the Chromium payment intent actions declared in the manifest, the Payment Request API enabled, and the app integration published to Google. A custom User-Agent must append GOOGLE_PAY_SUPPORTED. See the official Google WebView guide.Embedded WebViews on iOS do not support Google Pay.When the host app does not meet these requirements, break the payment flow out to the system browser and make sure the customer is guided back to the app after payment.",{"id":891,"title":892,"titles":893,"content":894,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#paymentstatus-and-nextaction","paymentStatus and nextAction",[57],"The SDK returns nextAction only when paymentStatus === 'R': nextAction.typeSDK behaviorMerchant actionPresentToShopperThe SDK presents a QR code, local payment page, or another handoff UI on the current page. There is no final result yet.Keep the current Checkout and wait for payment_result. Do not call confirmPayment() again.RedirectShopperThe SDK is about to redirect to an external payment page. There is no final result yet. 3DS uses this flow.Wait for Onerway to return the customer to the request's returnUrl, then call Query payments on the server using the stored paymentId. R means that the payment flow must continue; it does not mean success or failure. nextAction is absent when paymentStatus !== 'R'. See the paymentStatus response field for the full set of values and their definitions. Use client statuses only to update the page; do not fulfill, credit, or account for an order from them alone: paymentStatusMerchant actionI, U, P, ANot a final state. Keep the order pending; do not fulfill.RThe flow continues in an SDK handoff or redirect. Read nextAction.type and follow the table above.OThe payment can continue or be retried. Keep the same paymentId, Checkout, and Payment Element; do not create another order.S, NA client-received result. Verify on the server before completing the order or updating its display. Client exceptions that do not produce a payment status are described by reason: reason.typeMeaningvalidation_errorLocal form validation failed; no payment status was producedsdk_errorAn SDK local state, configuration, or invocation problemapi_errorThe payment API or a backend business call failed; reason.code is the backend's original respCode — see Response codescanceledThe customer canceled the current interaction; reason.code is presenter_closed (closed the SDK-presented QR code or local payment dialog), cvv_closed (closed the second card verification code dialog after Google Pay authorization), or wallet_canceled (canceled the Apple Pay or Google Pay authorization sheet) A cancellation may carry no paymentStatus, only reason.type === 'canceled'. Canceling the client flow is not a final payment failure; restore the page so the customer can retry.",{"id":896,"title":897,"titles":898,"content":899,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#verify-the-final-payment-result","Verify the final payment result",[57],"The confirmPayment() result, payment_result, and returnUrl can drive client navigation only; the final result is determined by webhooks: the payment result webhook for ordinary payments, the saved payment method result webhook when the customer opts in to saving a card, the subscription payment webhook for subscriptions, and the authorization, capture, and void webhook for pre-authorizations. Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in Webhooks. Additional considerations for the Web SDK integration: store the merchant-order-to-paymentId mapping on your server. After a redirect returns to returnUrl, do not trust a payment status in the URL — restore the page to a “confirming” state and, if no webhook has arrived, fall back to Query payments with the paymentId from your server and return the business result to the client. Do not store unredacted rawResult, request or response payloads, or payment data in browser logs, persistent storage, or analytics.",{"id":901,"title":902,"titles":903,"content":874,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#saved-cards-and-subscriptions","Saved cards and subscriptions",[57],{"id":905,"title":906,"titles":907,"content":908,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#let-the-customer-choose-whether-to-save-a-card","Let the customer choose whether to save a card",[57,902],"Keep subProductType at DIRECT and provide a stable merchantCustId. The SDK presents the save-card choice to the customer; it is not selected by default. Reuse the same merchantCustId for later payments, and the SDK displays the customer's saved cards and completes saved-card selection and payment internally; your client does not need a tokenId for that flow. Additional considerations for the Web SDK integration: subProductType=TOKEN belongs to the legacy Web SDK save-card flow and is not used for the current Web SDK's customer-controlled save-card flow. The requirements for merchantCustId, the saved payment method result webhook, and listing and deleting saved tokens are covered in Saved payment methods.",{"id":910,"title":911,"titles":912,"content":913,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fsdk#create-the-initial-payment-for-a-fixed-plan","Create the initial payment for a fixed plan",[57,902],"Use subProductType=SUBSCRIBE for the initial subscription payment. Keep the allowed plan mapping on your server and send a stable, readable subscription.productName; the billing model is determined by subscription.selfExecute. For a managed card subscription, you can also send subscription.bindCard as true to save the customer card when the subscription succeeds, in which case you receive two separate notifications. Choosing between managed and self-managed subscriptions, contract credentials, lifecycle notifications, renewals and plan changes, and handling the two notifications of a subscription that also saves the card are covered in Subscription payments.",{"id":915,"title":806,"titles":916,"content":917,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#pre-authorization",[57],"Send txnType as AUTH and keep subProductType at DIRECT to perform a pre-authorization: the order amount is held on the customer's card without an immediate charge, and the SDK integration flow is the same as an ordinary payment. After the pre-authorization succeeds, store the transactionId and paymentId from the response; your server later captures or voids through Capture or void authorization. Scope, the lifecycle from authorization to capture or void, notifications, boundaries, and status handling are covered in Pre-authorization and capture.",{"id":919,"title":104,"titles":920,"content":921,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fsdk#profit-sharing",[57],"Profit sharing applies to the platform model: the platform merchant creates the payment with the receiving sub-merchant's merchantNo, and the payment is eligible for profit sharing only when you submit the paymentMethodOptions with profitShare=true in its share object; the SDK integration flow is the same as an ordinary payment. When you also set profitShareRate, Onerway allocates funds automatically after a successful SALE or CAPTURE; without it, your server initiates profit sharing through the API. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Submit paymentMethodOptions as a JSON string as required by the API. Choosing between automatic and API-initiated profit sharing, result notifications, queries, and reversals are covered in Profit sharing. html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sO9CA, html code.shiki .sO9CA{--shiki-light:#FF5370;--shiki-default:#023B95;--shiki-dark:#FF9CAC}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}",{"id":60,"title":64,"titles":923,"content":924,"level":609},[],"Submit card data or tokens directly from your server through the create direct transaction API, handle 3DS redirects yourself, and rely on webhooks for the final results of payments, tokenization, subscriptions, and pre-authorizations. With the Direct API integration you build your own payment page and call Create direct transaction from your server: card data or tokens are submitted by your backend, 3DS redirects are handled by you, and the final result is confirmed through webhooks. Unlike Checkout and the Web SDK, card data passes through your systems, so this integration requires PCI DSS compliance. In return you get a fully custom payment experience and direct server-side control over tokenization, token payments, subscription billing, and pre-authorization. Setup and method-specific flows for Apple Pay, Google Pay, and each local payment method on the Direct API are covered in Payment methods.",{"id":926,"title":927,"titles":928,"content":929,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#before-you-begin","Before you begin",[64],"Before you begin, follow Setup to obtain your API credentials and add your server's public outbound IP addresses to the allowlist for the target environment. Generate sign for each request according to Request signing. Before going live, follow Sandbox testing to verify all scenarios used by your integration in the sandbox. The Direct API integration additionally requires PCI DSS compliance: to collect card numbers, expiry dates, and CVC on your own page and submit them to Onerway, you must hold a valid PCI DSS certification, transmit cardholder data over TLS, and never store sensitive authentication data such as CVC. If you are not certified, use Checkout integration or Web SDK integration instead — card data never reaches your server. Subscription renewals and pre-authorization captures do not submit card data and are not subject to this requirement; a card token payment still submits cardInfo.cvv and therefore remains within scope.",{"id":931,"title":337,"titles":932,"content":933,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#integration-flow",[64],"Create a transaction on your serverCall Create direct transaction. The transaction model is defined by the productType field, the subProductType field, and the txnType field together. For a direct card payment with card details collected by you, submit productType=CARD, subProductType=DIRECT, and txnType=SALE, with the card data in the cardInfo field.The txnOrderMsg field must include returnUrl (the synchronous return address for 3DS and other redirect flows) and notifyUrl (the webhook notification address). Unlike Checkout, the Direct API expects you to collect browser, device, and cardholder IP data (such as transactionIp) and submit them in txnOrderMsg; see the txnOrderMsg field tree for the exact requirement of each sub-field.Handle the redirect based on the response statusOnerway decides whether 3DS authentication is needed, and the status field in the synchronous response may already be terminal:ResponseHandlingstatus=SThe payment succeeded; complete the order after the webhook arrives.status=R with actionType=RedirectURLRedirect the customer's browser to the redirectUrl field to complete 3DS authentication or the local payment method page.Other valuesHandle failed or processing states according to status and respCode; see the API Reference for all values.Native apps can load redirectUrl in a WebView, watch for navigation to returnUrl, close the WebView, and query the result from the server.Handle the synchronous returnAfter authentication the customer returns to your page through returnUrl. The return is for page flow only and is not guaranteed to carry transaction parameters: add your order ID to returnUrl, show the customer a \"processing\" state when they return, and verify on your server through Query transactions. Do not use any parameter on the return URL to drive order processing.Confirm the result through webhooksOnerway POSTs the final result to notifyUrl. See Confirm the payment result for signature verification, acknowledgement, retries, and idempotency.",{"id":935,"title":936,"titles":937,"content":938,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#tokenization-and-token-payments","Tokenization and token payments",[64],"The Direct API flow for saving a payment method is: submit card data from your server to create a token, then pay with the tokenId, and list or delete saved records as needed. Choosing between customer opt-in and server-side tokenization, and the distinction between the three kinds of tokens, are covered in Saved payment methods. Create a card token: call Create card token with the card data and a stable merchantCustId field, together with notifyUrl and returnUrl. When the response status field is R, redirect the cardholder to redirectUrl to complete 3DS authentication.Confirm the saved result: the saved payment method result webhook (txnType=BIND_CARD) is the final source of truth — store the tokenId only when status=S. Neither the return to returnUrl nor the synchronous response means the payment method was saved. You can also verify with List saved tokens.Make a token payment: call Create direct transaction with subProductType=TOKEN and the tokenInfo field (tokenId set to the card token returned earlier, provider omitted), submitting the CVC the customer enters for this purchase in cardInfo.cvv and the same merchantCustId used when the token was created. A token payment may also return status=R and require 3DS authentication; handle it as described in the integration flow.Manage saved tokens: List saved tokens returns the id and tokenId of each binding record. When a customer asks to remove a card, call Delete card token with the binding record id — not the tokenId. Additional considerations for the Direct API integration: both creating a card token and making a token payment handle card data (a token payment must submit cardInfo.cvv), so both steps require PCI DSS. If you are not certified, keep both saving the card and repeat purchases on the Checkout or Web SDK page.",{"id":940,"title":801,"titles":941,"content":942,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#subscriptions",[64],"Choosing between managed and self-managed subscriptions, contract credentials, and lifecycle notifications are covered in Subscription payments. This section explains how to make the calls on the Direct API once you have chosen. All three request types use Create direct transaction with subProductType=SUBSCRIBE and the subscription field, distinguished by subscription.requestType: requestTypePurposeKey input0Initial subscription, creating the contractcardInfo or tokenInfo, merchantCustId, selfExecute, billing frequency and cycle count1Billing for the current cycle of a self-managed subscriptioncontractId, tokenId, merchantCustId, the amount for this cycle2Managed subscription plan upgrade or downgradecontractId, tokenId, changeMode, prorationMode After the initial subscription succeeds, store the contractId and tokenId from the subscription payment webhook. The initial subscription can also be completed through Checkout or the Web SDK — later billing and updates still go through the Direct API. Self-managed subscription renewal (requestType=1) submits contractId, tokenId, merchantCustId, and the amount for this cycle, with no card data, so renewals carry no PCI DSS requirement. Managed subscription plan updates (requestType=2) use the stored contractId and tokenId; when the change takes effect is controlled by the subscription.changeMode field, and prorationMode controls whether the prorated amount is calculated by remaining days or submitted by you in proration. Additional considerations for the Direct API integration: when a managed card subscription also submits subscription.bindCard=true, you receive a saved payment method result webhook and a subscription payment webhook with different transactionId values; handle each idempotently.",{"id":944,"title":806,"titles":945,"content":946,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#pre-authorization",[64],"A pre-authorization holds the order amount on the cardholder's card without charging it immediately. On the Direct API, txnType=AUTH applies to direct card payment and token payment (subProductType=DIRECT or TOKEN); it does not apply to local payment method, subscription, or installment transactions. Call Create direct transaction with txnType=AUTH; the remaining parameters are the same as a direct card or token payment. When 3DS is required, handle the status=R redirect as usual. Store the transactionId and paymentId from the response; capture or void later through Capture or void authorization. The lifecycle from authorization to capture or void, notifications, boundaries, and status handling are covered in Pre-authorization and capture.",{"id":948,"title":949,"titles":950,"content":951,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#local-payments","Local payments",[64],"A local payment method shares the create direct transaction API with card payment; only the parameter combination and flow shape differ. Set the productType field to the local payment method scope value and submit the lpmsInfo field (lpmsType selects the payment method; the remaining child fields are conditionally required per method), submitting DIRECT in subProductType for one-off payments and SUBSCRIBE for subscriptions. A local payment method does not support txnType=AUTH. Finding the supported methods and checking availability, handling the redirect and delayed settlement, method-specific parameters, and subscription behavior are covered in Local payment methods. Additional considerations for the Direct API integration: productType=ALL is an aggregated Checkout display concept and is not supported by the Direct API, so you build the method list yourself and handle the customer action returned under status=R as well as the return to your page.",{"id":953,"title":104,"titles":954,"content":955,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#profit-sharing",[64],"Profit sharing applies to the platform model: the platform merchant creates the payment with the receiving sub-merchant's merchantNo, and the payment is eligible for profit sharing only when you submit the paymentMethodOptions field with profitShare=true in its share object; the remaining parameters are the same as an ordinary transaction. When you also set profitShareRate, Onerway allocates funds automatically after a successful SALE or CAPTURE; without it, your server initiates profit sharing through the API. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Submit paymentMethodOptions as a JSON string as required by the API. Choosing between automatic and API-initiated profit sharing, result notifications, queries, and reversals are covered in Profit sharing.",{"id":957,"title":815,"titles":958,"content":959,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#confirm-the-payment-result",[64],"The final result of a Direct API integration is determined by webhooks; the payload for each scenario is documented in the payment result webhook, the saved payment method result webhook, the subscription payment webhook, and the authorization, capture, and void webhook. Signature verification, acknowledgement and retries, deduplication, status interpretation, and query fallback follow the shared rules in Webhooks. Additional considerations for the Direct API integration: this integration uses all four notification types, so your webhook endpoint must accept every notification type involved in the scenarios you use. Tokenization, subscription-with-binding, and pre-authorization flows with a later capture or void produce several related notifications with different transactionId values — associate them through paymentId and contractId. The synchronous response may already return the terminal status=S; still wait for the webhook before completing the order. If the customer has returned but no webhook has arrived, fall back to Query transactions.",{"id":961,"title":728,"titles":962,"content":963,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fapi#go-live-checklist",[64],"You hold a valid PCI DSS certification; the payment page uses TLS and never stores CVC.status=R redirects and returnUrl returns are handled, and your server queries the transaction after the return instead of trusting URL parameters.Your webhook endpoint passes the Webhooks go-live checklist and accepts every notification type used by your scenarios, including tokenization, subscription, and pre-authorization.Stored tokenId, contractId, and paymentId values are kept as strings and associated with the customer or order.The sandbox run covers the 3DS Challenge flow, the 3DS Frictionless flow, and every tokenization, subscription, pre-authorization, and local payment scenario you use.",{"id":67,"title":71,"titles":965,"content":966,"level":609},[],"The three kinds of payment methods — cards, wallets, and local payment method options — how each integration method supports them, and the availability check to run before displaying payment methods. Onerway supports three kinds of payment methods: cards (credit and debit cards from Visa, Mastercard, and other card networks), wallets (Apple Pay, Google Pay), and local payment method options (bank transfers, e-wallets, buy now pay later, and other methods specific to a country or region). This section is organized by payment method and covers setup, the differences across integration methods, and method-specific flows. The integration flow of each method is described in Checkout integration, Web SDK integration, and Direct API integration; business scenarios such as saved payment methods, subscriptions, and pre-authorization are covered in Scenarios.",{"id":968,"title":969,"titles":970,"content":971,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#support-by-integration-method","Support by integration method",[71],"Payment methodCheckoutWeb SDKDirect APICardsThe checkout page collects the card detailsThe SDK form collects the card detailsYou collect the card details yourself or pay with a card token; PCI DSS requiredApple PayThe checkout page renders the button; domain verification is handled by OnerwayThe SDK renders the button on your page; your domain must be verifiedYou render the button; your domain must be verified; the encrypted token is decrypted by Onerway or by youGoogle PayThe checkout page renders the buttonThe SDK renders the button on your pageYou load the Google Pay JS SDK; the encrypted token is decrypted by Onerway or by youLocal payment methodThe checkout page shows the available methods, or locks to oneThe SDK shows the available methodsSubmit the local payment method scope in productType with lpmsInfo, then present the redirect, QR code, or context according to actionType With Checkout and the Web SDK, wallet tokens and local payment method redirects are handled by the Onerway-hosted page or the SDK, and payment credentials never reach your system. With the Direct API, the parameter differences for wallets and each local payment method are described on the corresponding pages.",{"id":973,"title":974,"titles":975,"content":976,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#query-available-payment-methods-first","Query available payment methods first",[71],"Whether a payment method is available depends on your merchant configuration, the customer's country or region, the currency, and the amount; do not decide by currency alone. Before displaying payment methods, call List available payment methods to filter by the current order context, cache the result, and refresh it when your configuration changes. Currency and amount rules are covered in Currency and amount validation. Wallet records in the result carry the local payment method scope value in productType for classification only; when creating a wallet transaction through the Direct API, always submit productType=CARD with subProductType=DIRECT. Wallet records also return the configuration needed to initialize the wallet on your page: both ApplePay and GooglePay may return countryCode, subCardTypes, gatewayName, and merchantId, while gatewayMerchantId is returned for GooglePay only; see the wallet pages for how to use each value.",{"id":978,"title":979,"titles":980,"content":981,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#payment-method-in-notifications","Payment method in notifications",[71],"The payment result webhook returns the payment method that was actually charged in paymentMethod, and wallet transactions may additionally return walletTypeName. Which of the two carries which level of detail varies by wallet, so read both when you need to identify the payment method; walletTypeName has a documented value list, while paymentMethod reflects the channel that was actually charged and is not a closed set. Signature verification, acknowledgement, and status interpretation are covered in Webhooks.",{"id":74,"title":73,"titles":983,"content":984,"level":609},[],"How Apple Pay differs across Checkout, Web SDK, and Direct API, domain verification and account setup, the Direct API session flow and token submission, wallet subscriptions, and common issues. Apple Pay lets customers pay with a card already added to Wallet, using Face ID or Touch ID. With Checkout and the Web SDK, Onerway renders the Apple Pay button and handles the token, and you only need to complete domain registration. With the Direct API, you render the button, drive ApplePaySession, and submit the encrypted payment token returned by Apple to Onerway.",{"id":986,"title":987,"titles":988,"content":989,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#choose-an-integration-method","Choose an integration method",[73],"Integration methodButton and sessionToken handlingWhat you doCheckoutRendered and driven by the checkout pageNever reaches your systemSubmit productType=ALL, or lpmsInfo.lpmsType=ApplePay to lock to Apple PayWeb SDKRendered and driven by the SDK on your page; appearance in Configure wallet buttonsNever reaches your systemVerify your domain; receive the result through payment_result, see SDK-owned buttonsDirect APIYour own button and ApplePaySessionDecrypted by Onerway or by youVerify your domain; every step under \"Direct API integration\" on this page The checkout page is hosted by Onerway and its domain is already registered with Apple, so no domain verification is needed. The Web SDK and the Direct API show the Apple Pay button on your own domain, which Apple requires to be verified first; see \"Setup\". All three methods require HTTPS across your site with TLS 1.2 or later and Apple Pay enabled on your Onerway merchant account. Sandbox prerequisites and test cards are listed in Apple Pay sandbox testing.",{"id":991,"title":992,"titles":993,"content":994,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#browser-and-device-support","Browser and device support",[73,987],"Apple Pay on the Web is no longer limited to Safari: Safari, and third-party browsers on iOS \u002F iPadOS (all WebKit-based): the payment completes on the device.Compatible third-party browsers on Mac, Windows, and other devices: the page shows a QR code that the customer scans with an iPhone or iPad running iOS 18 \u002F iPadOS 18 or later. Direct API merchants must use the \u003Capple-pay-button> element from Apple Pay JS SDK 1.2.0 or later; CSS-rendered buttons do not work in non-Safari browsers.China mainland: Safari on iPhone and iPad only; third-party browsers are not available. Checkout and the Web SDK handle these differences for you; Direct API merchants get the same coverage by using the official SDK and button element as shown on this page. See the Apple support article for the authoritative list.",{"id":996,"title":20,"titles":997,"content":998,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#setup",[73],"Apple requires every merchant domain that shows the Apple Pay button to pass domain verification, which is bound to a Merchant ID in an Apple Developer account. Depending on who holds the Merchant ID, setup falls into three tiers: TierDomain and merchant validationToken decryptionSuitable forDefaultYour own Apple Developer account: create the Merchant ID, verify the domains yourself, and request the merchant session from Apple with your own Merchant Identity certificateOnerway decryption: Onerway generates the CSR for the payment processing certificate, and you upload it to your Merchant IDMost merchantsMerchant decryptionSame as DefaultYou hold the payment processing certificate and submit the decrypted result in cardInfo; PCI DSS requiredMerchants with PCI DSS and certificate management capabilityOnerway proxyDomains are registered under the Onerway Apple Developer account, and you call Validate Apple Pay merchant to obtain the merchant sessionOnerway decryptionMerchants without an Apple Developer account, or that do not want to maintain one The Web SDK only involves domain verification, so complete either the Default or the Onerway proxy tier. Do not mix your own Merchant ID with Onerway proxy validation. In both domain verification approaches, your own account and the Onerway proxy, the verification file is deployed under the .well-known path of your site (follow the exact path given by Apple Developer or by Onerway). The address must not sit behind a proxy or redirect, and must be reachable by Apple's verification servers: https:\u002F\u002Fyour-store.com\u002F.well-known\u002Fapple-developer-merchantid-domain-association",{"id":1000,"title":1001,"titles":1002,"content":1003,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#your-own-account","Your own account",[73,20],"Create a Merchant ID: sign in to Apple Developer, open Merchant IDs under Certificates, Identifiers & Profiles, and register one with a Description and an Identifier such as merchant.com.yourcompany.appname. Skip this step if you already have one.Configure the payment processing certificate: for the Default tier, first give the Merchant ID to Onerway technical support and obtain the CSR that Onerway generates. Create the certificate under Apple Pay Payment Processing Certificate for that Merchant ID, answer No to \"Will payments be processed exclusively in China mainland?\", and upload that CSR. Once the certificate is created, download the .cer file and send it back to Onerway: Onerway holds the matching private key and can decrypt Apple Pay tokens only after receiving the certificate. For the Merchant decryption tier, generate the CSR yourself and keep the private key.Configure the Merchant Identity certificate (Direct API only): create and download it under Apple Pay Merchant Identity Certificate following Apple's CSR guide, store it securely on your merchant validation server, and use it to request an Apple Pay payment session.Verify the domain: add the domain under Merchant Domains, download the verification file, deploy it to the path above, confirm it is reachable over HTTPS, and click Verify in Apple Developer. Domain verification expires together with your site's SSL certificate: Apple re-checks 30, 15, and 7 days before expiry, so renewing the SSL certificate in advance keeps the verification valid; if you replace the certificate only after it expires, verify the domain again. The payment processing and Merchant Identity certificates each expire after 25 months; the Merchant ID does not expire.",{"id":1005,"title":1006,"titles":1007,"content":1008,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#onerway-proxy","Onerway proxy",[73,20],"Give Onerway technical support every domain that shows the Apple Pay button, including subdomains and both sandbox and production domains, in the form https:\u002F\u002Fyour-store.com.Onerway registers the domains and returns the verification file; deploy it to the path above and confirm it is reachable: curl -I https:\u002F\u002Fyour-store.com\u002F.well-known\u002Fapple-developer-merchantid-domain-association Onerway completes domain verification with Apple and notifies you. The payment processing and Merchant Identity certificates are held and renewed by Onerway; you do not manage them. In every tier, keep certificates in a controlled environment with least-privilege access, and monitor the expiry of both your SSL certificate and the Apple certificates.",{"id":1010,"title":64,"titles":1011,"content":1012,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#direct-api-integration",[73],"You render the button and drive ApplePaySession; the encrypted payment token returned by Apple is submitted to Onerway according to the decryption mode. Choose one mode; never submit tokenInfo and cardInfo together. Onerway decryption (recommended; Default and Onerway proxy tiers): serialize the whole event.payment.token to a string and put it in tokenInfo.tokenId unchanged, without taking apart paymentData, paymentMethod, and transactionIdentifier. \"tokenInfo\": \"{\\\"provider\\\":\\\"ApplePay\\\",\\\"tokenId\\\":\\\"\u003Cevent.payment.token serialized as a string>\\\"}\" Merchant decryption (this tier; PCI DSS required): omit tokenInfo and put the decrypted result in cardInfo as shown below. Decrypted Apple fieldcardInfo fieldapplicationPrimaryAccountNumbercardNumberapplicationExpirationDate (YYMMDD)month from digits 3 and 4; year from the first two digits expanded to four, for example 30 becomes 2030onlinePaymentCryptogramcryptogrameciIndicatorecipaymentDataTypewallet.applePay.paymentDataType, 3DSecure or EMV, whichever your decryption returns Complete requests are shown in the \"Onerway-decrypted Apple Pay payment\" and \"Merchant-decrypted Apple Pay payment\" examples of Create direct transaction. Load the Apple Pay JS SDK on the page first: the auto-updating 1.latest address is recommended; cross-browser support requires 1.2.0 or later; if you pin a version, use the v1.x.y path and add integrity, which 1.latest does not support. The SDK injects ApplePaySession in non-Safari browsers. Check availability and show the buttonAfter loading the Apple Pay JS SDK, show the button only when ApplePaySession exists and canMakePayments() returns true. To check whether the customer already has a usable card, use applePayCapabilities(); it returns only paymentCredentialStatusUnknown in non-Safari browsers, in which case you should still show the button. canMakePaymentsWithActiveCard() is deprecated. Use the \u003Capple-pay-button> element provided by the SDK; style attributes are documented in Apple Pay button and branding in the Human Interface Guidelines.\u003Cscript src=\"https:\u002F\u002Fapplepay.cdn-apple.com\u002Fjsapi\u002F1.latest\u002Fapple-pay-sdk.js\">\u003C\u002Fscript>\n\u003Capple-pay-button buttonstyle=\"black\" type=\"buy\" locale=\"en-US\">\u003C\u002Fapple-pay-button>\nFetch the Onerway configurationOn your server, call List available payment methods, take the paymentMethod=ApplePay record, and return countryCode and subCardTypes to the page as the payment request countryCode and supportedNetworks; both are already in the format Apple expects, so pass them through unchanged. applePayCapabilities() needs a merchant identifier: your own Merchant ID in the own-account tiers, or the merchantId returned by List available payment methods in the Onerway proxy tier.Create the payment sessionUse supportsVersion() to find the highest version the browser supports, from newest to oldest, then create the ApplePaySession and call begin(). The payment request needs at least countryCode, currencyCode, supportedNetworks, merchantCapabilities including supports3DS, and total with label, amount, and type: 'final', where amount is a string.Check the validationURL and obtain the merchant sessionIn the onvalidatemerchant event, take validationURL, confirm that its host is an Apple validation gateway (apple-pay-gateway.apple.com, cn-apple-pay-gateway.apple.com for China mainland, with the matching -cert hosts in the sandbox) and call abort() for anything else, then hand it to your server. Your server must re-check the host before forwarding it, never rely on the page check alone, and never hard-code the validation address. In the own-account tiers, your server makes an mTLS request to Apple with the Merchant Identity certificate, sending merchantIdentifier, displayName (a stable store name, not localized and without order numbers), initiative as web, and initiativeContext as the full domain. In the Onerway proxy tier, call Validate Apple Pay merchant and parse the data in the response into an object.Complete merchant validationCall completeMerchantValidation() as soon as you have the session. A merchant session can be used once and expires five minutes after creation: request it on the server at that moment, never from the client directly against Apple.Authorize the paymentIn the onpaymentauthorized event, send event.payment.token to your server, which calls Create direct transaction with productType=CARD, subProductType=DIRECT, and txnType=SALE, submitting tokenInfo or cardInfo according to the decryption mode. Based on the server result, the page calls completePayment() with the success or failure status, exactly once; otherwise the Apple Pay sheet stays open.Confirm the final resultIn the synchronous response, status=S means success and P means processing; the final state is determined by the payment result webhook, which carries walletTypeName=ApplePay for wallet transactions. Signature verification, acknowledgement, and deduplication are covered in Webhooks.",{"id":1014,"title":1015,"titles":1016,"content":1017,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#front-end-example","Front-end example",[73],"The three internal server endpoints are yours to implement; they correspond to fetching the configuration, validating the merchant, and authorizing the payment. \u003Capple-pay-button id=\"applePayButton\" buttonstyle=\"black\" type=\"buy\" locale=\"en-US\" style=\"display:none;\">\u003C\u002Fapple-pay-button>\n\u003Cscript src=\"https:\u002F\u002Fapplepay.cdn-apple.com\u002Fjsapi\u002F1.latest\u002Fapple-pay-sdk.js\">\u003C\u002Fscript>\n\u003Cscript>\n const button = document.getElementById('applePayButton')\n\n \u002F\u002F Server calls List available payment methods and returns { countryCode, subCardTypes }\n const fetchConfig = () => fetch('\u002Fapi\u002Fapple-pay\u002Fconfig').then(r => r.json())\n \u002F\u002F Server obtains the merchant session for your tier: own account via the Merchant Identity certificate, Onerway proxy via Validate Apple Pay merchant\n const validateMerchant = (validationURL, website) =>\n fetch('\u002Fapi\u002Fapple-pay\u002Fvalidate-merchant', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ validationURL, website })\n }).then(r => r.json())\n \u002F\u002F Server calls Create direct transaction (tokenInfo.provider=ApplePay) and returns { success: boolean }\n const processPayment = (paymentToken) =>\n fetch('\u002Fapi\u002Fapple-pay\u002Fprocess-payment', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ paymentToken })\n }).then(r => r.json())\n\n \u002F\u002F Accept only Apple's validation gateway hosts, including the China mainland and sandbox domains\n const APPLE_PAY_GATEWAY = \u002F^(cn-)?apple-pay-gateway(-[a-z0-9-]+)?\\.apple\\.com$\u002F\n\n const highestSupportedVersion = () => {\n for (let version = 14; version >= 3; version -= 1) {\n if (ApplePaySession.supportsVersion(version)) return version\n }\n return 3\n }\n\n function startSession(config) {\n const paymentRequest = {\n countryCode: config.countryCode,\n currencyCode: 'USD',\n supportedNetworks: config.subCardTypes,\n merchantCapabilities: ['supports3DS'],\n total: { label: 'Example Store', amount: '99.99', type: 'final' }\n }\n const session = new ApplePaySession(highestSupportedVersion(), paymentRequest)\n\n session.onvalidatemerchant = async (event) => {\n \u002F\u002F Your server must validate the host again; do not rely on this check alone\n if (!APPLE_PAY_GATEWAY.test(new URL(event.validationURL).hostname)) {\n session.abort()\n return\n }\n try {\n const merchantSession = await validateMerchant(event.validationURL, window.location.hostname)\n session.completeMerchantValidation(merchantSession)\n } catch {\n session.abort()\n }\n }\n\n session.onpaymentauthorized = async (event) => {\n try {\n const result = await processPayment(event.payment.token)\n session.completePayment(result.success ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE)\n } catch {\n session.completePayment(ApplePaySession.STATUS_FAILURE)\n }\n }\n\n session.oncancel = () => {\n \u002F\u002F The customer closed the Apple Pay sheet; restore the page\n }\n\n session.begin()\n }\n\n async function init() {\n if (!window.ApplePaySession || !ApplePaySession.canMakePayments()) return\n const config = await fetchConfig()\n button.style.display = 'block'\n button.addEventListener('click', () => startSession(config))\n }\n init()\n\u003C\u002Fscript> Apple's interactive demo walks through the complete flow.",{"id":1019,"title":1020,"titles":1021,"content":1022,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#wallet-subscriptions","Wallet subscriptions",[73],"Apple Pay can be used for subscriptions: submit subProductType=SUBSCRIBE with subscription on the initial subscription; both selfExecute=1 (managed by Onerway) and selfExecute=2 (you initiate each billing) are supported. On Checkout, lock to Apple Pay with lpmsInfo.lpmsType=ApplePay; on the Direct API, submit the encrypted wallet token in tokenInfo to create the initial subscription. After the initial subscription succeeds, the subscription payment webhook returns contractId and the subscription tokenId; renewals and plan changes then work the same as card subscriptions, see Subscription payments. Differences from card subscriptions: the encrypted wallet token is single-use and cannot be saved for reuse, so the only billing credential during the subscription is the subscription token; wallet subscriptions produce no saved payment method result webhook and return no card token.",{"id":1024,"title":1025,"titles":1026,"content":1027,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#common-issues","Common issues",[73],"SymptomCommon causesWhat to doThe button does not appearApple Pay JS SDK not loaded or a CSS button used, not HTTPS, unsupported device or browser, or Apple Pay not available in the country or regionUse the SDK \u003Capple-pay-button>; show it only when canMakePayments() is true; an unknown status from applePayCapabilities() in non-Safari browsers is normal; offer other payment methodsThe sheet flashes and closes after tappingMerchant validation failed: validationURL rejected, the merchant session older than five minutes or reused, the domain verification file missing or unreachable, domain verification lapsed with an expired SSL certificate, or initiativeContext not matching the verified domainConfirm completeMerchantValidation is called; confirm the verification file returns 200 with curl -I; check the domains match; contact Onerway to regenerate certificates; do not mix sandbox and production merchant identifiersThe page reports the payment incomplete after confirmationcompletePayment() not called or called more than once; total.amount not a string or with wrong precision; payment processing certificate in an abnormal stateCheck the page logic; contact Onerway support if it still failsSandbox test cards are declinedNo sandbox tester account, device region not matching the test card network, or the card not added to WalletComplete the prerequisites in Apple Pay sandbox testing When contacting Onerway technical support, provide your merchant number and setup tier, the time and environment (sandbox or production), the device, OS, and browser version, complete console and network logs, and reproduction steps.",{"id":1029,"title":728,"titles":1030,"content":1031,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#go-live-checklist",[73],"Every sandbox and production domain is verified, the verification file is reachable, and SSL certificate renewal is monitored.Merchant sessions are requested only on the server, and validationURL is checked on both the page and the server.completePayment() is called exactly once on both success and failure.Apple Pay payment tokens are never logged or stored.Webhook signature verification and deduplication are in place. html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .ssf8z, html code.shiki .ssf8z{--shiki-light:#90A4AE;--shiki-default:#622CBC;--shiki-dark:#BABED8}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .sxVtM, html code.shiki .sxVtM{--shiki-light:#E53935;--shiki-default:#032563;--shiki-dark:#F07178}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .stp_H, html code.shiki .stp_H{--shiki-light:#90A4AE;--shiki-light-font-weight:inherit;--shiki-default:#024C1A;--shiki-default-font-weight:bold;--shiki-dark:#BABED8;--shiki-dark-font-weight:inherit}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}",{"id":78,"title":77,"titles":1033,"content":1034,"level":609},[],"How Google Pay differs across Checkout, Web SDK, and Direct API, website registration before going live, choosing the merchant identifier and decryption mode, the Direct API front-end configuration and transaction flow, the two paths for PAN_ONLY tokens, wallet subscriptions, and common issues. Google Pay lets customers check out quickly with a card saved to their Google account, in Chrome, Safari, Firefox, Edge, and other major browsers. With Checkout and the Web SDK, Onerway renders the Google Pay button and handles the token. With the Direct API, you load the Google Pay JS SDK yourself, obtain the encrypted payment token, and submit it to Onerway.",{"id":1036,"title":987,"titles":1037,"content":1038,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#choose-an-integration-method",[77],"Integration methodButton and tokenWhat you doCheckoutThe checkout page renders the button; the token never reaches your systemSubmit productType=ALL, or lpmsInfo.lpmsType=GooglePay to lock to Google PayWeb SDKThe SDK renders the button on your page, appearance in Configure wallet buttons; the token never reaches your systemReceive the result through payment_result, see SDK-owned buttons; embedded WebView limits in Google Pay in embedded app WebViewsDirect APIYou load the Google Pay JS SDK and obtain the tokenEvery step under \"Direct API integration\" on this page All three methods require HTTPS and Google Pay enabled on your Onerway merchant account. Browser and device support follows the Google Pay Web documentation; for sandbox testing, join the test card group with a Google account, see Test cards.",{"id":1040,"title":20,"titles":1041,"content":1042,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#setup",[77],"Before integrating through the Direct API, decide how token authentication methods are handled, who decrypts the token, and where the merchant identifier comes from.",{"id":1044,"title":1045,"titles":1046,"content":1047,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#token-authentication-method","Token authentication method",[77,20],"authMethod is determined by the status of the customer's card on the Google side and you cannot choose it; Onerway requires allowedAuthMethods to declare both values below, accepting only one is not supported: CRYPTOGRAM_3DS: a card the customer has tokenized on the device; the token carries a dynamic cryptogram and 3DS credentials and can be authorized directly.PAN_ONLY: a card saved to the Google account but not tokenized on a device; the token carries no 3DS credentials, so the CVC must be collected before it can be charged, see \"Two paths for PAN_ONLY tokens\". Both values occur in real traffic, and not declaring PAN_ONLY means you cannot charge those customers. PAN_ONLY does not mean the card number reaches you: with Onerway decryption the token is encrypted with the Onerway key and the card number never enters your systems, and on the standard path the CVC is collected on an Onerway-hosted page, so no PCI DSS compliance is required. PCI DSS applies only if you choose merchant decryption or collect the CVC yourself.",{"id":1049,"title":1050,"titles":1051,"content":1052,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#decryption-mode","Decryption mode",[77,20],"ModeFront-end tokenizationSubmitted to OnerwayPrerequisiteOnerway decryption (recommended)PAYMENT_GATEWAY, with the gateway parameters from List available payment methodstokenInfo, token passed through unchangedNoneMerchant decryptionDIRECT, ECv2 with the public key registered in your own Google Pay & Wallet ConsoleOmit tokenInfo; put the decrypted result in cardInfoPCI DSS required For merchant decryption, map the decrypted result into cardInfo as follows: Decrypted Google fieldcardInfo fieldpancardNumberexpirationMonth, expirationYearmonth, yearauthMethodwallet.googlePay.authMethodcryptogram, eciIndicator (CRYPTOGRAM_3DS only)cryptogram, eci",{"id":1054,"title":1055,"titles":1056,"content":1057,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#merchant-identifier","Merchant identifier",[77,20],"Google requires merchantInfo.merchantId when environment is PRODUCTION (optional in TEST). Its value depends on how your domain is registered; choose one: Onerway registers your domain under its Google Pay & Wallet Console profile: use the merchantId returned by List available payment methods.You register your own Google Pay & Wallet Console profile and domain: use your own merchant identifier. Merchant decryption requires this option. Confirm with Onerway technical support which account you will use, then complete website registration before going live.",{"id":1059,"title":1060,"titles":1061,"content":1062,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#website-registration-before-going-live","Website registration before going live",[77],"This applies only to Direct API integrations; Checkout and the Web SDK use Onerway's Google Pay integration and need no website registration. Register your website and obtain Google's approval before accepting production payments; a successful sandbox test does not replace it. Follow Google's Publish your integration guide for the Google Pay account you use: Google Pay accountWho submits the website for approvalWhat you need to doYour own accountYouAdd the website in your Google Pay & Wallet Console with its domain and integration screenshots, then submit it for approval.Onerway's accountOnerwaySend the domain and the five screenshots below to Onerway technical support; Onerway submits the website and notifies you of the result. The domain is the website that calls the Google Pay API. The account determines only the merchantInfo.merchantId to use: your own account does not require merchant decryption, and when Onerway decrypts the token, gatewayName and gatewayMerchantId still come from List available payment methods.",{"id":1064,"title":1065,"titles":1066,"content":1067,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#five-screenshots-for-onerway-registration","Five screenshots for Onerway registration",[77,1060],"Provide one screenshot for each stage of your purchase flow: ScreenshotWhat it must showItem selectionThe customer browsing an item or service.Pre-purchase screenThe customer ready to make a purchase.Payment method screenThe customer selecting Google Pay as the payment method.Google Pay API payment screenThe Google Pay payment sheet showing the customer's saved payment information.Post-purchase screenThe page shown after a successful purchase. If Android blocks screenshots of the Google Pay payment sheet, photograph the screen with another device; for this item only, an image of an error message is also accepted.",{"id":1069,"title":1070,"titles":1071,"content":1072,"level":667},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#switch-to-production-after-approval","Switch to production after approval",[77,1060],"After Google approves the website, set the merchantInfo.merchantId of the registering account, create the PaymentsClient with environment=PRODUCTION, and create transactions with your Onerway production API base URL and credentials.",{"id":1074,"title":64,"titles":1075,"content":1076,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#direct-api-integration",[77],"Fetch the Onerway configurationOn your server, call List available payment methods, take the paymentMethod=GooglePay record, and return the configuration to the page. Cache it and refresh it when it changes.Returned fieldGoogle Pay parametergatewayNamegateway in tokenizationSpecificationgatewayMerchantIdgatewayMerchantId in tokenizationSpecificationsubCardTypesallowedCardNetworks, already upper case as Google expects; pass through unchangedmerchantIdmerchantInfo.merchantId (see \"Merchant identifier\")countryCodetransactionInfo.countryCodeInitialize and show the buttonLoad the Google Pay JS SDK, create a PaymentsClient, check availability with isReadyToPay(), and render the official button with createButton() once it passes.\u003Cscript async src=\"https:\u002F\u002Fpay.google.com\u002Fgp\u002Fp\u002Fjs\u002Fpay.js\" onload=\"onGooglePayLoaded()\">\u003C\u002Fscript>\nconst paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' }) \u002F\u002F 'PRODUCTION' when live\nStart the paymentOn click, build the PaymentDataRequest, call loadPaymentData(), and take the token from tokenizationData.token in the result to your server. The request needs at least apiVersion: 2, allowedPaymentMethods with the tokenization parameters, transactionInfo with totalPriceStatus as FINAL plus totalPrice, currencyCode, and countryCode, and merchantInfo. Enable emailRequired or shippingAddressRequired if you want the Google Pay sheet to collect contact details.Create the transactionOn your server, call Create direct transaction with productType=CARD, subProductType=DIRECT, and txnType=SALE, submitting tokenInfo or cardInfo according to the decryption mode; complete requests are shown in the \"Onerway-decrypted Google Pay payment\" and \"Merchant-decrypted Google Pay CRYPTOGRAM_3DS payment\" examples of that endpoint.Handle the synchronous responseA respCode other than 20000 is a failure; data.status=S is success; data.status=R with actionType=RedirectURL means the token is PAN_ONLY and the CVC is still needed: redirect the customer to redirectUrl (an Onerway-hosted page) immediately, and the customer returns to txnOrderMsg.returnUrl after entering it. In that response transactionId is null, so associate the order by merchantTxnId. Any other status is processing; wait for the webhook.Confirm the final resultThe final state is determined by the payment result webhook, which carries walletTypeName=GooglePay for wallet transactions; check that the amount and currency in the webhook match your order. Signature verification, acknowledgement, and deduplication are covered in Webhooks.",{"id":1078,"title":1079,"titles":1080,"content":1081,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#two-paths-for-pan_only-tokens","Two paths for PAN_ONLY tokens",[77],"AspectStandard pathYou collect the CVCCVC collectionOnerway-hosted pageYour own input fieldCustomer experienceOne redirect and returnNo redirectImplementationHandle the status=R redirect onlyOne extra check call plus a CVC inputCVC security responsibilityOnerwayYou: never store or log it, transmit over HTTPS, clear it after use Neither path needs extra enablement. When you collect the CVC yourself: After obtaining the token, call Check Google Pay PAN_ONLY token first.When checkResult=false, collect the CVC from the customer and create the direct transaction with the same tokenInfo and the CVC in cardInfo.cvv. For a PAN_ONLY token submitted without cardInfo.cvv, the transaction response contains data.status=R and data.redirectUrl; redirect the customer to data.redirectUrl to enter the CVC on the Onerway-hosted page. This applies whether or not you called the check endpoint before creating the transaction.When checkResult=true, create the direct transaction with the same tokenInfo; cardInfo is not required.The check and the transaction must use the same token and the same merchantTxnId; fall back to the standard path if the check call fails.Validate the CVC length in real time (3 digits for most card networks, 4 for American Express), display it as a password field, and tell the customer why it is needed.",{"id":1083,"title":1015,"titles":1084,"content":1085,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#front-end-example",[77],"Fill in the configuration from your server; processPayment hands the token to your server. \u003Cdiv id=\"container\">\u003C\u002Fdiv>\n\u003Cscript>\n \u002F\u002F Configuration from the GooglePay record returned by List available payment methods on your server\n const onerwayConfig = {\n gateway: '\u003CgatewayName>',\n gatewayMerchantId: '\u003CgatewayMerchantId>',\n allowedCardNetworks: ['MASTERCARD', 'VISA'],\n merchantId: '\u003CmerchantId>',\n countryCode: 'US'\n }\n\n const baseRequest = { apiVersion: 2, apiVersionMinor: 0 }\n const baseCardPaymentMethod = {\n type: 'CARD',\n parameters: { allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'], allowedCardNetworks: onerwayConfig.allowedCardNetworks }\n }\n const cardPaymentMethod = {\n ...baseCardPaymentMethod,\n tokenizationSpecification: {\n type: 'PAYMENT_GATEWAY',\n parameters: { gateway: onerwayConfig.gateway, gatewayMerchantId: onerwayConfig.gatewayMerchantId }\n }\n }\n\n let paymentsClient = null\n function getPaymentsClient() {\n if (!paymentsClient) {\n paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' }) \u002F\u002F 'PRODUCTION' when live\n }\n return paymentsClient\n }\n\n function getPaymentDataRequest() {\n return {\n ...baseRequest,\n allowedPaymentMethods: [cardPaymentMethod],\n transactionInfo: { countryCode: onerwayConfig.countryCode, currencyCode: 'USD', totalPriceStatus: 'FINAL', totalPrice: '99.99' },\n merchantInfo: { merchantId: onerwayConfig.merchantId, merchantName: 'Example Store' }\n }\n }\n\n function onGooglePayLoaded() {\n getPaymentsClient()\n .isReadyToPay({ ...baseRequest, allowedPaymentMethods: [baseCardPaymentMethod] })\n .then((res) => {\n if (!res.result) return\n const button = getPaymentsClient().createButton({ onClick: onButtonClicked, allowedPaymentMethods: [baseCardPaymentMethod] })\n document.getElementById('container').appendChild(button)\n })\n }\n\n function onButtonClicked() {\n getPaymentsClient()\n .loadPaymentData(getPaymentDataRequest())\n .then(processPayment)\n .catch(() => {\n \u002F\u002F The customer closed the Google Pay sheet or the payment failed; restore the page\n })\n }\n\n async function processPayment(paymentData) {\n \u002F\u002F Never log or store the token\n const paymentToken = paymentData.paymentMethodData.tokenizationData.token\n \u002F\u002F Server calls Create direct transaction (tokenInfo.provider=GooglePay), maps a respCode other than 20000 to status 'F', and returns { status, redirectUrl }\n const res = await fetch('\u002Fapi\u002Fgoogle-pay\u002Fprocess-payment', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ paymentToken })\n }).then(r => r.json())\n\n if (res.status === 'R' && res.redirectUrl) {\n window.location.href = res.redirectUrl \u002F\u002F PAN_ONLY: redirect to the Onerway-hosted page to collect the CVC; the final state comes from the webhook\n } else if (res.status === 'S') {\n \u002F\u002F Synchronous success; the payment result webhook remains the final source of truth\n } else if (res.status === 'F') {\n \u002F\u002F Failed; ask the customer to choose another payment method\n } else {\n \u002F\u002F Processing; wait for the payment result webhook\n }\n }\n\u003C\u002Fscript>\n\u003Cscript async src=\"https:\u002F\u002Fpay.google.com\u002Fgp\u002Fp\u002Fjs\u002Fpay.js\" onload=\"onGooglePayLoaded()\">\u003C\u002Fscript> Google resources: Web integration guide, interactive demos, brand guidelines.",{"id":1087,"title":1020,"titles":1088,"content":1089,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#wallet-subscriptions",[77],"Google Pay can be used for subscriptions: submit subProductType=SUBSCRIBE with subscription on the initial subscription; both selfExecute=1 (managed by Onerway) and selfExecute=2 (you initiate each billing) are supported. On Checkout, lock to Google Pay with lpmsInfo.lpmsType=GooglePay; on the Direct API, submit the encrypted wallet token in tokenInfo to create the initial subscription. After the initial subscription succeeds, the subscription payment webhook returns contractId and the subscription tokenId; renewals and plan changes then work the same as card subscriptions, see Subscription payments. Differences from card subscriptions: the encrypted wallet token is single-use and cannot be saved for reuse, so the only billing credential during the subscription is the subscription token; wallet subscriptions produce no saved payment method result webhook and return no card token.",{"id":1091,"title":1025,"titles":1092,"content":1093,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#common-issues",[77],"SymptomCommon causesWhat to doThe button does not appearpay.js not loaded, not HTTPS, no usable card in the account, or an embedded app WebView that does not meet the requirementsCheck the isReadyToPay() result; for WebViews see Web SDK integrationConfiguration cannot be fetchedYour server did not return gatewayName, gatewayMerchantId, or subCardTypesCheck the List available payment methods call and filteringThe production sheet reports an unverified merchantmerchantInfo.merchantId missing or not matching the domain registration approachConfirm the source of the value under \"Merchant identifier\"PAN_ONLY not handledCreate direct transaction returned redirectUrl but the page did not redirectRedirect as soon as redirectUrl is returned, or switch to collecting the CVC yourself",{"id":1095,"title":728,"titles":1096,"content":1097,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#go-live-checklist",[77],"Direct API only: website registration is complete and approved by Google.The token is never decrypted on the client and never logged or stored.Both the PAN_ONLY redirect path and the CRYPTOGRAM_3DS direct success path have been tested with real cards.If you collect the CVC yourself, the fallback for a failed check call has been tested.Webhook signature verification, deduplication, and amount checks are in place. html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sxVtM, html code.shiki .sxVtM{--shiki-light:#E53935;--shiki-default:#032563;--shiki-dark:#F07178}",{"id":82,"title":81,"titles":1099,"content":1100,"level":609},[],"How to find which methods Onerway supports and which are available for an order, the differences across integration methods, the three customer actions and delayed settlement, method-specific parameters, subscription-capable methods, and the extra requirements of some regional methods. A local payment method is a method other than a card or a wallet that serves a specific country or region, covering bank transfers and online banking, virtual accounts, e-wallets, QR codes, convenience stores and cash vouchers, prepaid cards, carrier billing, and buy now pay later. They share the create-transaction API with card payment; what differs is that the customer leaves your page to pay in the payment method's own interface, and that some methods do not settle instantly. All three integration methods can use a local payment method: Checkout and the Web SDK display the available methods and handle the customer action for you, while with the Direct API you select the method and handle it yourself. A local payment method does not support pre-authorization (txnType=AUTH).",{"id":1102,"title":1103,"titles":1104,"content":1105,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#query-available-payment-methods","Query available payment methods",[81],"The methods Onerway supports are the values of the lpmsInfo.lpmsType field; each value carries a description of the method and can serve as an index of method names while you integrate. Two of those values, ApplePay and GooglePay, are wallets — see Apple Pay and Google Pay for those. Which methods are actually available for a given order depends on your merchant configuration, the customer's country or region, the currency, and the amount, so take it from the response of List available payment methods: do not decide availability by currency alone. Each returned record identifies its method in data[].paymentMethod, and lpmsInfo.lpmsType takes the same value when you create the transaction. Currency and amount rules are covered in Currency and amount validation. When you build the method list yourself — with the Direct API, or with Checkout locked to a single method — query before displaying and do not hard-code the list in your front end; the result can be cached and refreshed when your configuration changes. When Checkout or the Web SDK displays every available method, Onerway filters them for you and you do not need to call it. For per-transaction limits, and for the extra merchant registration or regional requirements that some methods have, contact Onerway support.",{"id":1107,"title":987,"titles":1108,"content":1109,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#choose-an-integration-method",[81],"Integration methodDisplay and selectionKey parametersCheckoutThe checkout page displays the methods available for the order and the customer chooses; it can also be locked to a single methodSubmit productType=ALL to display every available method; add lpmsInfo.lpmsType to lock to a single methodWeb SDKThe SDK displays the available methods on your page and renders QR codes and other presented interfacesproductType=ALL; a local payment method is confirmed by your own button calling confirmPayment()Direct APIYou build the method list and name the method when creating the transaction, and handle the customer action yourselfThe local payment method scope value of the productType field, lpmsInfo; submit DIRECT in subProductType for one-off payments and SUBSCRIBE for subscriptions With Checkout and the Web SDK, the customer action and the presented interfaces are handled by the Onerway-hosted page or the SDK. The rest of this page covers the Direct API calls and the settlement timing that all three integration methods share; subscription authorization is documented for the Direct API only.",{"id":1111,"title":64,"titles":1112,"content":1113,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#direct-api-integration",[81],"Create the transactionOnce the customer has chosen a method, call Create direct transaction from your server with the local payment method scope value of the productType field, subProductType=DIRECT (use SUBSCRIBE for subscriptions, see Local payment method subscriptions), txnType=SALE, and the lpmsInfo field: lpmsType names the method and the remaining child fields are conditionally required per method, see Method-specific parameters. productType=ALL is an aggregated Checkout display concept and is not supported by the Direct API.Handle the customer actionA response of status=R means the customer still has one action to take, and the actionType field says which. Handle all three values:actionTypeWhat to doRedirectURLRedirect the customer to the redirectUrl field. What the customer sees is determined by the method: a bank selection page, the bank app, or an online banking authorization pageQrCodeDisplay the QR code or barcode carried by the codeForm field on your own page; when that field carries an expireTime, handle expiry accordinglyShowContextDisplay the contextual content carried by the presentContext field on your own pageFor methods that open a native app, verify that opening the app and returning to your site both work in mobile browsers.Handle the synchronous returnWith redirect methods, the customer returns to your page through txnOrderMsg.returnUrl after completing or abandoning the payment. The return is only a page transition: it is not guaranteed to carry transaction parameters and it does not mean the payment is complete. Append your own order reference to returnUrl, show the customer a processing state when they return, and verify the result from your server with Query transactions.Confirm the final resultThe final state comes from the payment result webhook, whose paymentMethod field returns the method that was actually charged. Signature verification, acknowledgement and retries, idempotent deduplication, and query-based compensation are covered in Webhooks.",{"id":1115,"title":1116,"titles":1117,"content":1118,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#method-specific-parameters","Method-specific parameters",[81],"Apart from lpmsType, lpmsInfo has five child fields, each conditionally required depending on the method you selected: Child fieldWhat it collectsbankNameThe bank the customer chose; needed by EFT and Przelewy24; the selectable banks are listed under the lpmsInfo field reference belowwalletAccountIdWallet or local account identifierwalletAccountNameWallet or local account nameiBanAccount number for regional transfers that identify the bank by IBANprepaidNumberPrepaid card or voucher number for Japan prepaid methods The full required conditions, and the bank values for bankName, are on the lpmsInfo field. Which child fields of billingInformation and shippingInformation are required also varies by method — some methods require the customer's government-issued identityNumber, for example. These requirements come from the payment method provider. Create direct transaction states the condition explicitly for a few methods only — phoneCountryCode is required when lpmsType=MB_WAY, for example — and does not list the rest per method, so verify every method you plan to launch in the sandbox.",{"id":1120,"title":1121,"titles":1122,"content":1123,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#delayed-settlement-and-waiting-states","Delayed settlement and waiting states",[81],"Not every local payment method settles instantly: after the customer receives a payment code, a voucher, or transfer details, they may pay some time later. Bank transfers, virtual accounts, convenience stores, and cash vouchers all work this way, and orders paid with them need the following handling: One order maps to one payment intent: the paymentId and transactionId in the response are one-to-one. The payment can still be retried while the intent stays open (paymentStatus is O in the notification); once it is closed (N) the order can no longer be paid.The payment result webhook is sent only when the transaction reaches a final state; a payment code or voucher shown to the customer does not mean the funds have arrived.An order can stay in a processing state for a long time after the transaction is created, so design a waiting state and decide what happens on timeout; when a payment intent times out and is closed, paymentStatus in the notification is N.Do not treat the synchronous response or the return to your page as proof of settlement, and do not ship on return. If no notification arrives, compensate with Query transactions and read the transaction-level status — that endpoint does not return the payment-intent-level paymentStatus.",{"id":1125,"title":1126,"titles":1127,"content":1128,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#local-payment-method-subscriptions","Local payment method subscriptions",[81],"Subscriptions are supported by a subset of methods — currently DANA, WeChat, GCash, and TOUCH_GO_EWALLET. To check whether a given method supports subscriptions under your own configuration, pass subProductType=SUBSCRIBE when you call List available payment methods. These methods support self-managed subscriptions only (subscription.selfExecute=2) and you initiate the renewal charges. The difference between managed and self-managed subscriptions is covered in Subscription payments. frequencyType accepts only D, but that does not limit you to daily billing: the subscription.frequencyPoint field states the billing cycle in days (for example, you can submit 30 for a monthly subscription or 365 for an annual subscription). This value is informational only; you determine when to initiate renewal charges. A subscription is established in two steps: Subscription authorization: call Create direct transaction with the local payment method scope value in productType, subProductType=SUBSCRIBE, txnType=SALE, lpmsInfo, and the subscription field (requestType=0); the customer authorizes recurring charges in the payment method provider’s own interface, which you present according to actionType. subscription.mode decides how the first charge is collected: the default 2 means Onerway collects it as soon as the customer has authorized, while 1 establishes the authorization only and leaves the first charge to you. The authorization result comes from the saved payment method result webhook (txnType=BIND_CARD, scenarios=SUBSCRIPTION_INITIAL) — persist the contractId and tokenId only when it reports status=S. Submit the real subscription amount in orderAmount, with the line items in txnOrderMsg.products adding up to it; the authorization notification itself returns orderAmount=0.00.Subsequent charges: call Create direct transaction on your own billing schedule with subscription.requestType=1 and the stored contractId, tokenId, and merchantCustId. Under mode=2 the first charge has already been made by Onerway after the authorization, so you start from the second cycle; under mode=1 you make the first charge too. Every charge is reported by the subscription payment webhook (txnType=SALE). Differences from a card subscription: A failed authorization ends the subscription: no subscription payment webhook follows, and subscriptionStatus in the saved payment method result webhook is canceled.Under mode=2, the authorization and the first charge are two notifications. Their transactionId and channelRequestId differ, while merchantTxnId, contractId, and tokenId are the same (paymentId matches too when present, but the first-charge notification may omit it, so do not rely on it as the only matching key). The order in which the two reach your server is not guaranteed, so process both idempotently by their own transactionId.This tokenId is a subscription token. It is only for subscription operations and cannot be used for a subProductType=TOKEN payment, and a local payment method subscription does not return cardTokenId.The subscription payment webhook for the first charge does not return scenarios; the subscription scenario is returned in the saved payment method result webhook instead.",{"id":1130,"title":1131,"titles":1132,"content":1133,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#extra-requirements-of-some-regional-methods","Extra requirements of some regional methods",[81],"The values for stc pay, Tamara, Tabby, and MADA are stcpay, tamara, tabby, and cardpay; you can find each by method name in the value list of the lpmsInfo.lpmsType field. Their extra requirements are not in lpmsInfo but on the product and order information: Product line items must be categorized: submit virtual or physical in the txnOrderMsg.products[].type field, and an HTTPS product image URL in JPG, PNG, or WebP format in the txnOrderMsg.products[].productAvatarUrl field.The txnOrderMsg.customerPlatform field is required: submit the website domain for web transactions or the app name for app transactions.stc pay settlement depends on logistics information: once the transaction has completed successfully and the package has been delivered to and signed for by the customer, call Upload logistics information with the carrier code and tracking number. Virtual-goods transactions and installment transactions are not covered by this settlement prerequisite. Contact Onerway support for the enablement scope of these methods.",{"id":1135,"title":728,"titles":1136,"content":1137,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#go-live-checklist",[81],"Integration methods that build their own method list call List available payment methods before displaying them, and the list is not hard-coded in the front end.All three actionType values under status=R are handled, the return page only receives the customer, and the order result is confirmed from your server or from the notification.The webhook endpoint has passed the Webhooks go-live checklist and can receive the payment result webhook; when you use subscriptions it can also receive the saved payment method result webhook and the subscription payment webhook.Methods that do not settle instantly have a waiting state and a timeout policy, and nothing ships when the customer returns.Every method you are launching has been verified in the sandbox, including customer cancellation mid-flow and the mobile redirect.For local payment method subscriptions, contractId and tokenId are saved only on a successful authorization, stored as strings, and associated with the customer.",{"id":86,"title":90,"titles":1139,"content":1140,"level":609},[],"Saved payment methods, subscriptions, pre-authorization, profit sharing, and refunds explained by business scenario — concepts, lifecycle, and notifications — with the parameter differences across Checkout, Web SDK, and Direct API. This section is organized by business scenario and is independent of the integration method: the guides cover concepts, operations, and result notifications. Scenarios that require configuration when creating a payment also compare the parameters across Checkout, Web SDK, and Direct API. The integration flow of each method is described in Checkout integration, Web SDK integration, and Direct API integration; signature verification, acknowledgement and retries, deduplication, status interpretation, and result queries are covered in Webhooks. For profit share notification URLs, verification, and acknowledgement, see Profit sharing.",{"id":1142,"title":1143,"titles":1144,"content":1145,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios#scenarios-at-a-glance","Scenarios at a glance",[90],"ScenarioTypical businessCheckoutWeb SDKDirect APISaved payment methodsRepeat purchases without re-entering card detailsCustomer opts in to saveCustomer opts in to saveServer-side tokenization, token paymentsSubscription paymentsRecurring charges, automatic or merchant-initiatedInitial subscriptionInitial subscriptionInitial subscription, renewal, plan changesPre-authorization and captureDeposits, reservations, securing funds before shippingPre-authorizationPre-authorizationPre-authorization, capture, voidProfit sharingAllocate funds after a payment in the platform modelConfigure at payment creationConfigure at payment creationConfigure at payment creation After a successful payment, your server requests refunds through the API. The refund guide covers requests, result notifications, queries, and cancellations. Whichever integration method creates the transaction, your server initiates self-managed subscription renewals, managed subscription plan changes, and pre-authorization captures and voids through the Direct API.",{"id":1147,"title":1148,"titles":1149,"content":1150,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios#three-kinds-of-tokens","Three kinds of tokens",[90],"Three kinds of tokens appear in the documentation and are not interchangeable: Card token: the tokenId obtained after the customer opts in to save a card or your server tokenizes one, used for later token payments; see Saved payment methods.Subscription token: the tokenId returned in the subscription payment webhook, paired with contractId for renewals and plan changes; see Subscription payments.Encrypted wallet token: the one-time encrypted payload returned by the Apple Pay or Google Pay SDK. Pass it through unchanged as tokenId in the tokenInfo field and name the wallet token provider in provider so that Onerway decrypts it; it cannot be saved or reused. A subscription that also saves the card produces both a card token and a subscription token; the two token systems must not be mixed.",{"id":93,"title":92,"titles":1152,"content":1153,"level":609},[],"Let customers save a card for repeat purchases — choosing between customer opt-in and server-side tokenization, the tokenization result webhook, listing and deleting saved tokens, and the parameter differences across integration methods. Saving a payment method (tokenization) turns the customer's card into a reusable tokenId, so later payments no longer require card details. With Checkout and the Web SDK, the customer chooses whether to save the card on the Onerway-hosted page; with the Direct API, your server submits the card data to tokenize it.",{"id":1155,"title":1156,"titles":1157,"content":1158,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#concepts-and-choices","Concepts and choices",[92],"Customer opt-in (Checkout, Web SDK): submit a stable merchantCustId when creating the payment, and the Onerway page offers the customer the option to save their card. The option is not selected by default; the card is saved only after the customer opts in and completes the payment. For later payments within the same environment, merchantNo, and appId scope, keep submitting the same merchantCustId, and the page presents the customer's saved cards and completes card selection and payment on its own. Card data never passes through your system, so there is no PCI DSS requirement.Server-side tokenization (Direct API): your server calls Create card token with the card data, then uses the returned tokenId for token payments. Card data passes through your system, so you must hold a valid PCI DSS certification. Both paths produce the same kind of tokenId, but a server-initiated token payment must submit the CVC the customer enters for this purchase in cardInfo.cvv, so it still handles card data and requires PCI DSS. If you are not certified, keep repeat purchases on the Checkout or Web SDK page as well: the page presents the saved cards and completes the payment itself. Your server can verify saved records through List saved tokens but cannot initiate token payments on its own. Generate merchantCustId from a stable server-side customer record rather than an email address, phone number, or other mutable data; never reuse one identifier across customers, and omit it for guests without a durable customer record. Card tokens and subscription tokens belong to different systems; see Scenario overview.",{"id":1160,"title":1161,"titles":1162,"content":1163,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#lifecycle-and-notifications","Lifecycle and notifications",[92],"A successful payment does not mean the card was saved. The saved payment method result webhook (txnType=BIND_CARD) is the final source of truth: store the notified tokenId only when status=S. Neither the return to returnUrl nor the synchronous response means the payment method was saved. Your server can also verify with List saved tokens.Manage saved tokens: List saved tokens returns the id and tokenId of each binding record. When a customer asks to remove a card, call Delete card token with the binding record id — not the tokenId.Token payments may still require 3DS: a server-initiated payment with a saved tokenId can also return status=R; handle the redirect as described in the Direct API integration flow.Subscriptions that also save the card: when a managed card subscription submits subscription.bindCard=true, the tokenization result arrives in a separate saved payment method result webhook whose transactionId differs from the subscription payment webhook; handle each idempotently. See Subscriptions.",{"id":1165,"title":1166,"titles":1167,"content":1168,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#parameters-by-integration-method","Parameters by integration method",[92],"Integration methodEndpointKey parametersDifferencesIntegration guideCheckoutCreate checkout paymentmerchantCustIdThe checkout page presents the save option and saved cards; submit subProductType as DIRECT, SUBSCRIBE, or INSTALLMENT per scenario, with no dedicated value for saving cardsCheckout integrationWeb SDKCreate SDK transactionmerchantCustId, subProductType=DIRECTThe SDK completes card selection and payment internally; the client needs no tokenIdWeb SDK integrationDirect APICreate card token, Create direct transactionTokenization: card data, merchantCustId; card token payment: subProductType=TOKEN, tokenInfo.tokenId, cardInfo.cvv, merchantCustIdTokenization and card token payment are two separate calls, both requiring PCI DSSDirect API integration",{"id":97,"title":96,"titles":1170,"content":1171,"level":609},[],"Choosing between managed and self-managed subscriptions, contract credentials and lifecycle notifications, renewals and plan changes, and the parameter differences across integration methods. A subscription creates a contract with the first payment and charges repeatedly by billing cycle. The initial subscription can be completed through Checkout, the Web SDK, or the Direct API; self-managed renewals and managed plan changes are initiated by your server through the Direct API.",{"id":1173,"title":1156,"titles":1174,"content":1175,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#concepts-and-choices",[96],"The billing model is determined by subscription.selfExecute and chosen at the initial subscription: Managed subscriptions (selfExecute=1): Onerway automatically collects each cycle according to the subscription plan and sends a webhook for every payment. When notificationEmail is configured, Onerway emails the customer subscription confirmations and billing notices, and the customer can self-manage the subscription through the subscriptionManageUrl returned in the response.Self-managed subscriptions (selfExecute=2): you maintain the billing schedule and collect each cycle through Create direct transaction (subscription.requestType=1) using the contractId and tokenId returned by the initial subscription; only frequencyType=D is supported, but that does not limit you to daily billing: the subscription.frequencyPoint field states the billing cycle in days (for example, you can submit 30 for a monthly subscription or 365 for an annual subscription). This value is informational only; you determine when to initiate renewal charges. Whether you make the first charge depends on subscription.mode — under the default 2, Onerway collects it once the customer has authorized. Both cards and wallets can be used for subscriptions, and both billing models apply to Apple Pay and Google Pay. How a wallet subscription is started and how it differs from a card subscription are covered in Apple Pay and Google Pay. A subset of the methods in Local payment methods can also be used for subscriptions, but only as self-managed subscriptions, and the subscription authorization produces a notification of its own. The billing cycle, cycle count or end date, and trial period are all defined in the subscription field; see the API Reference for field definitions. The customer identifier is submitted in the top-level merchantCustId (subscription.merchantCustId is optional and must match when submitted), with the same requirements as in Saved payment methods.",{"id":1177,"title":1161,"titles":1178,"content":1179,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#lifecycle-and-notifications",[96],"Contract credentials: after the initial subscription succeeds, store the contractId and tokenId from the subscription payment webhook; they are the credentials for later billing, queries, and cancellation. This tokenId is a subscription token and must not be mixed with card tokens; see Scenario overview.Lifecycle events: initial purchase, renewal, card replacement, change, cancellation, expiration, and contract status are determined by the scenarios field and the subscriptionStatus field of the subscription payment webhook.Self-managed renewal: your server submits contractId, tokenId, merchantCustId, and the amount for this cycle, with no card data, so renewals carry no PCI DSS requirement. You specify the amount for each cycle; it is not constrained by the initial subscription amount. A successful charge produces a webhook with scenarios=SUBSCRIPTION_RENEWAL; reconciling with Onerway is your responsibility.Managed renewal: Onerway charges the amount of the plan in effect, which is the initial subscription amount until you change the plan. An individual automatic charge cannot be adjusted; to change future amounts, update the plan as described below.Managed plan changes: initiated with the stored contractId and tokenId (requestType=2); when the change takes effect is controlled by subscription.changeMode. A successful update produces a webhook with scenarios=SUBSCRIPTION_CHANGED. Once the change takes effect, Onerway continues automatic billing at the new plan amount.\nchangeMode=1, apply immediately: Onerway prorates by the remaining days of the current cycle (prorationMode=1, the default), or you calculate the prorated amount and submit it in proration (prorationMode=0). Upgrades charge the difference immediately; for downgrades, refund any difference owed to the customer through Create or cancel refund.changeMode=2, apply from the next billing cycle: no immediate charge, suitable for price increases that require advance notice.Subscriptions that also save the card: when a managed card subscription submits subscription.bindCard=true, two transactions and two separate notifications are created: the saved payment method result webhook (txnType=BIND_CARD) returns the card token usable for later token payments, and the subscription payment webhook (txnType=SALE) returns the subscription-side contractId and tokenId. The two notifications carry different transactionId values and must be handled idempotently on their own.Query and cancel: see Query subscription details and Cancel subscription contract.",{"id":1181,"title":1182,"titles":1183,"content":1184,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#failed-payments-and-retries","Failed payments and retries",[96],"For self-managed subscriptions (selfExecute=2), you decide whether, how many times, and how often to retry, and submit each retry as a renewal charge (requestType=1) through the Direct API. For managed subscriptions (selfExecute=1), Onerway retries automatically: at most 3 attempts per cycle, including the initial charge, so up to 2 retries. The interval depends on the billing cycle: Billing cycleRetry intervalDaily1 hourEvery 2–3 days12 hoursLonger than 3 days24 hours While retries are pending, subscriptionStatus is pastdue; if all 3 attempts fail, it becomes paused while the contract stays enabled (dataStatus=1). Both fields are returned by the subscription payment webhook and Query subscription details. Payment retries are separate from webhook redelivery; see Acknowledge and retries.",{"id":1186,"title":1187,"titles":1188,"content":1189,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#replacing-the-subscription-card","Replacing the subscription card",[96],"Only managed subscriptions (selfExecute=1) support card replacement, and only by the customer on the subscription management page at subscriptionManageUrl; there is no API for it. The result is reported by the subscription payment webhook with scenarios=SUBSCRIPTION_CARD_REPLACEMENT.",{"id":1191,"title":1166,"titles":1192,"content":1193,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#parameters-by-integration-method",[96],"Integration methodEndpointKey parametersDifferencesIntegration guideCheckoutCreate checkout paymentsubProductType=SUBSCRIBE, subscription (requestType=0)Initial subscription only; a top-level merchantCustId, if submitted, must match subscription.merchantCustIdCheckout integrationWeb SDKCreate SDK transactionsubProductType=SUBSCRIBE, subscription (requestType=0)Initial subscription only; keep the allowed plan mapping on your serverWeb SDK integrationDirect APICreate direct transactionsubProductType=SUBSCRIBE, subscription.requestTypeInitial subscription, renewal, and plan changes all use this endpoint, distinguished by requestType 0 \u002F 1 \u002F 2Direct API integration",{"id":101,"title":100,"titles":1195,"content":1196,"level":609},[],"Hold funds first and capture on fulfillment — scope of pre-authorization, the lifecycle and notifications from authorization to capture or void, boundaries and status handling, and the parameter differences across integration methods. A pre-authorization holds the order amount on the cardholder's card without charging it immediately. Use it for hotel and car rental deposits, reservations, or securing funds before shipping — any business that needs to secure funds first and charge based on fulfillment later. The pre-authorization can be created through any integration method; capture or void is initiated by your server through the API.",{"id":1198,"title":1156,"titles":1199,"content":1200,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#concepts-and-choices",[100],"Scope: txnType=AUTH applies to direct card payment and token payment (subProductType=DIRECT or TOKEN); it does not apply to local payment method, subscription, or installment transactions.Full capture only: to charge less, void first and create a new transaction, or capture and then refund the difference through Create or cancel refund.Capture or void, not both: only one of the two can be performed on a pre-authorization.",{"id":1202,"title":1161,"titles":1203,"content":1204,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#lifecycle-and-notifications",[100],"Create the pre-authorizationCreate the transaction through the method you use with txnType=AUTH; the remaining parameters are the same as an ordinary payment. When 3DS is required, handle the redirect as described in that method's integration flow.Confirm the authorizationConfirm authorization success when you receive an authorization, capture, and void webhook with txnType=AUTH, status=S, and paymentStatus=A. Store both transactionId and paymentId from the response or notification: the former becomes originTransactionId when you capture or void, and the latter associates the authorization and its later capture or void with the same payment intent.Capture or voidCall Capture or void authorization with originTransactionId set to the pre-authorization's transactionId. txnType=CAPTURE charges the full held amount; txnType=VOID releases the hold without charging.Confirm the final resultA successful capture produces a webhook with txnType=CAPTURE, status=S, and paymentStatus=S; a successful void produces a webhook with txnType=VOID, status=S, and paymentStatus=N. The transactionId belongs to the capture or void operation and differs from the original authorization. Handle each operation idempotently by its own transactionId, and associate them with the same payment intent through paymentId. Boundaries and status handling: VOID applies only to an uncaptured pre-authorization: it releases the held amount and moves no funds. Money from a captured transaction can only be returned through a refund.Different merchantTxnId values in capture or void requests are treated as different transactions; guard against repeated captures of the same originTransactionId on your side.Decide whether the funds are held, captured, or released from paymentId plus paymentStatus (A after a successful AUTH, S after a successful CAPTURE, and N after a successful VOID), not by combining the status values of several notifications; see Webhooks for the distinction between status and paymentStatus.",{"id":1206,"title":1166,"titles":1207,"content":1208,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#parameters-by-integration-method",[100],"Integration methodEndpointKey parametersDifferencesIntegration guideCheckoutCreate checkout paymenttxnType=AUTH3DS is guided by the checkout pageCheckout integrationWeb SDKCreate SDK transactiontxnType=AUTH, subProductType=DIRECTThe SDK integration flow is the same as an ordinary paymentWeb SDK integrationDirect APICreate direct transactiontxnType=AUTH, subProductType=DIRECT or TOKENHandle the status=R redirect yourself when 3DS is requiredDirect API integration",{"id":105,"title":104,"titles":1210,"content":1211,"level":609},[],"Choose automatic or API-initiated profit sharing, configure result notifications, and associate profit shares and reversals with the original payment. Profit sharing is a platform-model capability that allocates funds after a payment completes. Whether you are a platform merchant is determined by the cooperation model agreed when your merchant number is issued; ordinary merchants do not use profit sharing. The platform merchant typically initiates profit sharing on behalf of the sub-merchant that received the payment. Automatic profit sharing allocates funds to the platform merchant; for API-initiated profit sharing, you specify the recipients and amounts in receivers. Use the receiving sub-merchant's merchantNo when creating the payment, and the same merchant number for subsequent API profit share requests and queries.",{"id":1213,"title":1156,"titles":1214,"content":1215,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#concepts-and-choices",[104],"You must set profitShare=true in paymentMethodOptions.share when creating the payment; only then is the payment eligible for profit sharing. Checkout, Web SDK, and Direct API all use this configuration. MethodConfiguration when creating the paymentAfter the payment succeedsAutomatic profit sharingSet both profitShare=true and profitShareRateOnerway automatically allocates the specified percentage to the platform merchant after a successful SALE or CAPTURE; each original payment produces one automatic profit share recordAPI-initiated profit sharingSet profitShare=true without profitShareRateYour server calls the profit sharing API to specify recipients and amounts profitShareRate is a whole-number percentage from 1 to 100, submitted as a string: \"10\" means 10%. Decimals, 0, negative values, and values above 100 are rejected. When a payment with automatic profit sharing is refunded or charged back, Onerway returns the allocated portion at the same percentage. Setting only profitShare=true or a notification URL does not trigger automatic profit sharing. You must also set profitShareRate for automatic profit sharing. See the API Reference for each integration method for field requirements and complete request examples.",{"id":1217,"title":1161,"titles":1218,"content":1219,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#lifecycle-and-notifications",[104],"Create the payment and configure notificationsConfigure paymentMethodOptions.share for your chosen method. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Without this URL, no automatic notification is sent.The notification URL must use HTTPS and be submitted with profitShare=true. A CAPTURE transaction inherits the URL from its original AUTH transaction. Submit paymentMethodOptions as a JSON string as required by the API; complete examples are available in the references for each integration method below.Confirm the payment succeededConfirm the payment result using your integration method, and store the original transactionId, merchant order number, and receiving merchant number. See Webhooks for payment result handling. Profit sharing uses the separate Profit share result webhook.Use automatic profit sharing or call the profit sharing APIFor automatic profit sharing, Onerway allocates funds after a successful SALE or CAPTURE; you do not need to call the profit sharing API. Onerway generates the profitReference for automatic profit shares and reversals.To initiate a profit share through the API, call Create or reverse profit share with profitType=share. Set gatewayReference to the original payment's transactionId. Supply a globally unique profitReference for this request, submit the profit share currency in currency, and specify recipient merchant numbers, purpose codes, and amounts in receivers, serialized as a JSON string as required by the API.profitCompleted is required when profitType=share. It indicates whether this request completes profit sharing for the payment. Submit false while further profit shares are expected. Once you submit true, further profit share requests for that payment are rejected. See the field descriptions for the complete API requirements.API-initiated profit shares and reversals use urlCallback for result notifications. You can omit it when the original payment already has profitShareNotifyUrl. Otherwise, you must provide urlCallback in the API request.Process the profit share resultStore profitReference and the profitGatewayReference returned by Onerway for later queries and reversals. Associate a notification with the original payment using relatedTxnId and relatedMerchantTxnId; these fields are strings and can be null. You can also match an existing profit share record using its request reference and Onerway order number.Verify profit share and reversal notifications using the sign field in the notification body; see Profit share and reversal signature verification. Use the raw receivers string as received when calculating the signature; do not parse and re-serialize it. Return HTTP 200 after receiving and accepting the notification. The response body can be empty.state=completed means processing has finished, not that every detail succeeded. Check each receivers[].result. Use failReason to investigate failures, but do not determine the result by matching its text.",{"id":1221,"title":1222,"titles":1223,"content":1224,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#query-a-profit-share-result","Query a profit share result",[104],"If no notification arrives or you need to check a result, call Query profit share. Use the original payment's receiving merchant number and select profit shares or reversals with profitType=share or return. Provide at least one of profitReference, gatewayReference, profitGatewayReference, relatedTxnId, or relatedMerchantTxnId. Multiple identifiers are applied together as filters. You can query by the original payment's relatedTxnId or relatedMerchantTxnId, or use a stored profit share request reference or Onerway order number. See the API Reference for the query fields, requirements, and examples. The meaning of gatewayReference in a query depends on the order type: for share, it is the original SALE payment's transactionId; for return, it is the Onerway order number of the profit share being reversed. Use relatedTxnId to query a reversal by its original payment. We recommend using strings for merchant numbers and transaction IDs in query requests to avoid numeric precision loss. Query responses include data.sign, but merchants do not need to verify query response signatures. This does not change the requirement to verify profit share webhooks.",{"id":1226,"title":1227,"titles":1228,"content":1229,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#reverse-a-profit-share","Reverse a profit share",[104],"To reverse an existing profit share through the API, call Create or reverse profit share with profitType=return: Supply a new, globally unique profitReference for the reversal, and submit the reversal currency in currency.Set profitParentReference to the original profit share reference. For automatic profit shares, Onerway generates this reference; obtain it from a query result or notification.Set profitGatewayReference to the original Onerway profit share order number being reversed.Supply a profitDetailReference that is unique within this reversal's profitReference for each detail.In each detail, set profitDetailParentReference to the original detail reference and profitDetailGatewayReference to the original Onerway detail number. Use the original recipient merchant number. See the API field descriptions for amounts and other requirements.Do not submit gatewayReference when initiating a reversal. This differs from how the field is used when querying reversal results. Confirm the reversal result through notifications or queries and check each detail. Submitting a reversal request does not mean it has succeeded.",{"id":1231,"title":1166,"titles":1232,"content":1233,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#parameters-by-integration-method",[104],"All three integration methods configure paymentMethodOptions.share when creating a payment and follow the same automatic profit sharing rules. Your server calls the profit sharing APIs to initiate a profit share, query a result, or reverse a profit share. Integration methodEndpointKey parametersDifferencesIntegration guideCheckoutCreate checkout paymentpaymentMethodOptions.share: profitShare, profitShareRate, profitShareNotifyUrlNoneCheckout integrationWeb SDKCreate SDK transactionpaymentMethodOptions.share: profitShare, profitShareRate, profitShareNotifyUrlNoneWeb SDK integrationDirect APICreate direct transactionpaymentMethodOptions.share: profitShare, profitShareRate, profitShareNotifyUrlNoneDirect API integration",{"id":109,"title":108,"titles":1235,"content":1236,"level":609},[],"Request a refund, handle refund results and request rejections, and query the outcome or cancel a request before approval. After a successful payment, your server can request a refund through Create or cancel a refund. Use this API whether the original payment was created through Checkout, Web SDK, or Direct API.",{"id":1238,"title":927,"titles":1239,"content":1240,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#before-you-begin",[108],"Refund availability, support for partial or multiple refunds, and the refund request time limit depend on the payment method. Most payment methods support partial and multiple refunds. The total refunded amount must not exceed the original payment amount, and refund amounts use the currency of the original transaction. Save the original payment's Onerway transactionId and confirm that the payment succeeded. Before calling the API, complete Setup and Request signing.",{"id":1242,"title":1243,"titles":1244,"content":1245,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#request-a-refund-and-handle-the-result","Request a refund and handle the result",[108],"Submit the refund requestCall Create or cancel a refund with refundType=0, the original payment transaction ID in originTransactionId, and the amount to refund in refundAmount. See the API reference for all field requirements and a complete request example.You can provide a merchant transaction number for this refund in merchantTxnId for tracking and reconciliation. Onerway generates it if omitted. Duplicate submissions are rejected.Save the refund transaction IDrespCode=20000 means the refund request was accepted, not that the refund succeeded. Save the new refund transaction ID returned in data and link it to the original payment and your refund record. Use it to process notifications, query the refund, or cancel the request.Handle refund notificationsRefund notifications are sent to the notifyUrl from the original payment request. Your server needs to handle two notification types:Refund result webhook: identified by txnType=REFUND. Use the refund's transactionId and status to update the corresponding refund record.Refund request rejection webhook: identified by notifyType=REFUND_AUDIT. Sent only when Onerway rejects the refund request during review.Follow Webhooks for signature verification, acknowledgement, and deduplication. Once a notification reports success (S) or failure (F), update your refund record. No confirming query is needed.",{"id":1247,"title":1248,"titles":1249,"content":1250,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#query-a-refund-when-needed","Query a refund when needed",[108],"Wait for a Webhook to receive the refund result; continuous polling is not required. When you need to check refund progress or reconcile records, call Query refunds. To query a single refund, use its refund transaction ID in transactionId. To query refunds associated with the original payment, use the original payment transaction ID in originTransactionId. If a query result differs from a notification, see Handle differences between query results and Webhooks. Most refunds are credited immediately. Other refunds can take up to 25 days.",{"id":1252,"title":1253,"titles":1254,"content":1255,"level":615},"\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#cancel-a-refund-request","Cancel a refund request",[108],"Submit the cancellation before Onerway approves the refund request. After approval, Onerway submits the request to the payment channel or card issuer. A processing status alone does not mean that the request can still be cancelled. Call Create or cancel a refund with refundType=1 and the refund transaction ID to cancel in originTransactionId. See the API reference for the other required fields and a complete example. A successful cancellation does not trigger a notification. Handle the synchronous response: data in a successful response equals originTransactionId from the request. To check the record, query using that refund transaction ID. When requesting a refund, originTransactionId identifies the original payment. When cancelling a refund request, the same field identifies the refund transaction. These operations use different transaction IDs.",{"id":124,"title":123,"titles":1257,"content":1258,"level":609},[],"Create a checkout payment and obtain the redirectUrl for the Onerway-hosted payment page. Use this endpoint to create a checkout payment and obtain the redirectUrl for the Onerway-hosted payment page.",{"id":128,"title":127,"titles":1260,"content":1261,"level":609},[],"Create a direct API transaction for card, wallet, saved-token, subscription, installment, or local payment method payments. Use this endpoint to create a server-to-server direct API transaction for card, wallet, saved-token, subscription, installment, or local payment method payments.",{"id":132,"title":131,"titles":1263,"content":1264,"level":609},[],"Create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK. Use this endpoint to create an SDK transaction and obtain the paymentId used to initialize the current Onerway Web SDK.",{"id":136,"title":135,"titles":1266,"content":1267,"level":609},[],"Create a card token in a PCI DSS compliant integration and receive the final tokenization result through notifyUrl. Use this endpoint to create a card token in a PCI DSS compliant integration. The synchronous response carries the processing status and any required next action; receive the final tokenization result through notifyUrl.",{"id":140,"title":139,"titles":1269,"content":1270,"level":609},[],"Delete a saved payment method using the binding record ID returned by List saved tokens. Use this endpoint to remove a saved payment method. Pass the binding record ID from data.tokenInfos[].id in List saved tokens as id. This value is different from tokenId, which Create direct transaction uses for later token payments. After the deletion succeeds, the associated token can no longer be used for token payments.",{"id":144,"title":143,"titles":1272,"content":1273,"level":609},[],"Capture a successful pre-authorization or void it to release the reserved amount. Use this endpoint to capture the full amount of a successful pre-authorization or void the authorization to release the reserved amount.",{"id":148,"title":147,"titles":1275,"content":1276,"level":609},[],"Query the payment methods available for the current order context. Use this endpoint before creating a payment when your integration needs to display or filter the payment methods available for the customer's country, currency, amount, platform, and merchant configuration.",{"id":152,"title":151,"titles":1278,"content":1279,"level":609},[],"Query Payment records by payment intent, transaction identifiers, or time range. Use this endpoint to retrieve transaction results at the Payment level, including multiple transaction attempts under the same paymentId.",{"id":156,"title":155,"titles":1281,"content":1282,"level":609},[],"Query refund records by Payment Intent, refund transaction, original transaction, or time range. Query refund records and use paymentId to identify the associated Payment Intent. If no refund notification arrives, query this endpoint as a fallback; see the Refund result webhook and Refund request rejection webhook.",{"id":160,"title":159,"titles":1284,"content":1285,"level":609},[],"List saved payment method or subscription tokens for a merchant customer. Use this endpoint to list saved tokens under a merchant customer. The response returns the binding record ID for deletion and the tokenId for later token payment or subscription operations.",{"id":164,"title":163,"titles":1287,"content":1288,"level":609},[],"Query subscription information by contract ID and retrieve its billing, status, and token details. Use this endpoint to retrieve one subscription contract by contractId, including customer, product, billing-cycle, lifecycle status, and subscription token information.",{"id":168,"title":167,"titles":1290,"content":1291,"level":609},[],"Cancel a subscription contract immediately, at the end of the current billing cycle, or on a specified date. Use this endpoint to cancel an existing subscription contract by contractId and choose when the cancellation takes effect.",{"id":172,"title":171,"titles":1293,"content":1294,"level":609},[],"Query fraud notifications by notification ID, fraud type, original transaction, or creation time range. Use this endpoint to retrieve fraud notifications and link each notification back to the original transaction through originTransactionId.",{"id":176,"title":175,"titles":1296,"content":1297,"level":609},[],"Query chargeback records by chargeback ID, transaction identifiers, or import time range. Use this endpoint to retrieve chargeback records for merchant transactions. Contact Onerway before calling this endpoint because chargeback query access must be enabled first.",{"id":180,"title":179,"titles":1299,"content":1300,"level":609},[],"Query transaction records by merchant transaction IDs, Onerway transaction IDs, or creation time range. Use this endpoint to retrieve transaction records for reconciliation, chargeback handling, and reporting at the transaction-record level.",{"id":184,"title":183,"titles":1302,"content":1303,"level":609},[],"Create a hosted payment link and return its Payment Link ID and checkout URL. Use this endpoint to create a payment link that customers can open to complete payment on an Onerway-hosted checkout page.",{"id":188,"title":187,"titles":1305,"content":1306,"level":609},[],"Query payment links by status, keyword, creation time, and pagination. Use this endpoint to retrieve paginated payment links and their visit, payment, and collected amount statistics.",{"id":192,"title":191,"titles":1308,"content":1309,"level":609},[],"Enable or disable a payment link by Payment Link ID. Use this endpoint to enable or disable an existing payment link by submitting its Payment Link ID and target status.",{"id":196,"title":195,"titles":1311,"content":1312,"level":609},[],"Create a refund request or cancel a submitted refund request for a paid transaction. Use this endpoint to submit a refund request for a successful payment, or cancel a submitted request before Onerway approves it. Refund availability and request time limits depend on the payment method.",{"id":200,"title":199,"titles":1314,"content":1315,"level":609},[],"Upload carrier and tracking information for a payment transaction. Use this endpoint to attach carrier and tracking details to a transaction for settlement confirmation, order tracking, and chargeback handling. For stc pay settlement, upload logistics information only after the physical-goods transaction has completed successfully and the package has been delivered to and signed for by the customer.",{"id":204,"title":203,"titles":1317,"content":1318,"level":609},[],"Download a UTF-8 CSV settlement file by settlement date and settlement currency. Use this endpoint after Onerway has enabled settlement-file download permission for your account. Send the signed request parameters as headers and save successful responses as UTF-8 CSV files.",{"id":208,"title":207,"titles":1320,"content":1321,"level":609},[],"Submit an application to enable the Ethoca alert service for a merchant or agency sub-merchant. Use this endpoint to submit an Ethoca alert-service enrollment application and receive the application ID for later status queries or transitions.",{"id":212,"title":211,"titles":1323,"content":1324,"level":609},[],"Query Ethoca service enrollment records and their current lifecycle status. Use this endpoint to retrieve Ethoca enrollment applications, check whether the alert service is enabled, and review comments for failed or rejected applications.",{"id":216,"title":215,"titles":1326,"content":1327,"level":609},[],"Withdraw an Ethoca application, request service disablement, or resubmit a failed enrollment. Use this endpoint to request an Ethoca enrollment status transition, such as withdrawing a pending application, disabling an enrolled service, or resubmitting after a failed review.",{"id":220,"title":219,"titles":1329,"content":1330,"level":609},[],"Query Ethoca alert records by alert identifier, alert type, time range, billing descriptor, or outcome. Use this endpoint to retrieve Ethoca alerts, match each alert to the original transaction, and check the latest handling outcome and refund status.",{"id":224,"title":223,"titles":1332,"content":1333,"level":609},[],"Submit the handling outcome and refund status for an Ethoca alert. Use this endpoint to report how an Ethoca alert was handled, including the outcome and refund status associated with the alert.",{"id":228,"title":227,"titles":1335,"content":1336,"level":609},[],"Submit an application to enable the Visa Rapid Dispute Resolution service for a merchant or agency sub-merchant. Use this endpoint to submit an RDR enrollment application and receive the application ID for later status queries or transitions.",{"id":232,"title":231,"titles":1338,"content":1339,"level":609},[],"Query RDR service enrollment records and their current lifecycle status. Use this endpoint to retrieve RDR enrollment applications, check whether the service is enabled, and review comments for failed or rejected applications.",{"id":236,"title":235,"titles":1341,"content":1342,"level":609},[],"Submit, withdraw, or resubmit an RDR enrollment application. Use this endpoint to request an RDR enrollment status transition, such as submitting a pending application, withdrawing a pending application, disabling an enrolled service, or resubmitting after a failed review.",{"id":240,"title":239,"titles":1344,"content":1345,"level":609},[],"Query RDR alert cases by case identifier, case type, received time, original transaction details, or handling status. Use this endpoint to retrieve RDR alert cases, match each case to the original transaction, and check the automatic handling rule and status.",{"id":244,"title":243,"titles":1347,"content":1348,"level":609},[],"Share the proceeds of a completed payment, or reverse a previously submitted profit share. Use this endpoint to share the proceeds of a completed payment, or to reverse an existing profit share. The profitType value determines which operation runs.",{"id":248,"title":247,"titles":1350,"content":1351,"level":609},[],"Query the processing result of a profit share or reversal, including per-recipient details. Use this endpoint to retrieve the result of a profit share or reversal, check the overall state, and confirm the outcome of each recipient detail.",{"id":252,"title":251,"titles":1353,"content":1354,"level":609},[],"Update the order amount, billing information, or shipping information of an SDK transaction before the customer confirms payment. Use this endpoint to update the order amount, billing information, or shipping information of an SDK transaction before the customer confirms payment.",{"id":256,"title":255,"titles":1356,"content":1357,"level":609},[],"Obtain an Apple merchant session through Onerway to complete merchant validation for an Apple Pay session when Onerway registers your Apple Pay domains. Use this endpoint in the onvalidatemerchant event to obtain an Apple merchant session through Onerway when Onerway registers your Apple Pay domains. Merchants with their own Apple Developer account request the session from Apple directly with their own Merchant Identity certificate and do not call this endpoint; setup tiers and the session flow are covered in Apple Pay.",{"id":260,"title":259,"titles":1359,"content":1360,"level":609},[],"Check whether a Google Pay token is PAN_ONLY and needs a CVC before creating the direct transaction when you collect the CVC yourself. Use this endpoint to check whether a Google Pay token is PAN_ONLY before creating the direct transaction when you collect the CVC yourself. The standard path, where the Onerway-hosted page collects the CVC, does not call this endpoint; choosing between the two paths is covered in Google Pay.",{"id":268,"title":267,"titles":1362,"content":1363,"level":609},[],"Receive fraud alert payloads with the fraud type, original transaction, chargeback flag, and refund status. Use this webhook to receive fraud alerts and link each alert back to the original transaction through originTransactionId.",{"id":272,"title":271,"titles":1365,"content":1366,"level":609},[],"Receive Ethoca alert payloads with the alert identifier, original transaction, chargeback details, and handling status. Use this webhook to receive Ethoca alert notifications and link each alert back to the original transaction through ethocaId and transactionId.",{"id":276,"title":275,"titles":1368,"content":1369,"level":609},[],"Receive ordinary payment result notifications for successful, failed, timed-out, or canceled payment flows. Use this webhook to receive server-side results for TXN \u002F SALE payment transactions and reconcile each notification through transactionId and paymentId.",{"id":280,"title":279,"titles":1371,"content":1372,"level":609},[],"Receive initial and renewal subscription payment notifications with contract, token, and scenario context. Use this webhook to receive subscription payment results and link each charge to the related contractId, tokenId, and scenarios value.",{"id":284,"title":283,"titles":1374,"content":1375,"level":609},[],"Receive pre-authorization creation, capture, and void notifications and associate them through the same payment intent. Use this webhook to receive AUTH, CAPTURE, and VOID transaction notifications and associate the authorization lifecycle through paymentId.",{"id":288,"title":287,"titles":1377,"content":1378,"level":609},[],"Receive profit share and reversal result notifications with the overall state and per-recipient details. Receive profit share and reversal results, and use relatedTxnId and relatedMerchantTxnId to associate them with the original payment. Automatic notifications use the original payment's paymentMethodOptions.share.profitShareNotifyUrl; without this address, no automatic notification is sent. For API-initiated profit shares and reversals, use urlCallback; it can be omitted if the original payment already has profitShareNotifyUrl configured.",{"id":292,"title":291,"titles":1380,"content":1381,"level":609},[],"Receive the final result notification for saved payment method (binding) transactions, covering standalone and subscription-with-binding flows. Use this webhook to receive the authoritative server-side result of txnType=BIND_CARD saved payment method transactions; store and use the notified tokenId only when status is S.",{"id":296,"title":295,"titles":1383,"content":1384,"level":609},[],"Ethoca enrollment status changes, payload fields, signature verification, and acknowledgement requirements. Receive Ethoca enrollment status changes at the notification URL configured in the merchant portal.",{"id":300,"title":299,"titles":1386,"content":1387,"level":609},[],"RDR enrollment status changes, payload fields, signature verification, and acknowledgement requirements. Receive RDR enrollment status changes at the notification URL configured in the merchant portal.",{"id":304,"title":303,"titles":1389,"content":1390,"level":609},[],"Reports a refund result (txnType=REFUND) to the original transaction’s notifyUrl. Receive refund results at the original transaction’s notifyUrl. Do not use the example to determine whether a field is always returned or can be null. See Webhooks for handling and Create or cancel refund for requests.",{"id":308,"title":307,"titles":1392,"content":1393,"level":609},[],"Sent to the original transaction’s notifyUrl only when Onerway rejects a refund request during review (notifyType=REFUND_AUDIT). Receive a notification at the original transaction’s notifyUrl only when Onerway rejects the refund request during review. Do not use the example to determine whether a field is always returned or can be null. See Webhooks for handling and Create or cancel refund for requests.",{"id":312,"title":311,"titles":1395,"content":1396,"level":609},[],"Reports a chargeback alert and its associated transaction details. Receive chargeback alerts at the configured chargeback alert webhook URL. Return the received predisputeId unchanged to acknowledge the notification.",{"id":316,"title":315,"titles":1398,"content":1399,"level":609},[],"Reports chargeback status changes without retries. Receive chargeback status changes identified by notifyType=CHARGEBACK. Query chargeback records when needed through Query chargebacks.",{"id":320,"title":319,"titles":1401,"content":1402,"level":609},[],"Review Onerway payment response codes, response messages, and recommended troubleshooting actions. Use this page when an API response returns a respCode other than 20000. The table lists the response message, helps you identify the error category, check request parameters, and decide whether to ask the customer to use another card, retry later, or contact Onerway support. respCode=20000 means Onerway processed the request. It does not always mean the payment, refund, subscription, or tokenization result is final. Confirm the final state through the endpoint documentation, asynchronous notifications, and query APIs. Issuer and acquirer declines are often caused by card details, account state, issuer risk checks, or channel availability. Do not blindly retry hard declines, suspected fraud, AML, legal, or regulatory restriction errors.",{"id":1404,"title":1405,"titles":1406,"content":1407,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#code-ranges","Code ranges",[319],"RangeCategoryCount11xxxSystem errors112xxxConfiguration errors1113xxxParameter errors35132xxSubscription errors1614xxxRefund errors1520xxxRisk control errors130xxxValidation errors2140xxxAcquirer errors650xxx3DS errors560xxxIssuer errors8370xxxGeneral errors2",{"id":1409,"title":1410,"titles":1411,"content":1412,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#system-errors-11xxx","System errors (11xxx)",[319],"CodeMessageRecommended action11001System exceptionContact Onerway support",{"id":1414,"title":1415,"titles":1416,"content":1417,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#configuration-errors-12xxx","Configuration errors (12xxx)",[319],"CodeMessageRecommended action12001System configuration declineContact Onerway support12002Merchant ID is disabled or settlement currency is not configuredContact Onerway support12003Card brand\u002F3DS\u002FService is not supportedContact Onerway support12004Merchant Account is disabled or non-existentContact Onerway support12005Invalid transaction ID for SDK initializationCheck if the transaction number used for initializing the SDK is from the server response; Confirm the transaction number has not been tampered; Confirm the ordering interface and SDK environments are consistent12006Subscription payment information verification failedFor Onerway-managed subscriptions (selfExecute=1) only: make sure the subscription payment time matches the configured frequency12007Incorrect transaction IDCheck merchantNo12008Invalid transaction IPCheck transactionIp in the request12009Request channel timed outRetry later12010Configuration error prevents the request from being processedContact Onerway support and confirm the transaction type is enabled120113DS\u002FAPI request initialization failedContact Onerway support",{"id":1419,"title":1420,"titles":1421,"content":1422,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#parameter-errors-13xxx","Parameter errors (13xxx)",[319],"CodeMessageRecommended action13001Invalid appIdContact Onerway support13002Invalid card numberCheck the card number and retry13003Invalid transaction URLCheck whether the requested domain matches the registered domain; Contact Onerway support13004Expired cardCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card13005Year must be 2 or 4 digitsCheck the card details and retry; Ask the customer to use another card13006Invalid state, please fill in the correct state when the country is US, CA or CN.Check state in the request (required for US, CA, CN)13007Incorrect card informationCheck the card details and retry13008Repeat transaction rejectedCheck whether the transaction already succeeded13009Card number is requiredCheck the card number and retry13010Unsupported card brand: MAESTROCheck card brand configuration13011Decline - Invalid account numberAsk the customer to contact the issuer; Ask the customer to use another card13012billingAddress.city is longer than 30 charactersCheck billingAddress.city in the request13013mpiInfo is required when risk3dsStrategy is EXTERNALCheck mpiInfo in the request13014Invalid transaction typeCheck txnType in the request13015merchantCustId is required for subscriptionCheck merchantCustId in the request13016Subscription contract parameters are requiredCheck subscription in the request13017Billing information, email, and country are requiredCheck billingInformation (email, country)13018Invalid productTypeCheck productType in the request13019Invalid product information formatCheck txnOrderMsg (product)13020Invalid subscription frequencyCheck subscription (frequencyType, frequencyPoint)13021Transaction query time range cannot exceed 90 daysCheck startTime and endTime13022Unsupported currencyCheck country and currency consistency13023Subscription contract unavailableCheck subscription status13024contractId or tokenId is required for subscription paymentCheck contractId and tokenId13025Card year\u002Fmonth is invalidCheck year and month13026Invalid subProductTypeCheck subProductType13027Duplicate order transactionCheck if the request has already been successful13028Query condition is requiredCheck merchantTxnIds, transactionIds, startTime, endTime13029Subscription contract expiredCheck whether the subscription has expired13030Invalid transaction amountCheck amount13031PAN-only card does not support 3DSChange to a card that supports 3DS13032Order has already been captured or canceledCheck whether the order has already been captured or canceled13033Parameters have already been used for the first subscription purchaseCheck whether the same buyer already subscribed with the same card13034Invalid card verification code lengthCheck the card verification code length13035Refund amount is too smallRefund amount must be greater than 0",{"id":1424,"title":1425,"titles":1426,"content":1427,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#subscription-errors-132xx","Subscription errors (132xx)",[319],"CodeMessageRecommended action13200Invalid self-execute settingCheck \"Self execute\" setting13201Invalid emailCheck email13202Invalid cycle countCheck \"Cycle count\"13203Invalid trial-from-plan settingCheck \"Trial from plan\"13204Invalid trial days or trial endCheck \"Trial days\" or \"trial end\"13205Invalid products informationCheck \"Products information\"13206Invalid proration settingCheck \"Proration\"13207Invalid billing cycle anchorCheck \"Billing cycle anchor\"13208Invalid frequency typeCheck \"frequency type\"13209Invalid subscription request typeCheck \"subscription request type\"13210Invalid subscription periodCheck \"subscription period\"13211Invalid subscription frequencyCheck \"subscription frequency\"13212Invalid merchant customer numberCheck \"Merchant customer number\"13213Invalid contract number or tokenCheck \"contract number\" or \"token\"13214Subscription validity is earlier than the current timeCheck \"Subscription validity\"13215Invalid contract informationCheck \"contract information\"",{"id":1429,"title":1430,"titles":1431,"content":1432,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#refund-errors-14xxx","Refund errors (14xxx)",[319],"CodeMessageRecommended action14001Refund failedCheck the transaction status14002Real-time refund is not supportedRetry later14003Cumulative refund amount exceeds the transaction amountCheck the current and cumulative refund amounts14004Refund has already been processed and cannot be canceledCheck the refund status before canceling14005Online refunds not supportedProcess the refund manually through an offline channel14006Real-time refund not supportedUse delayed refund processing14007Refund not supported for this payment methodProcess the refund manually through another channel14008System automatic refund in progressWait for the automatic refund to complete14009Only full refund allowed for chargeback transactionsSubmit a full refund instead of a partial refund14010Refund must use designated interfaceSend the refund request to the designated interface14011Online refund failed because orders are pending or rejectedResolve pending or rejected orders first14012Insufficient payout account balanceMake sure the payout account has sufficient funds14013Transaction does not support refund initiationContact Onerway support14014Chargeback already exists, refund not supportedDo not refund again; the amount has already been returned through the bank or card issuer14015Original transaction was not successfulVerify the original transaction status before refunding",{"id":1434,"title":1435,"titles":1436,"content":1437,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#risk-control-errors-20xxx","Risk control errors (20xxx)",[319],"CodeMessageRecommended action20001High riskConfirm the customer identity; retry after 24 hours or contact Onerway support",{"id":1439,"title":1440,"titles":1441,"content":1442,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#validation-errors-30xxx","Validation errors (30xxx)",[319],"CodeMessageRecommended action30001Invalid IP addressCheck ip in the request30002Invalid birthDateCheck birthDate30003Invalid productCheck product30004Invalid merchantCustIdCheck merchantCustId30005Invalid productTypeCheck productType30006Invalid appIdCheck appId30007Invalid numberCheck the card number and retry30008Invalid card verification codeCheck the card verification code and retry30009Invalid pinAsk the customer to contact the issuer; Ask the customer to use another card30010Invalid expiry month or yearCheck the expiry date and retry; Ask the customer to use another card30011Invalid cardholder nameCheck the cardholder name and retry30012Invalid countryCheck country30013Invalid stateCheck state30014Invalid cityCheck city30015Invalid addressCheck address30016Invalid emailCheck email30017Invalid postalCodeCheck postalCode30018Invalid phoneCheck phone30019Invalid accountAsk the customer to contact the issuer; Ask the customer to use another card30020Invalid parametersCheck the API documentation and request parameters30021Invalid transaction URLContact Onerway support to review and approve the website",{"id":1444,"title":1445,"titles":1446,"content":1447,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#acquirer-errors-40xxx","Acquirer errors (40xxx)",[319],"CodeMessageRecommended action40000Illegal parameter {field}Check the field value, format, and dependencies against the endpoint reference; message names the offending field40001Acquirer suspected fraudConfirm the customer identity and retry with another card40002Acquirer system failureRetry later; Ask the customer to use another card; Contact Onerway support40003Acquirer declineRetry later; Ask the customer to use another card40004Acquirer timeoutRetry later40005Missing or invalid acquirer parametersContact Onerway support",{"id":1449,"title":1450,"titles":1451,"content":1452,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#_3ds-errors-50xxx","3DS errors (50xxx)",[319],"CodeMessageRecommended action500013DS authentication requiredRetry and complete 3DS authentication; Ask the customer to use another card500023DS parameters errorRetry and complete 3DS authentication; Ask the customer to use another card500033DS authentication failureRetry and complete 3DS authentication; Ask the customer to use another card500043DS system errorRetry and complete 3DS authentication; Ask the customer to use another card50030Order canceledConfirm the order state before retrying",{"id":1454,"title":1455,"titles":1456,"content":1457,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#issuer-errors-60xxx","Issuer errors (60xxx)",[319],"CodeMessageRecommended action60001Refer to card issuerCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60002Refer to card issuer, special conditionCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60003Invalid merchantContact Onerway support60004Pick up card (no fraud)\u002FCapture cardAsk the customer to contact the issuer or use another card60005Do not honorCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60006Issuer processing errorRetry later or ask the customer to use another card60007Pick up card, special condition (fraud account)Ask the customer to contact the issuer or use another card60012Invalid transactionCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60013Invalid amount or Currency conversion field overflowCheck transaction amount or currency; Contact Onerway support60014Invalid account numberCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60015Invalid issuerCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60019Re-enter transactionCheck for format errors; Check address information60021No action takenAsk the customer to contact the issuer; Ask the customer to use another card60025Unable to locate record in fileCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60028File temporarily not available for update or inquiryRetry the transaction60030Format errorCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60039No credit accountCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60041Lost card, pick up card (fraud account)Ask the customer to contact the issuer or use another card60043Stolen card, pick up (fraud account)Ask the customer to contact the issuer or use another card60046Closed accountCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60051Insufficient funds\u002Fover credit limitRefer to card issuer to confirm credit limit; Ask the customer to use another card60052No checking accountCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60053No savings accountCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60054Expired card or expiration date missingCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60055PIN incorrect or missing\u002FInvalid PINAsk the customer to contact the issuer or use another card60057Transaction not permitted to issuer\u002FcardholderAsk the customer to contact the issuer or use another card60058Transaction not permitted to acquirer\u002FterminalAsk the customer to contact the issuer or use another card60059Suspected fraudCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60061Exceeds approval amount limitAsk the customer to contact the issuer or use another card60062Restricted card (card invalid in region or country)\u002FRestricted cardAsk the customer to contact the issuer or use another card60063Security violation (source is not correct issuer)\u002FSecurity violationCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60064Transaction does not fulfill AML requirementDo not retry; review the transaction risk60065Exceeds withdrawal frequency limitAsk the customer to contact the issuer; Ask the customer to use another card; Contact Onerway support60070PIN data required or contact card issuerAsk the customer to contact the issuer or use another card60071PIN Not ChangedAsk the customer to contact the issuer or use another card60074Different value than that used for PIN encryption errorsAsk the customer to contact the issuer or use another card60075Allowable number of PIN entry tries exceededAsk the customer to contact the issuer or use another card60076Invalid or unsolicited reversal account informationAsk the customer to contact the issuer or use another card60077Invalid\u002Fnonexistent \"From Account\" specifiedAsk the customer to contact the issuer or use another card60078Blocked card or invalid accountContact card issuer to confirm activation; Ask the customer to use another card60079Reversed or card life-cycle restrictionCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60080No financial impact or issuer system unavailableCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60081PIN cryptographic error or domestic debit not allowedCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60082Card authentication value failed or issuer policy declineCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60083Fraud\u002FSecurity (Mastercard use only)Check the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60084Invalid Authorization Life CycleCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60086PIN verification is not possibleRetry on the same day; Try a non-PIN transaction if applicable60087Purchase Amount Only, No Cash Back AllowedCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60088Cryptographic failureCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60089Financial position information is not available or PIN retry requiredCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60090Cutoff is in progressAsk the customer to contact the issuer or use another card60091Issuer or authorization system unavailableRetry in 24 hours; Ask the customer to contact the issuer; Ask the customer to use another card60092Unable to route transactionContact Onerway support60093Transaction violates legal or regulatory requirementsAsk the customer to contact the issuer; do not retry60094Duplication transaction detectedCheck whether the transaction already succeeded60096System malfunctionCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card60100Exceeds authentication frequency limitAsk the customer to contact the issuer; Ask the customer to use another card; Contact Onerway support60101CancelledAsk the customer to contact the issuer; Ask the customer to use another card; Contact Onerway support60102Duplicate transactionCheck whether the transaction already succeeded60103Soft declineAsk the customer to use another card or complete a 3DS challenge60104Hard declineDo not retry60105Refund failedContact Onerway support60106Customer did not pay before the order timed outAsk the customer to complete payment before the order expires60129Suspected Counterfeit CardAsk the customer to contact the issuer; Ask the customer to use another card6001AAdditional customer authentication requiredAsk the customer to use another card or complete 3DS authentication6001ZAuthorization system inoperativeAsk the customer to contact the issuer or use another card6006PVerification data failedCheck the card details and retry; Complete 3DS authentication; Ask the customer to use another card600B1Surcharge amount not permitted on Visa cards or EBT food stamps (U.S. acquirers only)Ask the customer to use another card600B2Surcharge amount not supported by debit network issuer.Ask the customer to use another card600N0Issuer forces stand-in processingCheck the card details and retry; Complete 3DS authentication; Ask the customer to use another card600N3Cash service not availableAsk the customer to contact the issuer; Retry later; Change the amount; Ask the customer to use another card600N4Cash request exceeds issuer or approved limitAsk the customer to contact the issuer; Change the amount; Ask the customer to use another card600N5Ineligible for resubmissionAsk the customer to contact the issuer; Ask the customer to use another card600N7Decline for card verification code failureCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card600N8Transaction amount exceeds preauthorized approval amountMake sure the capture amount does not exceed the authorized amount600P5Denied PIN unblock—PIN change or unblock request declined by issuerAsk the customer to contact the issuer or use another card600P6Denied PIN change—requested PIN unsafeAsk the customer to contact the issuer or use another card600Q1Card Authentication failedCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card600R0Stop this paymentDo not retry; contact Onerway support600R1Stop all future paymentsDo not retry; contact Onerway support600R2Transaction does not qualify for Visa PINAsk the customer to contact the issuer or use another card600R3Stop all merchantsDo not retry; contact Onerway support600Z3Unable to go online; offline declinedCheck the card details and retry; Ask the customer to contact the issuer; Ask the customer to use another card",{"id":1459,"title":1460,"titles":1461,"content":1462,"level":615},"\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#general-errors-70xxx","General errors (70xxx)",[319],"CodeMessageRecommended action70001Common declineContact Onerway support70002Unknown declineContact Onerway support",{"id":328,"title":332,"titles":1464,"content":1465,"level":609},[],"Cross-border fund transfer and payout services. Before calling the Transfer API, complete sandbox onboarding, whitelist setup, and merchant credential preparation. It is recommended that you prepare the environment and merchant information first, and then proceed to request signing and the integration flow.",{"id":1467,"title":332,"titles":1468,"content":1469,"level":615},"\u002Ftransfer\u002Fget-started#overview",[332],"The main difference between the Sandbox and Production environments is the request domain. It is recommended that you complete integration testing in the Sandbox environment before switching to Production. Setup mainly includes the following items: Provide the onboarding emailProvide the test integration domainWait for the activation emailLog in to the merchant portal to obtain merchant credentialsComplete whitelist and follow-up configuration",{"id":1471,"title":1472,"titles":1473,"content":1474,"level":615},"\u002Ftransfer\u002Fget-started#environment-description","Environment Description",[332],"The request URLs for the Production and Sandbox environments differ only in domain names. In practice, the integration process is usually: Complete integration testing in the Sandbox environmentVerify signing and payout flowSwitch to the Production domain and Production configuration This helps expose issues in the test environment first, instead of mixing environment issues with business issues during production cutover.",{"id":1476,"title":1477,"titles":1478,"content":1479,"level":615},"\u002Ftransfer\u002Fget-started#environment-domains","Environment Domains",[332],"EnvironmentDomainSandboxhttps:\u002F\u002Fsandbox-api.onerway.com\u002FpayoutProductionhttps:\u002F\u002Fapi.onerway.com\u002Fpayout",{"id":1481,"title":1482,"titles":1483,"content":1484,"level":615},"\u002Ftransfer\u002Fget-started#merchant-onboarding-and-whitelist","Merchant Onboarding and Whitelist",[332],"Before creating a sandbox test merchant, please prepare: Onboarding emailDomain used for test integration The onboarding email is used to create the sandbox account. The submitted domain will be added to the whitelist, and only whitelisted domains can call the Onerway API. This means that during setup, in addition to “whether an account exists,” you should also confirm: Whether the domain has been submittedWhether the domain has been added to the whitelistWhether the actual request origin matches the whitelist configuration If the domain has not completed whitelist configuration, the API may still fail even if the request payload itself is correct.",{"id":1486,"title":1487,"titles":1488,"content":1489,"level":615},"\u002Ftransfer\u002Fget-started#merchant-credentials","Merchant Credentials",[332],"After receiving the activation email, log in through the merchant portal link in the email. On first login, you need to reset the password and then obtain the merchant credentials. In Transfer, use the actual request field name merchantNo. You will typically need to prepare: merchantNoThe key or private key corresponding to the signing method Transfer documentation consistently uses merchantNo. Do not replace it with merchantId.",{"id":1491,"title":1492,"titles":1493,"content":1494,"level":615},"\u002Ftransfer\u002Fget-started#required-field-markers","Required Field Markers",[332],"Field tables use the following markers: MarkerMeaningMRequiredCConditionally requiredNOptional",{"id":1496,"title":1497,"titles":1498,"content":1499,"level":615},"\u002Ftransfer\u002Fget-started#pre-integration-checklist","Pre-Integration Checklist",[332],"Before you start building request payloads, creating beneficiaries, or initiating payouts, confirm that: The sandbox account has been activatedThe integration domain has been added to the whitelistMerchant credentials have been obtained from the merchant portalThe signing method has been confirmedRequired fields for the target country, currency, payout method, and entity type have been confirmed After completing this preparation, the next steps are usually: Request signing preparationIntegration flow confirmationSandbox testing and go-live preparation",{"id":334,"title":24,"titles":1501,"content":1502,"level":609},[],"Learn the two Transfer API signing methods and their examples. Transfer APIs provide two signing methods: SHA256withRSA and SHA256. Use the method assigned to your merchant by Onerway.",{"id":1504,"title":1505,"titles":1506,"content":1507,"level":615},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#before-you-start","Before you start",[24],"Confirm your merchant's signing method first. The signing key type, canonical string rule, and generated signature format differ between the two methods.",{"id":1509,"title":1510,"titles":1511,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#sha256withrsa","SHA256withRSA",[24],{"id":1513,"title":1514,"titles":1515,"content":1516,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#signing-steps","Signing steps",[24,1510],"Obtain the privateKeyUse the SHA256withRSA algorithmConvert the canonical string into UTF-8Generate the signatureBase64-encode the signature result",{"id":1518,"title":1519,"titles":1520,"content":1521,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#canonical-string-rule","Canonical string rule",[24,1510],"Remove all parameters whose values are empty, sort the remaining parameters by ASCII order of the parameter name, and concatenate them in the format key=value&key1=value1.... Do not append & after the last parameter.",{"id":1523,"title":1524,"titles":1525,"content":1526,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-private-key","Example private key",[24,1510],"MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDHaM7clWWlJNS6\nZR5ZkxSFeMMFt74YGRmYPr67UHrfc4CzFtN9sctIUqZJVv05sfOgnb0rk1G7wx97\n\u002FLqxPEGs5chc+Nq9HkNf5VopMifOQ85j1Sv1U031oEGk+Oi4MTAR4ZWlLKBQPyKV\nb5pCP8aIv15GTIiIwJKS17zY5mQUrXzASTDk54DCG9eN4Lgka9xzwRvaYZvmxLg7\n32GxjI5TE797kA5gxY7GxZ0wxdkWkhcee6xX6WWhAcmdHPUUS0EPcnL5wcc3wP07\nvO+R\u002FjO1XoaXczb6JRh6ApR3Y5VjSFQApqwe7AIgASGf8aSkBU4K95RfZ3QsBjof\n2SX\u002F3fkf",{"id":1528,"title":1529,"titles":1530,"content":1531,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-request-data","Example request data",[24,1510],"{\n \"key\": \"value\",\n \"key2\": \"value2\",\n \"key1\": \"value2\",\n \"sign\": \"RcqXuiVp1JpwJedRGzTpL8M5mUsfeHL29gV9ycaJwmDoNV21AiaQ41au2qiJ8h+jKn\u002FKBMcrJAzHGBTO3CZ0ffGxmqNz9fKhZX+X1MTntH+MhtKTyKR4ZF8kbAtezdVgPfqT69NPQGbWo57R3KP0m4W4n2ZjgkxkcG3yYtBdAgsyxDNoT8W0wH7nK7Y0zp88O8wIMe7kfBnK59J4y0Xz2EwiFX+bNkfRhf3U5WiHIU2TdRbaYsnzndmOkYkVdFAiUH7zoXnEn8ZVqiDZkK4eFG9H1LxU55dStug1hLtwxOKlu5OYFUi4iGAiq0Vlir01eDR1++KAudOdb1gcUyH2rA==\"\n}",{"id":1533,"title":1534,"titles":1535,"content":1536,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-canonical-string","Example canonical string",[24,1510],"key=value&key1=value2&key2=value2",{"id":1538,"title":1539,"titles":1540,"content":1541,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-signature-result","Example signature result",[24,1510],"RcqXuiVp1JpwJedRGzTpL8M5mUsfeHL29gV9ycaJwmDoNV21AiaQ41au2qiJ8h+jKn\u002FKBMcrJAzHGBTO3CZ0ffGxmqNz9fKhZX+X1MTntH+MhtKTyKR4ZF8kbAtezdVgPfqT69NPQGbWo57R3KP0m4W4n2ZjgkxkcG3yYtBdAgsyxDNoT8W0wH7nK7Y0zp88O8wIMe7kfBnK59J4y0Xz2EwiFX+bNkfRhf3U5WiHIU2TdRbaYsnzndmOkYkVdFAiUH7zoXnEn8ZVqiDZkK4eFG9H1LxU55dStug1hLtwxOKlu5OYFUi4iGAiq0Vlir01eDR1++KAudOdb1gcUyH2rA== \u003Cdependency>\n \u003CgroupId>commons-codec\u003C\u002FgroupId>\n \u003CartifactId>commons-codec\u003C\u002FartifactId>\n \u003Cversion>1.14\u003C\u002Fversion>\n\u003C\u002Fdependency>\npackage xxx;\n\nimport org.apache.commons.codec.binary.Base64;\nimport java.nio.charset.StandardCharsets;\nimport java.security.KeyFactory;\nimport java.security.PrivateKey;\nimport java.security.Signature;\nimport java.security.spec.PKCS8EncodedKeySpec;\n\npublic class RSASecureDemo {\n public static String signRSA(String privateKey, String toBeSignedData) {\n try {\n byte[] keyBytes = Base64.decodeBase64(privateKey);\n PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);\n KeyFactory keyFactory = KeyFactory.getInstance(\"RSA\");\n PrivateKey priKey = keyFactory.generatePrivate(pkcs8KeySpec);\n Signature signature = Signature.getInstance(\"SHA256withRSA\");\n signature.initSign(priKey);\n signature.update(toBeSignedData.getBytes(StandardCharsets.UTF_8));\n return Base64.encodeBase64String(signature.sign());\n } catch (Exception e) {\n throw new RuntimeException(\"rsa sign failed\");\n }\n }\n\n public static void main(String[] args) {\n String privateKey = \"MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDHaM7clWWlJNS6\" +\n \"ZR5ZkxSFeMMFt74YGRmYPr67UHrfc4CzFtN9sctIUqZJVv05sfOgnb0rk1G7wx97\" +\n \"\u002FLqxPEGs5chc+Nq9HkNf5VopMifOQ85j1Sv1U031oEGk+Oi4MTAR4ZWlLKBQPyKV\" +\n \"483\u002FAxmrwea50UKLqRVH3IXzTOEJth0betqTmbefYFLETn5RXB6MOJQOdzpvvcP3\" +\n \"05FmtT\u002FgrqqcnaeLbosT4A==\";\n\n String toBeSignedData = \"key=value&key1=value2&key2=value2\";\n String sign = signRSA(privateKey, toBeSignedData);\n System.out.println(sign);\n }\n}",{"id":1543,"title":1544,"titles":1545,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#sha256","SHA256",[24],{"id":1547,"title":1514,"titles":1548,"content":1549,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#signing-steps-1",[24,1544],"Obtain the secret keyConcatenate the canonical string and the secret key as stringsConvert the result into UTF-8Apply the SHA-256 digestConvert the digest into a hexadecimal string",{"id":1551,"title":1519,"titles":1552,"content":1553,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#canonical-string-rule-1",[24,1544],"Remove all parameters whose signing column is No and parameters whose values are empty. Sort the remaining parameters by ASCII order of the parameter name, concatenate only the parameter values, and then append the secret key.",{"id":1555,"title":1556,"titles":1557,"content":1558,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-secret-key","Example secret key",[24,1544],"3b5e10b65bff4172a5b9ca2d2ec00a6e",{"id":1560,"title":1529,"titles":1561,"content":1562,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-request-data-1",[24,1544],"{\n \"merchantNo\": \"800135\",\n \"test\": \"dsaaass1dsag\",\n \"bizContent\": \"yesdas1dsa\",\n \"as\": \"12334567\",\n \"bc\": \"098754\"\n}",{"id":1564,"title":1534,"titles":1565,"content":1566,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-canonical-string-1",[24,1544],"12334567098754yesdas1dsa800135dsaaass1dsag",{"id":1568,"title":1539,"titles":1569,"content":1570,"level":667},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#example-signature-result-1",[24,1544],"0ce84cc90742e79b3af76da6b6909dc158a2e933057562639fe6a5a8e73f5350 \u003Cdependency>\n \u003CgroupId>org.apache.commons\u003C\u002FgroupId>\n \u003CartifactId>commons-lang3\u003C\u002FartifactId>\n \u003Cversion>3.6\u003C\u002Fversion>\n\u003C\u002Fdependency>\npackage xxx;\n\nimport org.apache.commons.lang3.StringUtils;\nimport java.security.MessageDigest;\nimport java.util.TreeMap;\n\npublic class SHA256SecureDemo {\n public static void main(String[] args) throws Exception {\n TreeMap data = new TreeMap();\n data.put(\"merchantNo\",\"800135\");\n data.put(\"test\",\"yesdas1dsa\");\n data.put(\"bizContent\",\"dsaaass1dsag\");\n data.put(\"as\",\"12334567\");\n data.put(\"bc\",\"098754\");\n\n String toBeSignedData = strcatValueSign(data);\n String key = \"3b5e10b65bff4172a5b9ca2d2ec00a6e\";\n String sign = signSha256(key, toBeSignedData);\n System.out.println(sign);\n }\n\n private static String strcatValueSign(TreeMap treeMap) {\n StringBuffer buffer = new StringBuffer();\n treeMap.forEach((k, v) -> {\n if (StringUtils.isNotBlank((String) v)) {\n buffer.append(v);\n }\n });\n return buffer.toString();\n }\n\n public static String signSha256(String key, String toBeSignedData) {\n String str = toBeSignedData + key;\n String encodestr = \"\";\n try {\n MessageDigest messageDigest = MessageDigest.getInstance(\"SHA-256\");\n messageDigest.update(str.getBytes(\"UTF-8\"));\n encodestr = byte2Hex(messageDigest.digest());\n } catch (Exception e) {\n e.printStackTrace();\n }\n return encodestr;\n }\n\n private static String byte2Hex(byte[] bytes) {\n StringBuffer stringBuffer = new StringBuffer();\n String temp = null;\n for (int i = 0; i \u003C bytes.length; i++) {\n temp = Integer.toHexString(bytes[i] & 0xFF);\n if (temp.length() == 1) {\n stringBuffer.append(\"0\");\n }\n stringBuffer.append(temp);\n }\n return stringBuffer.toString();\n }\n}",{"id":1572,"title":1573,"titles":1574,"content":1575,"level":615},"\u002Ftransfer\u002Fget-started\u002Frequest-signing#next-steps","Next Steps",[24],"SetupIntegration flowTesting and go-live html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}",{"id":338,"title":337,"titles":1577,"content":1578,"level":609},[],"Follow the four-stage Transfer flow from preparation to result closure. Transfer integration can be organized into four stages: preparation, transfer submission, result retrieval, and transaction completion.",{"id":1580,"title":332,"titles":1581,"content":1582,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#overview",[337],"Before you submit a transfer, confirm the beneficiary field requirements first. The required fields vary by country, currency, transfer method, and entity type.",{"id":1584,"title":1585,"titles":1586,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#stage-1-preparation","Stage 1: Preparation",[337],{"id":1588,"title":1589,"titles":1590,"content":1591,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#confirm-beneficiary-field-requirements","Confirm beneficiary field requirements",[337,1585],"Use one of the following methods: Call POST \u002Fapi\u002Fv1\u002Facct\u002FqueryPaymentFeild to retrieve the required fieldsContact your account manager to get the required field template for the target country, currency, transfer method, and entity type",{"id":1593,"title":1594,"titles":1595,"content":1596,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#prepare-beneficiary-information","Prepare beneficiary information",[337,1585],"After you have the field requirements, collect and validate beneficiary information according to the returned or provided template. The key order in this stage is: confirm the supported transfer method for the target country and currencyconfirm the required fields for that methodprepare beneficiary, address, and account information based on that template If the prerequisite fields are not confirmed first, both beneficiary creation and transfer initiation can fail because of missing or invalid data.",{"id":1598,"title":1599,"titles":1600,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#stage-2-submit-the-transfer","Stage 2: Submit the transfer",[337],{"id":1602,"title":1603,"titles":1604,"content":1605,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#decide-which-submission-path-to-use","Decide which submission path to use",[337,1599],"ConditionPathReal-time transfer has been enabled by OnerwayReal-time pathReal-time transfer has not been enabledDefault path if the real-time path has been enabled, you can submit beneficiary information and initiate the transfer in one requestif it has not been enabled, you must maintain the beneficiary first and then initiate the transfer by beneficiaryId",{"id":1607,"title":1608,"titles":1609,"content":874,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#default-path","Default path",[337,1599],{"id":1611,"title":1612,"titles":1613,"content":1614,"level":1615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_1-create-a-beneficiary-id","1. Create a beneficiary ID",[337,1599,1608],"Enter or import beneficiary informationCall POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002FaddStore the returned beneficiaryId This is the starting point of the default path. In other words, the default path is not \"fill and pay immediately\". It first turns beneficiary data into a reusable record.",4,{"id":1617,"title":1618,"titles":1619,"content":1620,"level":1615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_2-beneficiary-reuse-logic","2. Beneficiary reuse logic",[337,1599,1608],"Check whether the existing beneficiaryId can still be reusedIf the information is unchanged, keep using the existing beneficiaryIdIf the beneficiary information is inconsistent, call POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002Fedit first and then continue using the existing beneficiaryId Do not recreate a new beneficiary for every transfer when the existing record is still valid. Reuse first, update only when the information has changed.",{"id":1622,"title":1623,"titles":1624,"content":1625,"level":1615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_3-initiate-the-transfer-request","3. Initiate the transfer request",[337,1599,1608],"Call POST \u002Fapi\u002Fv1\u002Ftxn\u002FremittanceThe transaction enters Onerway transfer processing After this step, the transaction enters processing. A successful synchronous response only means the request has been accepted, not that the final transfer result has been confirmed.",{"id":1627,"title":1628,"titles":1629,"content":1630,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#real-time-path","Real-time path",[337,1599],"Real-time transfer must be enabled by Onerway in advance.",{"id":1632,"title":1633,"titles":1634,"content":1635,"level":1615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_1-submit-beneficiary-information-dynamically","1. Submit beneficiary information dynamically",[337,1599,1628],"Call POST \u002Fapi\u002Fv2\u002Ftxn\u002FremittancePut beneficiary information directly in the request bodyNo pre-created beneficiaryId is required",{"id":1637,"title":1638,"titles":1639,"content":1640,"level":1615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_2-initiate-the-transfer","2. Initiate the transfer",[337,1599,1628],"Submit the requestThe transaction enters transfer processing directly Compared with the default path, the real-time path removes the pre-created beneficiary step. This path has to be enabled in advance and should not be assumed to be available by default.",{"id":1642,"title":1643,"titles":1644,"content":1645,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#stage-3-retrieve-the-result","Stage 3: Retrieve the result",[337],"You can retrieve transfer results in two ways: Active query through POST \u002Fapi\u002Fv1\u002Ftxn\u002FqueryAsynchronous notification through webhook callbacks",{"id":1647,"title":1648,"titles":1649,"content":1650,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#result-retrieval-methods","Result retrieval methods",[337,1643],"Result retrieval is separated into two lines: active query for fallback confirmation, reconciliation, or investigationasynchronous callbacks as the main production result channel",{"id":1652,"title":1653,"titles":1654,"content":1655,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#callback-payload-usually-includes","Callback payload usually includes",[337,1643],"transaction statusfailure code when the transfer failsfailure description when the transfer fails This is why a successful synchronous response is not the end of the workflow.",{"id":1657,"title":1658,"titles":1659,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#stage-4-complete-the-transaction","Stage 4: Complete the transaction",[337],{"id":1661,"title":1662,"titles":1663,"content":1664,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#successful-transfer","Successful transfer",[337,1658],"Call POST \u002Fapi\u002Fv1\u002Ftxn\u002FqueryVoucher to retrieve the voucher",{"id":1666,"title":1667,"titles":1668,"content":1669,"level":667},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#unsuccessful-transfer","Unsuccessful transfer",[337,1658],"Query the failure reasonContinue with manual handling or retry based on your internal process The focus of this stage is straightforward: successful transfers move into voucher retrieval and reconciliationunsuccessful transfers move into retry or manual handling based on the reasonthe transaction flow is only truly closed after the result is confirmed and the follow-up action is completed",{"id":1671,"title":1672,"titles":1673,"content":1674,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#recommended-operating-model","Recommended operating model",[337],"Use this operating model in production: use webhook callbacks as the primary result channelkeep the query APIs for reconciliation, retry handling, and fallback checksreuse existing beneficiary records when the information is still valid",{"id":1676,"title":1677,"titles":1678,"content":1679,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#notes","Notes",[337],"If the real-time path is not enabled, use the default path first instead of submitting a real-time request directlyIn the default path, store beneficiaryId properly to avoid duplicate beneficiary creationEven after a transfer request is accepted, confirm the final status through webhooks or query APIsIf you need proof of payment after success, continue with the voucher API",{"id":1681,"title":1682,"titles":1683,"content":1684,"level":615},"\u002Ftransfer\u002Fget-started\u002Fintegration-flow#continue-reading","Continue Reading",[337],"SetupRequest signingTesting and go-live",{"id":342,"title":341,"titles":1686,"content":1687,"level":609},[],"Validate the Transfer integration in Sandbox and prepare the final production checklist. Complete the full payout lifecycle in Sandbox before switching to Production. Validate environment setup, the four-stage flow, and callback handling before go-live.",{"id":1689,"title":1690,"titles":1691,"content":1692,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#why-complete-validation-in-sandbox-first","Why complete validation in Sandbox first",[341],"Validate at least these baseline capabilities: whether the whitelist and environment domain are correctwhether merchant credentials and signing workwhether beneficiary data can be prepared according to the field templatewhether transfer requests can enter processingwhether final results can be closed through webhooks or query APIs If only part of this flow is tested, it is easy to reach production with requests that can be sent but not fully closed.",{"id":1694,"title":1695,"titles":1696,"content":1697,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#what-to-validate","What to validate",[341],"Request signing works consistentlybeneficiaryId creation, reuse, and query flows behave correctlyWebhook notifications arrive after payout submissionActive queries can recover unresolved ordersSuccessful orders can download vouchers when needed",{"id":1699,"title":1700,"titles":1701,"content":1702,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#additional-checks-worth-including","Additional checks worth including",[341],"Beyond simply proving that the happy path works, it is also worth validating: idempotent handling under repeated notificationsrecovery logic for exceptional stateshow failure reasons are stored and surfaced internallywhether the mapping between payer, beneficiary, and business order IDs is completewhether voucher download, archiving, and later access meet your internal requirements",{"id":1704,"title":1705,"titles":1706,"content":1707,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#recommended-test-sequence","Recommended test sequence",[341],"Verify environment, whitelist, and secret configurationConfirm the payout method for the target country, currency, and entity typeQuery the required fields for that combinationCreate a test beneficiarySubmit a payout via beneficiaryIdReceive the webhook and update the order statusRun active queries for unresolved ordersDownload the voucher for successful orders If your business will use both the beneficiaryId flow and the direct beneficiary-details flow, test both paths separately instead of validating only one.",{"id":1709,"title":1710,"titles":1711,"content":1712,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#pre-launch-checklist","Pre-launch checklist",[341],"Production domain and whitelist configuration are confirmedProduction secrets are stored securelyCallback endpoints are publicly reachableThe server supports signature verification, idempotency, and retry-safe handlingThe business system has a clear status lifecycle and exception recovery flowThe final closure model is confirmed, whether webhook only, active query only, or both together",{"id":1714,"title":1715,"titles":1716,"content":874,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#common-questions","Common questions",[341],{"id":1718,"title":1719,"titles":1720,"content":1721,"level":667},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#when-should-merchantno-keys-and-callback-urls-be-confirmed","When should merchantNo, keys, and callback URLs be confirmed",[341,1715],"Ideally before joint testing starts, not at the last moment before go-live. Otherwise the integration often gets blocked by basic issues such as signature failures, whitelist drift, or unreachable callbacks.",{"id":1723,"title":1724,"titles":1725,"content":1726,"level":667},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#what-is-most-often-missed-before-go-live","What is most often missed before go-live",[341,1715],"The most common gap is exception closure: webhook retries, active-query recovery, failure-reason persistence, and scheduled inspection for unresolved orders.",{"id":1728,"title":1729,"titles":1730,"content":1731,"level":667},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#is-a-successful-synchronous-response-enough","Is a successful synchronous response enough",[341,1715],"No. A successful synchronous response does not mean the transaction has finished. You still need to validate the final status path through webhooks or query APIs. If your business will submit payouts at scale, also validate batch queries, monitoring alerts, and reconciliation workflows before go-live.",{"id":1733,"title":1682,"titles":1734,"content":1735,"level":615},"\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#continue-reading",[341],"SetupRequest signingIntegration flowChange log",{"id":346,"title":345,"titles":1737,"content":1738,"level":609},[],"View the version history for the payout guide. This page records the version history of the payout guide and keeps the current version note. Only the latest version entry is kept on this page.",{"id":1740,"title":1741,"titles":1742,"content":1743,"level":615},"\u002Ftransfer\u002Fget-started\u002Fchange-log#v1-2026-07-10","V1 - 2026-07-10",[345],"Adjusted the payout guide structure to keep only Setup, Request signing, Integration flow, Testing and go-live, and Change log.",{"id":360,"title":359,"titles":1745,"content":1746,"level":609},[],"Query the supported transfer methods for a country, currency, and entity type combination.",{"id":364,"title":363,"titles":1748,"content":1749,"level":609},[],"Query the field requirements for a specific country, currency, entity type, and transfer method.",{"id":368,"title":367,"titles":1751,"content":1752,"level":609},[],"Create a beneficiary that can be used in later Transfer payouts.",{"id":372,"title":371,"titles":1754,"content":1755,"level":609},[],"Query the profile details and review status of a single beneficiary.",{"id":376,"title":375,"titles":1757,"content":1758,"level":609},[],"Create a payer that can be reused in later Transfer payouts.",{"id":380,"title":379,"titles":1760,"content":1761,"level":609},[],"Submit a Transfer payout by using an approved beneficiary ID.",{"id":1763,"title":1764,"titles":1765,"content":1766,"level":609},"\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Finitiate-transfer-with-beneficiary-details","Transfer with Custom Beneficiary",[],"Submit a Transfer payout by sending beneficiary details inline with the request.",{"id":384,"title":383,"titles":1768,"content":1769,"level":609},[],"Query a single transfer by merchant request ID or Onerway payout ID.",{"id":388,"title":387,"titles":1771,"content":1772,"level":609},[],"Query transfer records in batches with pagination.",{"id":392,"title":391,"titles":1774,"content":1775,"level":609},[],"Query and download the electronic voucher for a successful transfer.",{"id":396,"title":395,"titles":1777,"content":1778,"level":609},[],"Query beneficiary records with pagination.",{"id":400,"title":399,"titles":1780,"content":1781,"level":609},[],"Update the profile information of an existing beneficiary.",{"id":404,"title":403,"titles":1783,"content":1784,"level":609},[],"Delete a beneficiary that is no longer needed.",{"id":408,"title":407,"titles":1786,"content":1787,"level":609},[],"Query saved payers with pagination.",{"id":412,"title":411,"titles":1789,"content":1790,"level":609},[],"Update an existing payer profile.",{"id":416,"title":415,"titles":1792,"content":1793,"level":609},[],"Delete a payer that is no longer needed.",{"id":420,"title":419,"titles":1795,"content":1796,"level":609},[],"Query the currencies supported by the merchant account and their balances.",{"id":424,"title":423,"titles":1798,"content":1799,"level":609},[],"Query account balances and transaction details for a specific currency.",{"id":428,"title":427,"titles":1801,"content":1802,"level":609},[],"Query the indicative FX rate from a source currency to a target currency.",{"id":349,"title":353,"titles":1804,"content":1805,"level":609},[],"View Transfer endpoints, webhooks, response codes, and common enum references. Environment DescriptionThe request URLs for the production and sandbox environments differ only in their domain names. We recommend testing the Onerway API in the sandbox environment first. Once testing is complete, you can switch to the production environment by updating the request domain and configuration parameters.To create a sandbox merchant account for testing, please provide your registration email and intended domain name. After receiving the activation email, log in to the merchant portal using the provided link to obtain your merchantNo and secret key. Then, select the appropriate integration method to begin.The submitted email will be used to create your sandbox account. We will add your provided domain to our whitelist. Only whitelisted domains are permitted to access the Onerway API.When logging in to the merchant backend for the first time, you will be required to reset your password. After resetting, you can obtain your merchantNo and secret key.",{"id":1807,"title":1808,"titles":1809,"content":1810,"level":615},"\u002Ftransfer\u002Fapi-reference#environment-configuration","Environment Configuration",[353],"Environment DomainsEnvironmentDomainSandbox Environmenthttps:\u002F\u002Fsandbox-api.onerway.com\u002FpayoutProduction Environmenthttps:\u002F\u002Fapi.onerway.com\u002Fpayout",{"id":1812,"title":1813,"titles":1814,"content":1815,"level":615},"\u002Ftransfer\u002Fapi-reference#field-description","Field Description",[353],"Required Field RulesIdentifierDescriptionMRequired fieldCConditionally required fieldNOptional field",{"id":1817,"title":1818,"titles":1819,"content":874,"level":615},"\u002Ftransfer\u002Fapi-reference#payment-process-four-phases","Payment Process (Four Phases)",[353],{"id":1821,"title":1822,"titles":1823,"content":1824,"level":667},"\u002Ftransfer\u002Fapi-reference#_1️⃣-initialization-pre-setup-phase","1️⃣ Initialization & Pre-Setup Phase",[353,1818],"Node: Start → Pre-SetupBeneficiary Field Retrieval:Method 1: Retrieve mandatory fields via API POST \u002Fapi\u002Fv1\u002Facct\u002FqueryPaymentFeildMethod 2: Contact your account manager to obtain the mandatory field template according to country, currency, payment method, and entity type.Beneficiary Information Preparation:Collect and complete beneficiary information in accordance with the required template.",{"id":1826,"title":1827,"titles":1828,"content":1829,"level":667},"\u002Ftransfer\u002Fapi-reference#_2️⃣-payment-initiation-phase","2️⃣ Payment Initiation Phase",[353,1818],"Branch Decision: Real-Time Payment Enabled?ConditionRoute✅ Real-time payment channel enabled (contact Onerway to activate)Real-Time Payment Route❌ Real-time payment channel not enabledDefault Payment Route🅰️ Default Payment Route(1) Create beneficiary IDEnter or import beneficiary details.Call the API: POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002FaddResponse: returns a beneficiaryId.(2) Beneficiary Reuse LogicCheck whether the beneficiaryId already exists:\n✅ Reusable: use the existing beneficiaryId.❌ Information mismatch: call POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002Fedit to update, then reuse the existing beneficiaryId.(3) Initiate Payment RequestCall the API: POST \u002Fapi\u002Fv1\u002Ftxn\u002FremittanceThe system proceeds to transaction processing.",{"id":1831,"title":1832,"titles":1833,"content":1834,"level":667},"\u002Ftransfer\u002Fapi-reference#_3️⃣-transaction-result-retrieval-phase","3️⃣ Transaction Result Retrieval Phase",[353,1818],"Result Retrieval MethodsResult Retrieval Methods:Active Query Call the API: POST \u002Fapi\u002Fv1\u002Ftxn\u002FqueryAsynchronous Callback The system sends a Webhook notification with transaction results.Webhook Payload Includes:Transaction status (Success \u002F Failure \u002F Processing)Error code and description (if applicable)",{"id":1836,"title":1837,"titles":1838,"content":1839,"level":667},"\u002Ftransfer\u002Fapi-reference#_4️⃣-transaction-completion-phase","4️⃣ Transaction Completion Phase",[353,1818],"Determine Transaction Status:✅ SuccessRetrieve electronic receipt: POST \u002Fapi\u002Fv1\u002Ftxn\u002FqueryVoucher❌ Not SuccessfulQuery the failure reason;Handle manually or reinitiate the payment.",{"id":436,"title":435,"titles":1841,"content":1842,"level":609},[],"Receive asynchronous callbacks when the transfer status changes and update your business order accordingly.",{"id":440,"title":439,"titles":1844,"content":1845,"level":609},[],"Review common Transfer response codes, transfer status values, and related enum dictionaries.",{"id":1847,"title":1848,"titles":1849,"content":1850,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#status","Status",[439],"StatusStatus CodeDescriptionExplanationAPending ReviewTransaction created, waiting for reviewCACompliance ReviewTransaction undergoing compliance reviewBPending CheckTransaction waiting for system checkUReview FailedTransaction failed manual reviewVCheck FailedTransaction failed system checkRPending PayoutTransaction approved, waiting for payoutPProcessing PayoutTransaction being processed for payoutSSuccessTransaction completed successfullyFFailedTransaction processing failed",{"id":1852,"title":1853,"titles":1854,"content":1855,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#full-amount-arrival-flag","Full Amount Arrival Flag",[439],"Status CodeDescriptionExplanationYFull Amount ArrivalBeneficiary receives amount equal to target amountNNon-Full Amount ArrivalBeneficiary may receive less than target amount::",{"id":1857,"title":1858,"titles":1859,"content":1860,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#swift-fee-responsibility","SWIFT Fee Responsibility",[439],"Status CodeDescriptionExplanationSHACosts sharedSWIFT fees are shared between the payer and recipient.OURCosts borne by payerThe payer bears all SWIFT-related fees, and the recipient receives the full amount.::",{"id":1862,"title":1863,"titles":1864,"content":1865,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#transaction-purpose","Transaction Purpose",[439],"transactionPurposeCodeDescriptionExplanation0Transfer to Own AccountFund transfer to own other account1Personal RemittanceFund transfer between individuals2Loan or Credit RepaymentUsed for loan or credit bill refund3Technical ServicesPayment for technical service fees4Shipping FeePayment for transportation-related fees5Professional Services\u002FBusiness ServicesPayment for professional or business service fees",{"id":1867,"title":1868,"titles":1869,"content":1870,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#payment-method","Payment Method",[439],"payoutMethodCodeDescriptionExplanationSWIFTSWIFT Submit paymentInternational transfer via SWIFT networkBANK_TRANSFERBank Submit paymentTransfer via local banking networkE_WALLETWallet Submit paymentTransfer to e-wallet accountCASH_PICKUPCash PickupBeneficiary can collect cash at designated location",{"id":1872,"title":1873,"titles":1874,"content":1875,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#entity-type","Entity Type",[439],"entityTypeCodeDescriptionExplanation0CompanyCorporate legal entity account1IndividualNatural person account",{"id":1877,"title":1878,"titles":1879,"content":1880,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#currency","Currency",[439],"currencyCodeDescriptionExplanationUSDUS DollarLegal currency of United States of AmericaEUREuroLegal currency of European Union member countriesGBPBritish PoundLegal currency of United KingdomJPYJapanese YenLegal currency of JapanPHPPhilippine PesoLegal currency of PhilippinesIDRIndonesian RupiahLegal currency of IndonesiaTHBThai BahtLegal currency of ThailandMYRMalaysian RinggitLegal currency of Malaysia",{"id":1882,"title":1883,"titles":1884,"content":1885,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#beneficiary-information","Beneficiary Information",[439],"receiverInfoParameterTypeDescriptioncompanyNamestring(64)Company NamelastNamestring(64)Last NamefirstNamestring(64)First NameareaCodestring(32)Area Codephonestring(16)Mobile NumbervatNumberstring(64)VAT Number CPF\u002FCNPJbirthDatestringDate of Birth (yyyy-MM-dd)emailstring(32)Beneficiary email, conditional fieldidentityTypestring(32)ID Type (e.g., SSN), conditional field",{"id":1887,"title":1888,"titles":1889,"content":1890,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#address","Address",[439],"address Field DescriptionParameterTypeDescriptionstatestring(20)State\u002FProvincecitystring(64)CityaddressLine1string(256)Address Line 1addressLine2string(256)Address Line 2addressLine3string(256)Address Line 3postalCodestring(32)Postal Code",{"id":1892,"title":1893,"titles":1894,"content":1895,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#account-information","Account information",[439],"accountInfomation Field DescriptionParameterTypeDescriptioncardNumberstring(20)Card Number\u002FIBANaccountTypestring(64)Account Type 0:checking, 1:saving, 2:ordinaryswiftCodestring(256)swift codebankNamestring(250)Bank name (optional). When provided, this field will override the default valuesortCodestring(256)Sort Code\u002FABAbranchCodestring(256)Branch NumberbankHolderNamestring(32)Bank account namewalletTypestring(20)Wallet TypewalletPhonestring(64)Wallet ValuepickUpBankNamestring(256)Pickup InstitutionpickUpBankBranchNamestring(256)Branch InstitutionpickUpBankBranchIdstring(256)Branch Institution IDpickUpBankBranchAddressstring(32)Branch Institution Address",{"id":1897,"title":1898,"titles":1899,"content":1900,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#response-code","Response Code",[439],"respCodeCodeDescriptionExplanation0000SuccessRequest processed successfully1001Parameter ErrorRequest parameters do not meet requirements1002Signature ErrorRequest signature verification failed1003Insufficient BalanceAccount balance insufficient to complete transaction1004Limit ExceededTransaction limit exceeded2001System ErrorSystem internal processing exception2002Network TimeoutNetwork connection timeout3001Account FrozenAccount frozen and cannot operate3002Duplicate RequestDuplicate submitted request NotesAll enum values are case-sensitiveCurrency codes follow ISO 4217 standardResponse codes only list common statuses, refer to error code documentation for detailed error codes",{"id":1902,"title":1813,"titles":1903,"content":1904,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#field-description",[439],"ParameterTypeDescriptionpayoutIdintegerIDpaymentMethodstringPayment MethodpayoutTypestringPayout TypesettleCurrencystringSettlement CurrencysettleSumAmountnumberSettlement Summary AmountserviceFeenumberService FeeotherFeenumberOther FeesfrozenAmountnumberRisk Control Frozen AmountsettleAmountnumberActual Settlement AmountpayoutCurrencystringPayout CurrencypayoutAmountnumberPayout AmountconvRatenumberConversion FX RatemerchantNointegerMerchant NumberbeneficiaryIdintegerbeneficiary IDbeneficiaryNamestringName of BeneficiarybeneficiaryBankNamestringBeneficiary Bank namebeneficiaryBankAddressstringBeneficiary Bank AddressbeneficiaryAccountstringBeneficiary AccountbeneficiaryAccountCountrystringBeneficiary Account CountrybeneficiaryAccountNamestringBeneficiary Account NamebeneficiaryAccountSwiftCodestringBeneficiary Account SWIFT CODEbeneficiaryAccountLocalCodestringBeneficiary Account LOCAL CODEbeneficiaryCountrystringBeneficiary CountrybeneficiaryAddressstringBeneficiary AddressmobileNumberstringMobile NumberpayoutStatusstringPayout StatuspayoutTipsstringCustomer TipspayoutRemarkstringException TipspayoutTimestringPayout TimedistributeStatusstringDistribution StatusdistributePsstringPayment ReferencetransactionPurposestringTransaction PurposeremarkstringRemarkcreateTimestringCreation timeupdateTimestringUpdate TimepayoutMethodstringPayment Method payoutMethod enum valuefirstNamestringBeneficiary - First NamelastNamestringBeneficiary - Last NamecompanyNamestringCompany Name",{"id":1906,"title":1907,"titles":1908,"content":1909,"level":615},"\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#status-description","Status Description",[439],"ParameterTypeDescriptionWAITINGStringWaitingPROCESSStringProcessingREJECTStringRejectedPASSStringPassedFAILStringFailedUNNECESSARYStringNot RequiredPENDING_UPDATEStringPending Update",{"id":448,"title":332,"titles":1911,"content":1912,"level":609},[],"Prepaid virtual card issuing for platforms and businesses, including card creation, cardholder management, transaction visibility, and card lifecycle controls. Use Onerway Issuing to create and manage prepaid virtual cards for online purchasing scenarios. After onboarding and card creation, you can manage card status, query transaction records, and receive event notifications for card operations and card transactions.",{"id":1914,"title":1915,"titles":1916,"content":1917,"level":615},"\u002Fissuing\u002Fget-started#core-features","Core features",[332],"Issue prepaid virtual cards through the Onerway platformUse the merchant portal for visual operations or API integration for automated issuing workflowsManage the card lifecycle, including freeze, unfreeze, termination, deposit, and balance returnTrace card transactions across authorization, settlement, refund, verification, and related event statesLet Onerway handle PCI DSS scope for sensitive card data surfaces",{"id":1919,"title":1920,"titles":1921,"content":1922,"level":615},"\u002Fissuing\u002Fget-started#merchant-workflow","Merchant workflow",[332],"StepDescriptionOnboardingRegister an account, submit KYC materials, and obtain issuing access after approval.Account fundingSubmit a funding request so the currency account balance can support card creation and card operations.Select card productConfirm the card product, issuing market, currency, card network, and usage details with Onerway.Create cardholderCreate the cardholder linked to the card and responsible for card spending.Create cardAssociate the cardholder, set the deposit amount, and create the virtual card.Card spendingUse the card for online purchases after creation succeeds.Transaction query and managementQuery transaction records, manage card status, and process follow-up actions such as disputes when applicable.",{"id":1924,"title":612,"titles":1925,"content":1926,"level":615},"\u002Fissuing\u002Fget-started#start-here",[332],"Setup — prepare the Issuing environment, ApiKey, IP allowlist, merchant credentials, and event callback URLAPI specifications — review common request headers, response envelope, currency and timestamp rules, and response codesCreate cardholder — create the cardholder required before card creationCreate card — create a prepaid virtual card for a cardholderEvent webhooks — receive asynchronous card operation and transaction events",{"id":453,"title":20,"titles":1928,"content":1929,"level":609},[],"Before calling Issuing APIs, read the flow below carefully.",{"id":1931,"title":1932,"titles":1933,"content":1934,"level":615},"\u002Fissuing\u002Fget-started\u002Fsetup#setup-steps","Setup steps",[20],"Select the base URLUse the base URL that matches the environment of your ApiKey.EnvironmentBase URLProductionhttps:\u002F\u002Fissuer.onerway.com\u002Fapi\u002Fv1\u002FmerchantSandboxhttps:\u002F\u002Fsandbox-issuer.onerway.com\u002Fapi\u002Fv1\u002FmerchantSandbox and production credentials are separate. API paths, request methods, and request structures stay the same across environments, but the base URL and ApiKey must come from the same environment.Create a sandbox merchant accountProvide your email address, source IP address, and event callback URL to Onerway. After the sandbox account is created, sign in to the merchant portal from the email link and obtain the merchant number and secret key used for integration and webhook verification.Provide source IP addressesSend your stable server source IP addresses to Onerway so they can be added to the Issuing allowlist.Provide only stable server source IP addresses.If sandbox and production use different source IP addresses, provide them separately.If a source IP address changes, update the allowlist before switching traffic.Store credentials securelyIssuing APIs identify caller permissions through the ApiKey request header. Store the ApiKey, merchant number, and webhook secret on your server.Do not expose issuing credentials in frontend pages, mobile apps, client-side bundles, logs, or public repositories.Configure event callbacksConfigure a server-side callback URL that can receive card operation and transaction event webhooks. The callback must verify x-signature, deduplicate events by request_id, and return respCode=20000 after accepting an event.",{"id":1936,"title":337,"titles":1937,"content":1938,"level":615},"\u002Fissuing\u002Fget-started\u002Fsetup#integration-flow",[20],"StepActionEndpoint or source1Get card product information and confirm the productId with Onerway.Card product list2Create a cardholder that matches the card product.Create cardholder3Create a card with productId, cardholderId, and the deposit amount.Create card4Query card operation progress, basic card information, balance, and sensitive information when needed.Card queries5Receive card operation event notifications.Card operation event6Query card transaction records and receive transaction event notifications.Query transaction records",{"id":1940,"title":626,"titles":1941,"content":1942,"level":615},"\u002Fissuing\u002Fget-started\u002Fsetup#next-steps",[20],"API specifications — review common Issuing API rulesCreate cardholder — create a cardholder before card creationCreate card — create the first virtual cardEvent webhooks — configure card operation and transaction event handling",{"id":456,"title":460,"titles":1944,"content":1945,"level":609},[],"Review common Issuing API request headers, response envelope, currency and timestamp rules, and response codes. Use this page before integrating Issuing APIs. All Issuing merchant APIs use POST requests under the \u002Fapi\u002Fv1\u002Fmerchant base path unless an endpoint page states otherwise.",{"id":1947,"title":1948,"titles":1949,"content":1950,"level":667},"\u002Fissuing\u002Fapi-reference#request-headers","Request headers",[460],"HeaderTypeRequiredDescriptionContent-TypeStringYesUse application\u002Fjson;charset=UTF-8.ApiKeyStringYesMerchant identity credential assigned by Onerway for Issuing API access.",{"id":1952,"title":1953,"titles":1954,"content":1955,"level":667},"\u002Fissuing\u002Fapi-reference#response-structure","Response structure",[460],"FieldTypeDescriptionrespCodeStringResponse code. 20000 means the request was processed successfully.respMsgStringResponse message.dataObject \u002F ArrayBusiness data. The value can be null when the request fails.",{"id":1957,"title":1878,"titles":1958,"content":1959,"level":667},"\u002Fissuing\u002Fapi-reference#currency",[460],"Currency values use the ISO 4217 international standard.",{"id":1961,"title":1962,"titles":1963,"content":1964,"level":667},"\u002Fissuing\u002Fapi-reference#timezone","Timezone",[460],"Long timestamp fields are UTC timestamps. Query parameters use seconds unless the endpoint page states otherwise; operation, settlement, authorization, and transaction event timestamps can be returned in milliseconds.",{"id":1966,"title":319,"titles":1967,"content":1968,"level":667},"\u002Fissuing\u002Fapi-reference#response-codes",[460],"When the HTTP status code is not 200: HTTP status codeDescription401 UnauthorizedInvalid API credentials.403 ForbiddenIP allowlist restriction or insufficient API permissions. When the HTTP status code is 200, read the business response code: CodeDescription20000Success.40000Parameter error.80000Internal service error. Contact Onerway.80001Cardholder not found.80002Cardholder email already exists.80003Incorrect cardholder merchant number.80004Merchant status is invalid.80005Merchant has no issuing business.80006Merchant account not found.80007Merchant balance is not enough.80008The recharge amount exceeds the maximum limit.80009The recharge amount is less than the minimum limit.80010Duplicate data.80011Cardholder card count limit.81000Unauthorized merchant.81001Business does not exist.40004System exception: NoHandlerFoundException.40005System exception: HttpRequestMethodNotSupportedException.40013System exception: HttpMessageNotReadableException.40015System exception: HttpMediaTypeNotSupportedException.",{"id":467,"title":466,"titles":1970,"content":1971,"level":609},[],"Create a prepaid virtual card for a specified cardholder and card product. Use this endpoint to create a card for a cardholder with a designated card product and initial deposit amount.",{"id":471,"title":470,"titles":1973,"content":1974,"level":609},[],"Freeze, unfreeze, or terminate an existing card. Use this endpoint to perform status operations on a card, such as freeze, unfreeze, or termination.",{"id":475,"title":474,"titles":1976,"content":1977,"level":609},[],"Deposit a specified amount to an existing card. Use this endpoint to deposit funds to a card.",{"id":479,"title":478,"titles":1979,"content":1980,"level":609},[],"Withdraw a card's available balance to the Onerway account. Use this endpoint to withdraw a card's available balance to the Onerway account.",{"id":483,"title":482,"titles":1982,"content":1983,"level":609},[],"Query card operation records with pagination and optional filters. Use this endpoint to query card operation records by card ID, idempotent request ID, operation type, and time range.",{"id":487,"title":486,"titles":1985,"content":1986,"level":609},[],"Query basic status information for a card. Use this endpoint to query the basic status information of a card.",{"id":491,"title":490,"titles":1988,"content":1989,"level":609},[],"Query the current balance of a card. Use this endpoint to query the current balance of a card.",{"id":495,"title":494,"titles":1991,"content":1992,"level":609},[],"Query sensitive card information from a secure server-side environment. Use this endpoint to query sensitive card information such as card number, card verification code, and expiry date from a secure server-side environment.",{"id":499,"title":498,"titles":1994,"content":1995,"level":609},[],"Create a cardholder under the merchant account. Use this endpoint to create a cardholder before card creation.",{"id":503,"title":502,"titles":1997,"content":1998,"level":609},[],"Update an existing cardholder's profile information. Use this endpoint to update an existing cardholder's profile information.",{"id":507,"title":506,"titles":2000,"content":2001,"level":609},[],"Query cardholders under the merchant account with pagination and optional filters. Use this endpoint to query cardholders under the merchant account.",{"id":511,"title":510,"titles":2003,"content":2004,"level":609},[],"Query the list of supported regions for Issuing cardholder addresses. Use this endpoint to query supported regions.",{"id":515,"title":514,"titles":2006,"content":2007,"level":609},[],"Query cities or administrative divisions under a specified region. Use this endpoint to query cities or administrative divisions under a specified region.",{"id":519,"title":518,"titles":2009,"content":2010,"level":609},[],"Query supported mobile area codes. Use this endpoint to query supported mobile area codes.",{"id":523,"title":522,"titles":2012,"content":2013,"level":609},[],"Query card transaction records with pagination and optional filters. Use this endpoint to query card transaction records by transaction type, status, card ID, and time range.",{"id":527,"title":526,"titles":2015,"content":2016,"level":609},[],"Query paginated 3DS delivery records by card, transaction order number, and time range. Use this endpoint to query 3DS delivery records for an issued card.",{"id":531,"title":530,"titles":2018,"content":2019,"level":609},[],"Retrieve the card products and related configuration available to the merchant. Use this endpoint to retrieve the card products that can be used when creating a card.",{"id":535,"title":534,"titles":2021,"content":2022,"level":609},[],"Understand Issuing webhook headers, payload envelope, merchant acknowledgement, and HMAC-SHA256 signature verification. Use this page before implementing Issuing webhook callbacks. Onerway pushes card operation, card transaction, and 3DS events to the callback URL configured for the merchant.",{"id":2024,"title":1948,"titles":2025,"content":2026,"level":615},"\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#request-headers",[534],"HeaderTypeRequiredDescriptionContent-TypeStringYesFixed to application\u002Fjson;charset=UTF-8.x-timestampStringYesUnix timestamp in seconds.x-signatureStringYesGenerate the HMAC-SHA256 signature from webhook_secret and x-timestamp + \".\" + raw_body. See Signature and verification.",{"id":2028,"title":2029,"titles":2030,"content":2031,"level":615},"\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#payload-structure","Payload structure",[534],"FieldTypeRequiredDescriptionrequest_idStringYesUnique event identifier for deduplication.event_typeStringYesEvent type. Issuing currently sends issuing.cardOperateEvent, issuing.cardTransactionEvent, and issuing.card3dsEvent.created_atStringYesEvent creation time in ISO 8601 format.versionStringNoWebhook API version selected when the subscription is created. Defaults to 1.0 when not specified.dataObjectYesBusiness data. The structure depends on event_type.",{"id":2033,"title":2034,"titles":2035,"content":2036,"level":615},"\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#merchant-response-requirements","Merchant response requirements",[534],"The merchant callback must return a JSON response. Onerway uses this response to decide whether the push was received successfully. FieldTypeDescriptionrespCodeStringReturn 20000 to confirm receipt.respMsgStringResponse message. If the callback response code is not 20000, Onerway retries every 15 seconds, up to 10 times.",{"id":2038,"title":2039,"titles":2040,"content":2041,"level":615},"\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#signature-and-verification","Signature and verification",[534],"Onerway signs asynchronous notifications such as card operation, transaction, and 3DS events. Verify the signature before processing the event. Build the signed content as: x-timestamp + \".\" + raw_body Generate the expected signature with HMAC-SHA256 and compare it with x-signature case-insensitively. import javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.util.Base64;\nimport java.util.HexFormat;\n\npublic final class HmacSHA256Util {\n private HmacSHA256Util() {\n }\n\n public static String signHmacSHA256(String webhook_secret, String content) throws Exception {\n byte[] key = Base64.getDecoder().decode(webhook_secret);\n Mac mac = Mac.getInstance(\"HmacSHA256\");\n mac.init(new SecretKeySpec(key, \"HmacSHA256\"));\n return HexFormat.of().formatHex(mac.doFinal(content.getBytes(StandardCharsets.UTF_8)));\n }\n\n public static boolean verifyHmacSHA256(String webhook_secret, String content, String signed) throws Exception {\n String expected = signHmacSHA256(webhook_secret, content);\n return MessageDigest.isEqual(\n expected.toLowerCase().getBytes(StandardCharsets.UTF_8),\n signed.toLowerCase().getBytes(StandardCharsets.UTF_8)\n );\n }\n}\nimport base64\nimport hashlib\nimport hmac\n\ndef sign_hmac_sha256(webhook_secret: str, content: str) -> str:\n key = base64.b64decode(webhook_secret)\n return hmac.new(key, content.encode(\"utf-8\"), hashlib.sha256).hexdigest()\n\ndef verify_hmac_sha256(webhook_secret: str, content: str, signed: str) -> bool:\n expected = sign_hmac_sha256(webhook_secret, content)\n return hmac.compare_digest(expected.lower(), signed.lower())\n\u003C?php\n\nfinal class HmacSHA256Util\n{\n public static function signHmacSHA256(string $webhook_secret, string $content): string\n {\n $key = base64_decode($webhook_secret, true);\n if ($key === false) {\n throw new InvalidArgumentException('Invalid webhook secret.');\n }\n\n return hash_hmac('sha256', $content, $key);\n }\n\n public static function verifyHmacSHA256(string $webhook_secret, string $content, string $signed): bool\n {\n $expected = self::signHmacSHA256($webhook_secret, $content);\n return hash_equals(strtolower($expected), strtolower($signed));\n }\n} html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .ssWmh, html code.shiki .ssWmh{--shiki-light:#6182B8;--shiki-default:#023B95;--shiki-dark:#82AAFF}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}",{"id":543,"title":542,"titles":2043,"content":2044,"level":609},[],"Receive card operation event notifications for card creation, freeze, unfreeze, deposit, termination, and balance return status changes. Use this webhook to receive card operation status changes.",{"id":547,"title":546,"titles":2046,"content":2047,"level":609},[],"Receive card transaction event notifications for authorization, reversal, settlement, refund, and verification events. Use this webhook to receive card transaction events.",{"id":551,"title":550,"titles":2049,"content":2050,"level":609},[],"Receive 3DS one-time password event notifications for issued card transactions. Use this webhook to receive 3DS one-time password events.",{"id":559,"title":332,"titles":2052,"content":2053,"level":609},[],"Account balance, account transaction, account statement, and Global Account management services. Onerway Account is for merchants that need to manage account funds, query balance movements, export statements, and use Global Account capabilities. You can use Account service APIs to query multi-currency balances, trace account transactions, export daily statements, and create or query a Global Account after the required capability is enabled. For new integrations with account balance, account transaction, and account statement APIs, use the current Account service endpoints. The API Reference sidebar groups the current endpoints by Account balance, Account transaction, Account statement, and Global Account. Deprecated endpoints are not shown as current integration entry points.",{"id":2055,"title":2056,"titles":2057,"content":2058,"level":615},"\u002Faccount\u002Fget-started#capabilities","Capabilities",[332],"CapabilityUse caseRecommended entry pointAccount balanceQuery balance summaries across currencies or read the balance for one currency.Query account balance overviewAccount transactionQuery account balance movement records or look up related records by transaction order number.Query account transactionsAccount statementExport daily account statement CSV files for finance reconciliation.Export daily account statementGlobal AccountCreate a Global Account and retrieve onboarding details, account status, and notification URL.Create Global AccountResponse codesIdentify causes from Account service response codes and decide troubleshooting actions.Response codes",{"id":2060,"title":2061,"titles":2062,"content":2063,"level":615},"\u002Faccount\u002Fget-started#integration-path","Integration Path",[332],"Complete setupPrepare the Account service base URL, apikey, x-timestamp, outbound IP allowlist, and API permissions first. The current Account service base URLs are:EnvironmentBase URLSandboxhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-serverProductionhttps:\u002F\u002Fapi.onerway.com\u002Faccount-serverThe Setup page includes required request headers, the example apikey, the 10-minute timestamp window, and the endpoint URL checklist.Query account balancesAfter setup, start with the balance APIs to verify account access and currency data.Query account balance overview: use for dashboards, fund summaries, and multi-currency balance views.Query account balance: use before payments, payouts, or reconciliation when you need the balance for one currency.Query account transactionsAccount transactions help explain balance changes and connect account movements with orders, payments, or payout records.Query account transactions: query records by currency, time range, and pagination.Query account transactions by transaction order number: use this when you already have a transaction order number and need the related account movements.Export account statementsFor finance reconciliation or archival, use Export daily account statement to download a CSV file for a specified date. Store files by business date and keep the request parameters with the exported file for later traceability.Use Global AccountFor account opening, collection, or payout scenarios, confirm that the Global Account capability is enabled, then call:Create Global AccountGet Global Account details",{"id":2065,"title":2066,"titles":2067,"content":2068,"level":615},"\u002Faccount\u002Fget-started#field-differences","Field Differences",[332],"The current account balance, account transaction, and account statement APIs use the Account service response shape: ItemCurrent Account service endpointsAuthenticationapikey headerReplay protection headerx-timestampSuccess response coderespCode = 20000Response message fieldrespMsgError objecterrorIdempotency fieldrequestId, used for safe retry within 10 minutes Global Account APIs follow the field names shown on their current endpoint pages. Do not mix response envelopes, status codes, or required fields across different endpoints.",{"id":2070,"title":2071,"titles":2072,"content":2073,"level":615},"\u002Faccount\u002Fget-started#quick-links","Quick Links",[332],"Setup - Prepare the Account service base URL, apikey, x-timestamp, and outbound IP allowlistQuery account balance overview - Query multi-currency account balance summariesQuery account transactions - Review account transaction records and balance movementsExport daily account statement - Export a daily account statement CSVCreate Global Account - Create a Global AccountResponse codes - Handle Account service response codes and troubleshooting actions",{"id":564,"title":20,"titles":2075,"content":2076,"level":609},[],"Configure the Account service base URL, apikey, x-timestamp, and outbound IP allowlist before calling account balance, account transaction, account statement, and Global Account APIs. Account service APIs use dedicated base URLs and an environment-specific apikey request header. Before you call account balance, account transaction, account statement, or Global Account endpoints, make sure the target environment, API access, apikey, x-timestamp, and outbound IP allowlist are ready.",{"id":2078,"title":1932,"titles":2079,"content":2080,"level":615},"\u002Faccount\u002Fget-started\u002Fsetup#setup-steps",[20],"Confirm API accessAccount service APIs are restricted. Onerway must enable the corresponding capability for your merchant account before you can call the endpoints.Before calling account balance, account transaction, and account statement APIs, confirm that Account service API access is enabled.Before calling Global Account APIs, confirm that Global Account opening, collection, or payout capabilities are enabled.If a platform merchant queries on behalf of a sub-merchant, confirm that the parent-child merchant relationship and onBehalfOf permission are configured.Select the base URLUse the Account service base URL that matches the environment of your apikey.EnvironmentBase URLProductionhttps:\u002F\u002Fapi.onerway.com\u002Faccount-serverSandboxhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-serverSandbox and production credentials are separate. API paths start with \u002Fapi\u002Fv2\u002F... or with the \u002Fapi\u002Fv1\u002F... path shown on the current Global Account page. The base URL, API path, and apikey must come from the same environment.Store the apikeyAccount service APIs identify caller permissions through the apikey request header.HeaderRequiredDescriptionapikeyYesCredential value assigned for Account service access.Store the apikey on your server. Do not expose it in frontend pages, mobile apps, client-side bundles, logs, or public repositories.Send x-timestampAccount balance, account transaction, and account statement APIs require both apikey and x-timestamp. The gateway uses x-timestamp to check whether the request is within the accepted time window and reduce replay risk.HeaderRequiredDescriptionx-timestampYesRequest timestamp. Accepts 10-digit seconds or 13-digit milliseconds. Must be within 10 minutes of the server time.Content-TypeYes (POST)application\u002Fjson.Provide outbound IP addressesSend your stable server outbound IP addresses to Onerway so they can be added to the Account service allowlist.Provide only stable server outbound IP addresses.If sandbox and production use different outbound IP addresses, provide them separately.If an outbound IP address changes, update the allowlist before switching traffic.Send a server-side requestAfter the environment, apikey, x-timestamp, and IP allowlist are ready, call the API from your server and include the required request headers.curl https:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002Fquery \\\n -H 'Content-Type: application\u002Fjson' \\\n -H 'apikey: replace_with_account_service_apikey' \\\n -H 'x-timestamp: 1776931200' \\\n -d '{\n \"requestId\": \"REQ-BAL-OV-20260423-0001\",\n \"displayCurrency\": \"USD\"\n }'",{"id":2082,"title":2083,"titles":2084,"content":2085,"level":615},"\u002Faccount\u002Fget-started\u002Fsetup#endpoint-urls","Endpoint URLs",[20],"The current public Account service endpoint URLs are listed below. Build the request URL by appending the API path to the base URL for the target environment. CategoryEndpointMethodPathAccount balanceQuery account balance overviewPOST\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002FqueryAccount balanceQuery account balancePOST\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002FqueryAccount transactionQuery account transactionsPOST\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002FqueryAccount transactionQuery account transactions by transaction order numberPOST\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fservice\u002FqueryAccount statementExport daily account statementPOST\u002Fapi\u002Fv2\u002Faccount\u002Fstatement\u002Fdaily\u002FexportGlobal AccountCreate Global AccountPOST\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FcreateGlobal AccountGet Global Account detailsPOST\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FgetDetail Complete Sandbox examples: https:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fservice\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fstatement\u002Fdaily\u002Fexporthttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002Fcreatehttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FgetDetail",{"id":2087,"title":2088,"titles":2089,"content":2090,"level":615},"\u002Faccount\u002Fget-started\u002Fsetup#idempotency","Idempotency",[20],"Account balance, account transaction, and account statement APIs are idempotent. Reuse the same requestId to safely retry a request within 10 minutes. A repeated requestId returns a 10006 DUPLICATE_REQUEST error of type idempotency_error.",{"id":2092,"title":626,"titles":2093,"content":2094,"level":615},"\u002Faccount\u002Fget-started\u002Fsetup#next-steps",[20],"Query account balance overview - Query multi-currency account balance summariesQuery account balance - Read the balance for one account currencyQuery account transactions - Review account transaction records and balance movementsQuery account transactions by transaction order number - Query related account transactions by transaction order numberExport daily account statement - Export a daily account statement CSVCreate Global Account - Create a Global Account for collection and payout scenariosGet Global Account details - Retrieve Global Account onboarding details and statusResponse codes - Handle Account service response codes and troubleshooting actions html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"id":576,"title":575,"titles":2096,"content":2097,"level":609},[],"Create a Global Account for acquiring-side collection and payout scenarios. Use this endpoint to initialize a Global Account for a customer, including the bank country or region and supported collection currencies.",{"id":580,"title":579,"titles":2099,"content":2100,"level":609},[],"Retrieve Global Account details by Global Account ID or account number. Use this endpoint to read Global Account details, lifecycle status, supported business types, and supported collection currencies.",{"id":584,"title":583,"titles":2102,"content":2103,"level":609},[],"Query balance movement records for the caller merchant account or a specified sub-merchant account. Use this endpoint to page through account balance movements, which are the balance increase and decrease records created in Onerway Account by acquiring, payout, and related business activity. By default, the query returns records for the merchant account associated with the apikey. When a platform merchant queries on behalf of a sub-merchant, provide onBehalfOf to identify the sub-merchant account. The response includes records that match the currency, balance type, business type, and balance update time range filters.",{"id":588,"title":587,"titles":2105,"content":2106,"level":609},[],"Query account balance movement records associated with one or more transaction order numbers. Use this endpoint when you already have transaction order numbers and need to retrieve the related account transaction records.",{"id":592,"title":591,"titles":2108,"content":2109,"level":609},[],"Query the account balance details for a single currency. Use this endpoint to retrieve the account balance breakdown for a specified currency, including Payment, Funding, pending settlement, on-hold, risk deposit, and total balances.",{"id":596,"title":595,"titles":2111,"content":2112,"level":609},[],"Query multi-currency account balance summaries and an optional display-currency total. Use this endpoint to retrieve per-currency account balance summaries and, when exchange rates are available, a display-currency total for overview purposes.",{"id":600,"title":599,"titles":2114,"content":2115,"level":609},[],"Export a daily account statement as a CSV file. Use this endpoint to export a daily account statement CSV for a given date, currency, and business type.",{"id":603,"title":319,"titles":2117,"content":2118,"level":609},[],"Review Account service response envelopes, success codes, and recommended troubleshooting actions. Use this page when an Account service response returns a non-success response code. Always follow the response field names shown on the endpoint page you are calling. Current account balance, account transaction, and account statement endpoints do not use code \u002F message as the primary response envelope. They use respCode \u002F respMsg, where 20000 means the request was processed successfully.",{"id":2120,"title":2121,"titles":2122,"content":2123,"level":615},"\u002Faccount\u002Fapi-reference\u002Fresponse-codes#current-account-service-endpoints","Current Account service endpoints",[319],"Account balance and account transaction endpoints use the JSON response envelope respCode \u002F respMsg \u002F data \u002F error. The daily account statement export endpoint returns a CSV stream on success. It returns a JSON error response with respCode, respMsg, and error only when the request fails before the CSV response is committed. respCodeDefault respMsgError typeExplanationRecommended action20000Success-The request was processed successfully.Continue with the endpoint-specific data fields, account balance details, account transaction records, or pagination fields. For a successful statement export, read the CSV stream.10001Invalid request parameterinvalid_request_errorOne or more request fields are missing, malformed, outside the allowed range, or use an unsupported enum value.Compare the request with the endpoint schema, required fields, currency codes, enum values, timestamp requirements, query time ranges, and examples.10006DUPLICATE_REQUESTidempotency_errorThe requestId was reused within the idempotency window.Confirm the original request result first. Use a new requestId only for a genuinely new operation. The error object carries standardized error details: FieldDescriptioncodeExternal business error code, usually aligned with respCode.declineCodeCompatibility field that usually mirrors code for current Account service APIs.messageHuman-readable error message.typeStandardized error type, such as invalid_request_error, idempotency_error, or api_error.paramRequest parameter that caused the error, when applicable.requestIdCaller request ID copied from body requestId.",{"id":2125,"title":2126,"titles":2127,"content":2128,"level":615},"\u002Faccount\u002Fapi-reference\u002Fresponse-codes#global-account-endpoints","Global Account endpoints",[319],"Global Account creation and detail APIs use the success \u002F respCode \u002F respMsg response envelope. The success response code is 20000. respCodeConstantDefault respMsgExplanationRecommended action20000SUCCESS_CODESuccessThe request was processed successfully.Continue with the endpoint-specific data fields and Global Account status values.10001INVALID_PARAMETERInvalid request parameterOne or more request fields are missing, malformed, outside the allowed range, or use an unsupported enum value.Compare the request with the endpoint schema, required fields, enum values, query constraints, and examples. For detail queries, globalAccountId must be numeric, and at least one of globalAccountId or globalAccountNo is required.10002INVALID_TIME_RANGEInvalid query time rangeThe query time range is invalid or exceeds the supported range for the request.Adjust the start and end time according to the endpoint query constraints, then retry.10003UNAUTHORIZED_ACCESSAccess deniedThe caller is not allowed to access the requested Account service resource or capability.Check that the apikey, environment, merchant account, and IP allowlist match the requested resource. Contact Onerway support if access should be enabled.10004RESOURCE_NOT_FOUNDResource not foundThe requested Global Account or related business resource was not found.Verify globalAccountId, globalAccountNo, environment, and merchant ownership. Do not retry blindly with the same identifier.10005REQUEST_FAILEDRequest failedThe Account service could not complete the request.Check the response message and request context. Retry only when the operation is safe to repeat or protected by idempotency.10006DUPLICATE_REQUESTDuplicate requestThe request duplicates a previous request or uses an idempotency identifier that has already been processed.Query the existing result before sending another request. Use a new requestId only for a genuinely new operation.10007INIT_GLOBAL_ACCOUNT_FAILEDInit Global Account failedGlobal Account initialization failed.Check customerId, onBehalfOf, supported currencies, bank country or region, and account capability configuration. Contact Onerway support if the request data is valid.10008GLOBAL_ACCOUNT_CUSTOMER_INVALIDInvalid customer id for Global AccountThe customer identifier cannot be used for the requested Global Account operation.Confirm customerId belongs to the merchant account. For platform calls on behalf of a child customer, confirm customerId matches onBehalfOf and the parent-child relationship is valid.10009GLOBAL_ACCOUNT_CALLER_NOT_AUTHORIZEDCaller identity does not match customerThe caller identity does not match the customer associated with the Global Account resource.Confirm that the apikey, merchant account, customerId, onBehalfOf, and Global Account identifier all belong to the same authorized relationship.",[14,21,25,29,33,37,46,53,60,67,74,78,82,86,93,97,101,105,109,124,128,132,136,140,144,148,152,156,160,164,168,172,176,180,184,188,192,196,200,204,208,212,216,220,224,228,232,236,240,244,248,252,256,260,268,272,276,280,284,288,292,296,300,304,308,312,316,320,328,334,338,342,346,360,364,368,372,376,380,1763,384,388,392,396,400,404,408,412,416,420,424,428,349,436,440,448,453,456,467,471,475,479,483,487,491,495,499,503,507,511,515,519,523,527,531,535,543,547,551,559,564,576,580,584,588,592,596,600,603],{"navigation":2131,"files":2729,"visiblePaths":4229},[2132,2444,2566,2677],{"title":2133,"deprecated":8,"path":2134,"stem":2135,"children":2136,"page":111},"支付","\u002Fzh\u002Fpayments","zh\u002Fpayments",[2137,2164,2233],{"title":2138,"path":2139,"stem":2140,"children":2141,"deprecated":8},"快速开始","\u002Fzh\u002Fpayments\u002Fget-started","zh\u002Fpayments\u002F01.get-started\u002F01.index",[2142,2144,2148,2152,2156,2160],{"title":2143,"path":2139,"stem":2140,"deprecated":8},"支付概览",{"title":2145,"path":2146,"stem":2147,"deprecated":8},"接入准备","\u002Fzh\u002Fpayments\u002Fget-started\u002Fsetup","zh\u002Fpayments\u002F01.get-started\u002F02.setup",{"title":2149,"path":2150,"stem":2151,"deprecated":8},"请求签名","\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing","zh\u002Fpayments\u002F01.get-started\u002F03.request-signing",{"title":2153,"path":2154,"stem":2155,"deprecated":8},"Webhook 通知","\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks","zh\u002Fpayments\u002F01.get-started\u002F04.webhooks",{"title":2157,"path":2158,"stem":2159,"deprecated":8},"币种与金额校验","\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount","zh\u002Fpayments\u002F01.get-started\u002F06.currency-and-amount",{"title":2161,"path":2162,"stem":2163,"deprecated":8},"沙盒测试","\u002Fzh\u002Fpayments\u002Fget-started\u002Ftesting","zh\u002Fpayments\u002F01.get-started\u002F07.testing",{"title":2165,"deprecated":8,"path":2166,"stem":2167,"children":2168,"page":111},"线上支付","\u002Fzh\u002Fpayments\u002Fonline-payments","zh\u002Fpayments\u002F02.online-payments",[2169,2176,2182,2189,2206],{"title":2170,"path":2171,"stem":2172,"children":2173,"deprecated":8},"收银台","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout","zh\u002Fpayments\u002F02.online-payments\u002F01.checkout\u002F01.index",[2174],{"title":2175,"path":2171,"stem":2172,"deprecated":8},"收银台接入",{"title":52,"path":2177,"stem":2178,"children":2179,"deprecated":8},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk","zh\u002Fpayments\u002F02.online-payments\u002F02.sdk\u002F01.index",[2180],{"title":2181,"path":2177,"stem":2178,"deprecated":8},"Web SDK 接入",{"title":2183,"path":2184,"stem":2185,"children":2186,"deprecated":8},"API 直连","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi","zh\u002Fpayments\u002F02.online-payments\u002F03.api\u002F01.index",[2187],{"title":2188,"path":2184,"stem":2185,"deprecated":8},"API 直连接入",{"title":2190,"path":2191,"stem":2192,"children":2193,"deprecated":8},"支付方式","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods","zh\u002Fpayments\u002F02.online-payments\u002F04.payment-methods\u002F01.index",[2194,2196,2199,2202],{"title":2195,"path":2191,"stem":2192,"deprecated":8},"支付方式概览",{"title":73,"path":2197,"stem":2198,"deprecated":8},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay","zh\u002Fpayments\u002F02.online-payments\u002F04.payment-methods\u002F02.apple-pay",{"title":77,"path":2200,"stem":2201,"deprecated":8},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay","zh\u002Fpayments\u002F02.online-payments\u002F04.payment-methods\u002F03.google-pay",{"title":2203,"path":2204,"stem":2205,"deprecated":8},"本地支付方式","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods","zh\u002Fpayments\u002F02.online-payments\u002F04.payment-methods\u002F04.local-payment-methods",{"title":2207,"path":2208,"stem":2209,"children":2210,"deprecated":8},"支付场景","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F01.index",[2211,2213,2217,2221,2225,2229],{"title":2212,"path":2208,"stem":2209,"deprecated":8},"场景概览",{"title":2214,"path":2215,"stem":2216,"deprecated":8},"保存支付方式","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F02.saved-payment-methods",{"title":2218,"path":2219,"stem":2220,"deprecated":8},"订阅支付","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F03.subscriptions",{"title":2222,"path":2223,"stem":2224,"deprecated":8},"预授权与请款","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F04.pre-authorization",{"title":2226,"path":2227,"stem":2228,"deprecated":8},"分账","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F05.profit-sharing",{"title":2230,"path":2231,"stem":2232,"deprecated":8},"退款","\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds","zh\u002Fpayments\u002F02.online-payments\u002F05.scenarios\u002F06.refunds",{"title":2234,"deprecated":8,"path":2235,"stem":2236,"children":2237,"page":111},"API 参考","\u002Fzh\u002Fpayments\u002Fapi-reference","zh\u002Fpayments\u002F04.api-reference",[2238,2383,2440],{"title":2239,"deprecated":8,"path":2240,"stem":2241,"children":2242,"page":111},"接口","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints",[2243,2247,2251,2255,2259,2263,2267,2271,2275,2279,2283,2287,2291,2295,2299,2303,2307,2311,2315,2319,2323,2327,2331,2335,2339,2343,2347,2351,2355,2359,2363,2367,2371,2375,2379],{"title":2244,"path":2245,"stem":2246,"deprecated":8},"创建收银台支付","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-checkout-payment","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F01.create-checkout-payment",{"title":2248,"path":2249,"stem":2250,"deprecated":8},"创建直连交易","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdirect-create-transaction","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F02.direct-create-transaction",{"title":2252,"path":2253,"stem":2254,"deprecated":8},"创建 SDK 交易","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsdk-create-transaction","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F03.sdk-create-transaction",{"title":2256,"path":2257,"stem":2258,"deprecated":8},"生成卡 token","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-card-token","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F04.create-card-token",{"title":2260,"path":2261,"stem":2262,"deprecated":8},"删除卡 token","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdelete-card-token","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F05.delete-card-token",{"title":2264,"path":2265,"stem":2266,"deprecated":8},"预授权请款与撤销","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcapture-or-void-authorization","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F06.capture-or-void-authorization",{"title":2268,"path":2269,"stem":2270,"deprecated":8},"查询可用支付方式","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-available-payment-methods","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F07.list-available-payment-methods",{"title":2272,"path":2273,"stem":2274,"deprecated":8},"查询支付记录","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-payments","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F08.query-payments",{"title":2276,"path":2277,"stem":2278,"deprecated":8},"查询退款记录","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-refunds","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F09.query-refunds",{"title":2280,"path":2281,"stem":2282,"deprecated":8},"查询已保存 token","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-saved-tokens","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F10.list-saved-tokens",{"title":2284,"path":2285,"stem":2286,"deprecated":8},"查询订阅信息","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-subscription-details","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F11.query-subscription-details",{"title":2288,"path":2289,"stem":2290,"deprecated":8},"取消订阅合同","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcancel-subscription-contract","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F12.cancel-subscription-contract",{"title":2292,"path":2293,"stem":2294,"deprecated":8},"查询欺诈通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-fraud-notifications","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F13.query-fraud-notifications",{"title":2296,"path":2297,"stem":2298,"deprecated":8},"查询拒付记录","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-chargebacks","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F14.query-chargebacks",{"title":2300,"path":2301,"stem":2302,"deprecated":8},"查询交易记录","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-transactions","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F15.query-transactions",{"title":2304,"path":2305,"stem":2306,"deprecated":8},"创建支付链接","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-payment-link","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F16.create-payment-link",{"title":2308,"path":2309,"stem":2310,"deprecated":8},"查询支付链接列表","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Flist-payment-links","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F17.list-payment-links",{"title":2312,"path":2313,"stem":2314,"deprecated":8},"更新支付链接状态","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-payment-link-status","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F18.update-payment-link-status",{"title":2316,"path":2317,"stem":2318,"deprecated":8},"申请或取消退款","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-or-cancel-refund","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F19.create-or-cancel-refund",{"title":2320,"path":2321,"stem":2322,"deprecated":8},"上传物流信息","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupload-logistics-info","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F20.upload-logistics-info",{"title":2324,"path":2325,"stem":2326,"deprecated":8},"下载结算文件","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fdownload-settlement-file","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F21.download-settlement-file",{"title":2328,"path":2329,"stem":2330,"deprecated":8},"Ethoca 服务开通申请","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-ethoca-enrollment","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F22.submit-ethoca-enrollment",{"title":2332,"path":2333,"stem":2334,"deprecated":8},"查询 Ethoca 申请状态","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-ethoca-enrollments","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F23.query-ethoca-enrollments",{"title":2336,"path":2337,"stem":2338,"deprecated":8},"变更 Ethoca 申请状态","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-ethoca-enrollment-status","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F24.update-ethoca-enrollment-status",{"title":2340,"path":2341,"stem":2342,"deprecated":8},"查询 Ethoca 预警","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-ethoca-alerts","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F25.query-ethoca-alerts",{"title":2344,"path":2345,"stem":2346,"deprecated":8},"提交 Ethoca 预警处理结果","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-ethoca-alert-outcome","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F26.submit-ethoca-alert-outcome",{"title":2348,"path":2349,"stem":2350,"deprecated":8},"RDR 服务开通申请","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsubmit-rdr-enrollment","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F27.submit-rdr-enrollment",{"title":2352,"path":2353,"stem":2354,"deprecated":8},"查询 RDR 申请状态","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-rdr-enrollments","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F28.query-rdr-enrollments",{"title":2356,"path":2357,"stem":2358,"deprecated":8},"变更 RDR 申请状态","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fupdate-rdr-enrollment-status","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F29.update-rdr-enrollment-status",{"title":2360,"path":2361,"stem":2362,"deprecated":8},"查询 RDR 预警","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-rdr-alerts","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F30.query-rdr-alerts",{"title":2364,"path":2365,"stem":2366,"deprecated":8},"发起分账或分账回退","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcreate-or-reverse-profit-share","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F31.create-or-reverse-profit-share",{"title":2368,"path":2369,"stem":2370,"deprecated":8},"查询分账结果","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fquery-profit-share","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F32.query-profit-share",{"title":2372,"path":2373,"stem":2374,"deprecated":8},"更新 SDK 订单","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fsdk-update-order","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F33.sdk-update-order",{"title":2376,"path":2377,"stem":2378,"deprecated":8},"Apple Pay 商户验证","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fvalidate-apple-pay-merchant","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F34.validate-apple-pay-merchant",{"title":2380,"path":2381,"stem":2382,"deprecated":8},"检查 Google Pay PAN_ONLY token","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fendpoints\u002Fcheck-google-pay-pan-only","zh\u002Fpayments\u002F04.api-reference\u002F01.endpoints\u002F35.check-google-pay-pan-only",{"title":2384,"deprecated":8,"path":2385,"stem":2386,"children":2387,"page":111},"Webhook 回调","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks",[2388,2392,2396,2400,2404,2408,2412,2416,2420,2424,2428,2432,2436],{"title":2389,"path":2390,"stem":2391,"deprecated":8},"欺诈预警","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Ffraud-alert","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F01.fraud-alert",{"title":2393,"path":2394,"stem":2395,"deprecated":8},"Ethoca 预警通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fethoca-alert-created","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F02.ethoca-alert-created",{"title":2397,"path":2398,"stem":2399,"deprecated":8},"支付结果通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fpayment-result","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F03.payment-result",{"title":2401,"path":2402,"stem":2403,"deprecated":8},"订阅扣款通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fsubscription-payment","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F04.subscription-payment",{"title":2405,"path":2406,"stem":2407,"deprecated":8},"预授权、请款与撤销通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fauthorization-capture","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F05.authorization-capture",{"title":2409,"path":2410,"stem":2411,"deprecated":8},"分账结果通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fprofit-share-result","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F06.profit-share-result",{"title":2413,"path":2414,"stem":2415,"deprecated":8},"保存支付方式结果通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fpayment-method-result","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F07.payment-method-result",{"title":2417,"path":2418,"stem":2419,"deprecated":8},"Ethoca 报备状态通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fethoca-enrollment-changed","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F08.ethoca-enrollment-changed",{"title":2421,"path":2422,"stem":2423,"deprecated":8},"RDR 报备状态通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frdr-enrollment-changed","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F09.rdr-enrollment-changed",{"title":2425,"path":2426,"stem":2427,"deprecated":8},"退款结果通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frefund-result","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F10.refund-result",{"title":2429,"path":2430,"stem":2431,"deprecated":8},"退款审核拒绝通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Frefund-audit-rejected","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F11.refund-audit-rejected",{"title":2433,"path":2434,"stem":2435,"deprecated":8},"拒付预警通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fchargeback-alert-created","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F12.chargeback-alert-created",{"title":2437,"path":2438,"stem":2439,"deprecated":8},"拒付状态变化通知","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fwebhooks\u002Fchargeback-status-changed","zh\u002Fpayments\u002F04.api-reference\u002F02.webhooks\u002F13.chargeback-status-changed",{"title":2441,"path":2442,"stem":2443,"deprecated":8},"响应码","\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes","zh\u002Fpayments\u002F04.api-reference\u002F03.response-codes",{"title":2445,"deprecated":8,"path":2446,"stem":2447,"children":2448,"page":111},"转账","\u002Fzh\u002Ftransfer","zh\u002Ftransfer",[2449,2471],{"title":2450,"path":2451,"stem":2452,"children":2453,"deprecated":8},"接入指南","\u002Fzh\u002Ftransfer\u002Fget-started","zh\u002Ftransfer\u002F01.get-started\u002F01.index",[2454,2456,2459,2463,2467],{"title":2455,"path":2451,"stem":2452,"deprecated":8},"概览",{"title":2149,"path":2457,"stem":2458,"deprecated":8},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing","zh\u002Ftransfer\u002F01.get-started\u002F03.request-signing",{"title":2460,"path":2461,"stem":2462,"deprecated":8},"集成流程","\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow","zh\u002Ftransfer\u002F01.get-started\u002F04.integration-flow",{"title":2464,"path":2465,"stem":2466,"deprecated":8},"测试与上线","\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live","zh\u002Ftransfer\u002F01.get-started\u002F05.testing-and-go-live",{"title":2468,"path":2469,"stem":2470,"deprecated":8},"变更记录","\u002Fzh\u002Ftransfer\u002Fget-started\u002Fchange-log","zh\u002Ftransfer\u002F01.get-started\u002F08.change-log",{"title":2472,"deprecated":8,"path":2473,"stem":2474,"children":2475},"接口参考","\u002Fzh\u002Ftransfer\u002Fapi-reference","zh\u002Ftransfer\u002F04.api-reference\u002F01.index",[2476,2477,2553,2562],{"title":2455,"path":2473,"stem":2474,"deprecated":8},{"title":2239,"deprecated":8,"path":2478,"stem":2479,"children":2480,"page":111},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints",[2481,2485,2489,2493,2497,2501,2505,2509,2513,2517,2521,2525,2529,2533,2537,2541,2545,2549],{"title":2482,"path":2483,"stem":2484,"deprecated":8},"打款方式查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfer-methods","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F01.query-transfer-methods",{"title":2486,"path":2487,"stem":2488,"deprecated":8},"收款方必填字段查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-required-fields","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F02.query-required-fields",{"title":2490,"path":2491,"stem":2492,"deprecated":8},"收款方添加","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fcreate-beneficiary","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F03.create-beneficiary",{"title":2494,"path":2495,"stem":2496,"deprecated":8},"收款方详情查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fget-beneficiary-details","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F04.get-beneficiary-details",{"title":2498,"path":2499,"stem":2500,"deprecated":8},"打款方新增","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fcreate-payer","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F05.create-payer",{"title":2502,"path":2503,"stem":2504,"deprecated":8},"通过收款方ID发起打款","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Finitiate-transfer-by-beneficiary-id","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F06.initiate-transfer-by-beneficiary-id",{"title":2506,"path":2507,"stem":2508,"deprecated":8},"打款单笔查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfer","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F08.query-transfer",{"title":2510,"path":2511,"stem":2512,"deprecated":8},"打款批量查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-transfers","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F09.query-transfers",{"title":2514,"path":2515,"stem":2516,"deprecated":8},"打款凭证查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdownload-transfer-voucher","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F10.download-transfer-voucher",{"title":2518,"path":2519,"stem":2520,"deprecated":8},"收款方列表查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Flist-beneficiaries","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F11.list-beneficiaries",{"title":2522,"path":2523,"stem":2524,"deprecated":8},"收款方编辑","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fupdate-beneficiary","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F12.update-beneficiary",{"title":2526,"path":2527,"stem":2528,"deprecated":8},"收款方删除","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdelete-beneficiary","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F13.delete-beneficiary",{"title":2530,"path":2531,"stem":2532,"deprecated":8},"打款方查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-payer","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F14.query-payer",{"title":2534,"path":2535,"stem":2536,"deprecated":8},"打款方编辑","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fupdate-payer","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F15.update-payer",{"title":2538,"path":2539,"stem":2540,"deprecated":8},"打款方删除","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fdelete-payer","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F16.delete-payer",{"title":2542,"path":2543,"stem":2544,"deprecated":8},"账户币种查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-account-currencies","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F17.query-account-currencies",{"title":2546,"path":2547,"stem":2548,"deprecated":8},"账户详情查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-account-details","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F18.query-account-details",{"title":2550,"path":2551,"stem":2552,"deprecated":8},"汇率查询","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Fquery-exchange-rate","zh\u002Ftransfer\u002F04.api-reference\u002F01.endpoints\u002F19.query-exchange-rate",{"title":2554,"deprecated":8,"path":2555,"stem":2556,"children":2557,"page":111},"回调通知","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fwebhooks","zh\u002Ftransfer\u002F04.api-reference\u002F02.webhooks",[2558],{"title":2559,"path":2560,"stem":2561,"deprecated":8},"打款回调","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fwebhooks\u002Ftransfer-result","zh\u002Ftransfer\u002F04.api-reference\u002F02.webhooks\u002F01.transfer-result",{"title":2563,"path":2564,"stem":2565,"deprecated":8},"枚举值说明","\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes","zh\u002Ftransfer\u002F04.api-reference\u002F03.response-codes",{"title":2567,"deprecated":8,"path":2568,"stem":2569,"children":2570,"page":111},"发卡","\u002Fzh\u002Fissuing","zh\u002Fissuing",[2571,2579],{"title":2138,"path":2572,"stem":2573,"children":2574,"deprecated":8},"\u002Fzh\u002Fissuing\u002Fget-started","zh\u002Fissuing\u002F01.get-started\u002F01.index",[2575,2576],{"title":2455,"path":2572,"stem":2573,"deprecated":8},{"title":2145,"path":2577,"stem":2578,"deprecated":8},"\u002Fzh\u002Fissuing\u002Fget-started\u002Fsetup","zh\u002Fissuing\u002F01.get-started\u002F02.setup",{"title":2472,"path":2580,"stem":2581,"children":2582,"deprecated":8},"\u002Fzh\u002Fissuing\u002Fapi-reference","zh\u002Fissuing\u002F04.api-reference\u002F01.index",[2583,2585,2656,2660],{"title":2584,"path":2580,"stem":2581,"deprecated":8},"接口说明",{"title":2239,"deprecated":8,"path":2586,"stem":2587,"children":2588,"page":111},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints",[2589,2593,2597,2601,2605,2609,2613,2617,2621,2625,2629,2633,2637,2641,2645,2648,2652],{"title":2590,"path":2591,"stem":2592,"deprecated":8},"创建卡片","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcreate-card","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F01.create-card",{"title":2594,"path":2595,"stem":2596,"deprecated":8},"操作卡片","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Foperate-card","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F02.operate-card",{"title":2598,"path":2599,"stem":2600,"deprecated":8},"卡片充值","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fdeposit-card","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F03.deposit-card",{"title":2602,"path":2603,"stem":2604,"deprecated":8},"卡片提现","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Freturn-card-balance","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F04.return-card-balance",{"title":2606,"path":2607,"stem":2608,"deprecated":8},"查询卡片操作记录","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-operate-record-list","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F05.get-operate-record-list",{"title":2610,"path":2611,"stem":2612,"deprecated":8},"查询卡片基础信息","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-basic-info","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F06.get-basic-info",{"title":2614,"path":2615,"stem":2616,"deprecated":8},"查询卡片余额","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-balance-info","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F07.get-balance-info",{"title":2618,"path":2619,"stem":2620,"deprecated":8},"查询卡片敏感信息","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fget-sensitive-info","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F08.get-sensitive-info",{"title":2622,"path":2623,"stem":2624,"deprecated":8},"创建持卡人","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcreate-cardholder","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F09.create-cardholder",{"title":2626,"path":2627,"stem":2628,"deprecated":8},"更新持卡人","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fupdate-cardholder","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F10.update-cardholder",{"title":2630,"path":2631,"stem":2632,"deprecated":8},"查询持卡人列表","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-cardholders","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F12.query-cardholders",{"title":2634,"path":2635,"stem":2636,"deprecated":8},"查询地区列表","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fregion-list","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F13.region-list",{"title":2638,"path":2639,"stem":2640,"deprecated":8},"查询城市列表","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fcity-list","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F14.city-list",{"title":2642,"path":2643,"stem":2644,"deprecated":8},"查询手机区号列表","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fmobile-area-code-list","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F15.mobile-area-code-list",{"title":2300,"path":2646,"stem":2647,"deprecated":8},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-transaction-records","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F16.query-transaction-records",{"title":2649,"path":2650,"stem":2651,"deprecated":8},"查询 3DS 记录","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Fquery-3ds-records","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F17.query-3ds-records",{"title":2653,"path":2654,"stem":2655,"deprecated":8},"查询卡产品","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fendpoints\u002Flist-card-products","zh\u002Fissuing\u002F04.api-reference\u002F02.endpoints\u002F18.list-card-products",{"title":2657,"path":2658,"stem":2659,"deprecated":8},"WEBHOOK 说明","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhook-description","zh\u002Fissuing\u002F04.api-reference\u002F03.webhook-description",{"title":2661,"deprecated":8,"path":2662,"stem":2663,"children":2664,"page":111},"事件推送","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhooks","zh\u002Fissuing\u002F04.api-reference\u002F06.webhooks",[2665,2669,2673],{"title":2666,"path":2667,"stem":2668,"deprecated":8},"卡操作事件","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-operation-event","zh\u002Fissuing\u002F04.api-reference\u002F06.webhooks\u002F01.card-operation-event",{"title":2670,"path":2671,"stem":2672,"deprecated":8},"卡交易事件","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-transaction-event","zh\u002Fissuing\u002F04.api-reference\u002F06.webhooks\u002F02.card-transaction-event",{"title":2674,"path":2675,"stem":2676,"deprecated":8},"3DS 事件","\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhooks\u002Fcard-threeds-event","zh\u002Fissuing\u002F04.api-reference\u002F06.webhooks\u002F03.card-threeds-event",{"title":2678,"deprecated":8,"path":2679,"stem":2680,"children":2681,"page":111},"账户","\u002Fzh\u002Faccount","zh\u002Faccount",[2682,2690],{"title":2138,"path":2683,"stem":2684,"children":2685,"deprecated":8},"\u002Fzh\u002Faccount\u002Fget-started","zh\u002Faccount\u002F01.get-started\u002F01.index",[2686,2687],{"title":2455,"path":2683,"stem":2684,"deprecated":8},{"title":2145,"path":2688,"stem":2689,"deprecated":8},"\u002Fzh\u002Faccount\u002Fget-started\u002Fsetup","zh\u002Faccount\u002F01.get-started\u002F02.setup",{"title":2472,"deprecated":8,"path":2691,"stem":2692,"children":2693,"page":111},"\u002Fzh\u002Faccount\u002Fapi-reference","zh\u002Faccount\u002F04.api-reference",[2694,2726],{"title":2239,"deprecated":8,"path":2695,"stem":2696,"children":2697,"page":111},"\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints",[2698,2702,2706,2710,2714,2718,2722],{"title":2699,"path":2700,"stem":2701,"deprecated":8},"创建 Global Account","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fcreate-global-account","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F01.create-global-account",{"title":2703,"path":2704,"stem":2705,"deprecated":8},"查询 Global Account 详情","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fget-global-account-details","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F02.get-global-account-details",{"title":2707,"path":2708,"stem":2709,"deprecated":8},"查询账户余额变动流水","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-transactions","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F03.query-account-transactions",{"title":2711,"path":2712,"stem":2713,"deprecated":8},"按交易单号查询账户流水","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-transactions-by-service-id","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F04.query-account-transactions-by-service-id",{"title":2715,"path":2716,"stem":2717,"deprecated":8},"查询账户余额","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-balance","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F05.query-account-balance",{"title":2719,"path":2720,"stem":2721,"deprecated":8},"查询账户余额总览","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fquery-account-balance-overview","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F06.query-account-balance-overview",{"title":2723,"path":2724,"stem":2725,"deprecated":8},"导出每日账户账单","\u002Fzh\u002Faccount\u002Fapi-reference\u002Fendpoints\u002Fexport-daily-statement","zh\u002Faccount\u002F04.api-reference\u002F01.endpoints\u002F07.export-daily-statement",{"title":2441,"path":2727,"stem":2728,"deprecated":8},"\u002Fzh\u002Faccount\u002Fapi-reference\u002Fresponse-codes","zh\u002Faccount\u002F04.api-reference\u002F03.response-codes",[2730,2733,2738,2741,2746,2751,2754,2759,2764,2769,2774,2779,2784,2789,2794,2799,2804,2809,2812,2817,2822,2827,2832,2837,2842,2847,2852,2855,2860,2863,2868,2873,2878,2881,2886,2891,2896,2901,2904,2909,2914,2919,2923,2928,2932,2937,2940,2944,2949,2954,2959,2964,2969,2974,2979,2984,2989,2993,2998,3003,3008,3013,3018,3022,3027,3032,3036,3040,3043,3048,3052,3057,3062,3066,3071,3075,3079,3083,3086,3091,3096,3101,3104,3109,3114,3118,3123,3128,3132,3137,3142,3147,3151,3154,3158,3162,3167,3172,3177,3182,3187,3192,3196,3201,3205,3209,3213,3217,3220,3224,3228,3232,3237,3242,3247,3252,3256,3259,3264,3269,3272,3277,3282,3287,3290,3294,3298,3303,3308,3312,3315,3319,3323,3327,3330,3334,3338,3342,3347,3351,3354,3359,3364,3369,3374,3377,3380,3383,3386,3389,3392,3395,3398,3401,3404,3407,3410,3413,3416,3419,3422,3425,3428,3431,3434,3437,3440,3443,3446,3449,3452,3455,3458,3461,3464,3467,3470,3473,3476,3479,3482,3485,3488,3491,3494,3497,3500,3503,3506,3509,3512,3515,3518,3521,3526,3531,3536,3541,3546,3551,3556,3561,3566,3571,3576,3581,3584,3589,3594,3599,3604,3609,3614,3619,3624,3627,3632,3635,3640,3645,3649,3653,3657,3661,3664,3668,3672,3676,3679,3682,3685,3689,3692,3696,3700,3705,3710,3714,3719,3723,3728,3733,3738,3743,3748,3753,3758,3763,3768,3772,3777,3782,3787,3792,3796,3799,3804,3809,3814,3819,3824,3827,3832,3837,3842,3846,3849,3853,3856,3859,3862,3865,3868,3871,3876,3879,3882,3885,3888,3891,3894,3897,3900,3903,3906,3909,3912,3915,3919,3923,3928,3933,3938,3941,3944,3949,3954,3959,3964,3969,3974,3979,3984,3989,3994,3999,4004,4009,4012,4017,4022,4026,4029,4033,4037,4041,4044,4049,4054,4059,4064,4068,4071,4074,4077,4080,4083,4086,4089,4092,4095,4098,4101,4104,4107,4110,4113,4116,4119,4122,4127,4132,4137,4142,4145,4148,4151,4154,4159,4164,4169,4174,4177,4181,4186,4191,4195,4198,4201,4204,4207,4210,4213,4216,4219,4224],{"id":2139,"title":2143,"titles":2731,"content":2732,"level":609},[],"面向商户与合作伙伴的收单接入指南和 API 参考。 使用 Onerway Payments 接受线上支付，准备 API 凭证，校验支付请求，并将你的服务端接入与收银台、Webhook、退款、争议处理和 API 参考页面串联起来。",{"id":2734,"title":2735,"titles":2736,"content":2737,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started#从这里开始","从这里开始",[2143],"接入准备 — 激活沙盒账户、获取 API 凭证、配置对应环境的 IP 白名单，并准备上线请求签名 — 生成 Payments API 请求所需的 signWebhook 通知 — 验签、应答并幂等处理支付通知，未收到通知时使用查询接口补偿支付场景 — 按保存支付方式、订阅与预授权了解概念、生命周期与通知，并对比各接入方式的参数差异支付方式 — 了解卡、钱包与本地支付方式在各接入方式下的支持情况，以及 Apple Pay、Google Pay 的接入准备与流程币种与金额校验 — 在创建支付请求前校验币种与金额格式收银台接口参考 — 查看创建收银台支付的接口契约",{"id":2146,"title":2145,"titles":2739,"content":2740,"level":609},[],"开通沙盒账户、获取 API 凭证并配置 IP 白名单，在正式上线前完成首笔测试交易。 接入 Onerway Payments 时，先激活沙盒账户、获取 API 凭证并配置沙盒 IP 白名单。在沙盒环境完成集成开发与测试后，再配置生产环境并上线。",{"id":2742,"title":2743,"titles":2744,"content":2745,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fsetup#接入步骤","接入步骤",[2145],"激活沙盒账户向 Onerway 技术支持提供注册邮箱和测试域名，收到邮件邀请后点击链接，商户账户即在沙盒中激活。通过 Web SDK 或 API 直连在自有页面展示 Apple Pay 按钮的商户，需为对应的测试与生产域名完成 Apple 域名验证（收银台为 Onerway 托管页面，无需此步骤），见 Apple Pay 接入准备。通过 API 直连接入 Google Pay 时，需完成上线前网站报备；收银台和 Web SDK 无需报备。获取凭证登录商户后台，获取以下 API 凭证，供服务端调用 API 时使用。凭证后台路径直达链接merchantNo设置 → 用户信息沙盒 · 生产appId设置 → 支付 → 应用列表沙盒 · 生产secret开发者 → API 凭证沙盒 · 生产请将 secret 保存在服务端，切勿暴露在客户端代码、移动端安装包或版本控制系统中。配置 IP 白名单首次从服务端调用沙盒 API 前，必须将服务端使用的所有公网出口 IP 地址加入沙盒 IP 白名单。登录沙盒商户后台，在 开发者 → IP 白名单中添加这些地址。此处填写服务端的出口 IP，不要填写客户设备或浏览器访问网站时使用的 IP。沙盒和生产环境的 IP 白名单需要分别配置。上线前，必须在生产商户后台添加生产服务端使用的所有公网出口 IP 地址。即使两个环境的出口 IP 相同，也需分别添加。环境配置时机后台入口沙盒环境首次从服务端调用沙盒 API 前沙盒 IP 白名单生产环境首次从服务端调用生产 API 前生产 IP 白名单启用 IP 白名单后，请求来源 IP 不在对应环境的白名单中时，请求可能被拒绝。构建与测试配置沙盒 IP 白名单后，使用沙盒凭证开发集成，验证所有支付流程、异常处理和 Webhook 回调。切换至生产环境 API 地址和凭证前，必须将生产服务端的公网出口 IP 加入生产 IP 白名单。同时完成所用支付方式的接入要求，例如 Apple Pay 域名验证或 Google Pay 网站报备。",{"id":2747,"title":2748,"titles":2749,"content":2750,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fsetup#下一步","下一步",[2145],"请求签名 — 了解 Onerway 如何通过签名鉴权，以及如何生成 sign币种与金额校验 — 在创建支付请求前校验 orderCurrency、orderAmount 和支付方式限额沙盒测试 — 使用沙盒测试卡验证成功、失败、订阅和 token 支付场景",{"id":2150,"title":2149,"titles":2752,"content":2753,"level":609},[],"了解 Onerway 如何通过请求签名对 API 请求进行身份鉴权、如何生成 sign 字段，以及如何验签 webhook 通知。 Onerway 依赖 sign 字段对 API 请求进行身份鉴权。商户服务端需使用对应环境的密钥 (SECRET)，根据请求报文动态计算签名 (sign)；严禁在前端、移动端或公开的代码仓库中暴露 SECRET。 从服务端调用 API 前，必须完成对应环境的 IP 白名单配置。沙盒和生产环境需分别配置。",{"id":2755,"title":2756,"titles":2757,"content":2758,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#签名规则","签名规则",[2149],"生成 sign 时，请按以下顺序处理请求参数： 排除 sign 字段。排除值为 null、undefined 和空字符串的字段。若字段值为对象 (Object) 或数组 (Array)，将其序列化为紧凑的 JSON 字符串（无多余空格或换行）；嵌套结构的序列化规则见对象和数组字段转换。按字段名的 ASCII 码升序排列。仅将排序后的字段值直接拼接，不要拼接字段名、等号 (=)、与号 (&) 或任何其他分隔符；拼接后的字符串称为 Canonical String。在 Canonical String 末尾追加 SECRET。对最终的字符串进行 SHA-256 哈希计算，并将结果转换为小写的十六进制字符串。 非字符串标量参与拼接时：布尔值转为 true \u002F false；数字转为十进制字符串，不含多余尾零或科学计数法（例如 1.10 拼接为 1.1）。",{"id":2760,"title":2761,"titles":2762,"content":2763,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#对象和数组字段转换","对象和数组字段转换",[2149],"对象或数组字段需要序列化为紧凑的 JSON 字符串： {\n \"billingInformation\": {\n \"country\": \"US\",\n \"email\": \"customer@test.com\"\n }\n} 转换后参与签名并发送： {\n \"billingInformation\": \"{\\\"country\\\":\\\"US\\\",\\\"email\\\":\\\"customer@test.com\\\"}\"\n} 嵌套字段需要先转换内层，再转换外层。例如 txnOrderMsg.products 是数组，最终会作为 txnOrderMsg 字符串里的 JSON 字符串： {\n \"txnOrderMsg\": \"{\\\"appId\\\":\\\"replace_with_app_id\\\",\\\"products\\\":\\\"[{\\\\\\\"currency\\\\\\\":\\\\\\\"USD\\\\\\\",\\\\\\\"name\\\\\\\":\\\\\\\"test product\\\\\\\",\\\\\\\"num\\\\\\\":\\\\\\\"1\\\\\\\",\\\\\\\"price\\\\\\\":\\\\\\\"1\\\\\\\"}]\\\",\\\"returnUrl\\\":\\\"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\\\"}\"\n}",{"id":2765,"title":2766,"titles":2767,"content":2768,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#请求示例","请求示例",[2149],"原始请求可以保留对象结构，sign 字段为空： {\n \"merchantNo\": \"replace_with_merchant_no\",\n \"merchantTxnId\": \"replace_with_unique_transaction_id\",\n \"merchantTxnTime\": \"2026-04-24 15:37:39\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"billingInformation\": {\n \"country\": \"US\",\n \"email\": \"customer@test.com\",\n \"province\": \"CA\"\n },\n \"txnOrderMsg\": {\n \"appId\": \"replace_with_app_id\",\n \"products\": [\n {\n \"currency\": \"USD\",\n \"name\": \"test product\",\n \"num\": \"1\",\n \"price\": \"1\"\n }\n ],\n \"returnUrl\": \"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\"\n },\n \"productType\": \"CARD\",\n \"subProductType\": \"DIRECT\",\n \"txnType\": \"SALE\",\n \"sign\": null\n} 发送前应把对象字段转换为字符串，并填入计算后的 sign： {\n \"billingInformation\": \"{\\\"country\\\":\\\"US\\\",\\\"email\\\":\\\"customer@test.com\\\",\\\"province\\\":\\\"CA\\\"}\",\n \"merchantNo\": \"replace_with_merchant_no\",\n \"merchantTxnId\": \"replace_with_unique_transaction_id\",\n \"merchantTxnTime\": \"2026-04-24 15:37:39\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"productType\": \"CARD\",\n \"sign\": \"replace_with_calculated_signature\",\n \"subProductType\": \"DIRECT\",\n \"txnOrderMsg\": \"{\\\"appId\\\":\\\"replace_with_app_id\\\",\\\"products\\\":\\\"[{\\\\\\\"currency\\\\\\\":\\\\\\\"USD\\\\\\\",\\\\\\\"name\\\\\\\":\\\\\\\"test product\\\\\\\",\\\\\\\"num\\\\\\\":\\\\\\\"1\\\\\\\",\\\\\\\"price\\\\\\\":\\\\\\\"1\\\\\\\"}]\\\",\\\"returnUrl\\\":\\\"https:\u002F\u002Fdevelopers.onerway.com\u002Fexample-return\\\"}\",\n \"txnType\": \"SALE\"\n} 最终请求体可以按字段名排序，便于排查；签名是否正确仅取决于签名规则中的排序和拼接结果。",{"id":2770,"title":2771,"titles":2772,"content":2773,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#签名算例","签名算例",[2149],"用以下最小请求和示例密钥 example_secret 对拍你的实现： {\n \"merchantNo\": \"demo_merchant_no\",\n \"merchantTxnId\": \"demo_txn_id_001\",\n \"orderAmount\": \"1\",\n \"orderCurrency\": \"USD\",\n \"sign\": null\n} Canonical String: demo_merchant_nodemo_txn_id_0011USD\n待哈希字符串: demo_merchant_nodemo_txn_id_0011USDexample_secret\nsign: 8af506acd9322fcab9d676dd9b861512f194d9ab724eacdb358d90d087d9caac",{"id":2775,"title":2776,"titles":2777,"content":2778,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#代码示例","代码示例",[2149],"以下示例默认输入是商户服务端内存中的字典 (Map) 或对象 (Object)；若某个字段已经是 JSON 字符串，请确保它已按同样的由内向外规则完成内层转换。normalizeValue 的结果应同时用于签名和最终请求体；不要在计算签名后用不同的序列化方式重新构建对象或数组字段，这会导致网关验签失败。 \u003C?php\n\nfunction is_assoc_array(array $value): bool {\n if ($value === []) {\n return false;\n }\n return array_keys($value) !== range(0, count($value) - 1);\n}\n\nfunction normalize_nested($value) {\n if (!is_array($value)) {\n return $value;\n }\n\n if (!is_assoc_array($value)) {\n return array_map('normalize_nested', $value);\n }\n\n $result = [];\n foreach ($value as $key => $child) {\n $result[$key] = is_array($child)\n ? json_encode(normalize_nested($child), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)\n : $child;\n }\n return $result;\n}\n\nfunction normalize_value($value) {\n if ($value === null || $value === '') {\n return $value;\n }\n if (is_bool($value)) {\n return $value ? 'true' : 'false';\n }\n return is_array($value)\n ? json_encode(normalize_nested($value), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)\n : (string) $value;\n}\n\nfunction generate_signature(array $payload, string $secret): string {\n $normalized = [];\n foreach ($payload as $key => $value) {\n if ($key !== 'sign') {\n $normalized[$key] = normalize_value($value);\n }\n }\n\n ksort($normalized, SORT_STRING);\n\n $canonical = '';\n foreach ($normalized as $value) {\n if ($value !== null && $value !== '') {\n $canonical .= $value;\n }\n }\n\n return hash('sha256', $canonical . $secret);\n}\nimport com.fasterxml.jackson.core.JsonProcessingException;\nimport com.fasterxml.jackson.databind.ObjectMapper;\n\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.util.ArrayList;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.TreeMap;\n\npublic final class OnerwaySign {\n private static final ObjectMapper JSON = new ObjectMapper();\n\n private static Object normalizeNested(Object value) throws JsonProcessingException {\n if (value instanceof List\u003C?> list) {\n List\u003CObject> result = new ArrayList\u003C>();\n for (Object item : list) {\n result.add(normalizeNested(item));\n }\n return result;\n }\n\n if (value instanceof Map\u003C?, ?> map) {\n TreeMap\u003CString, Object> result = new TreeMap\u003C>();\n for (Map.Entry\u003C?, ?> entry : map.entrySet()) {\n Object child = entry.getValue();\n result.put(\n String.valueOf(entry.getKey()),\n child instanceof Map\u003C?, ?> || child instanceof List\u003C?>\n ? JSON.writeValueAsString(normalizeNested(child))\n : child\n );\n }\n return result;\n }\n\n return value;\n }\n\n private static String normalizeValue(Object value) throws JsonProcessingException {\n if (value == null) {\n return null;\n }\n if (value instanceof String text) {\n return text.isEmpty() ? null : text;\n }\n if (value instanceof Map\u003C?, ?> || value instanceof List\u003C?>) {\n return JSON.writeValueAsString(normalizeNested(value));\n }\n return String.valueOf(value);\n }\n\n public static String generateSignature(Map\u003CString, Object> payload, String secret) throws Exception {\n TreeMap\u003CString, String> normalized = new TreeMap\u003C>();\n for (Map.Entry\u003CString, Object> entry : payload.entrySet()) {\n if (!\"sign\".equals(entry.getKey())) {\n normalized.put(entry.getKey(), normalizeValue(entry.getValue()));\n }\n }\n\n StringBuilder canonical = new StringBuilder();\n for (String value : normalized.values()) {\n if (value != null && !value.isEmpty()) {\n canonical.append(value);\n }\n }\n\n MessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\n byte[] hash = digest.digest((canonical + secret).getBytes(StandardCharsets.UTF_8));\n\n StringBuilder hex = new StringBuilder();\n for (byte b : hash) {\n hex.append(String.format(\"%02x\", b));\n }\n return hex.toString();\n }\n}\npackage signing\n\nimport (\n \"crypto\u002Fsha256\"\n \"encoding\u002Fhex\"\n \"encoding\u002Fjson\"\n \"fmt\"\n \"sort\"\n)\n\nfunc normalizeNested(value any) any {\n switch typed := value.(type) {\n case []any:\n result := make([]any, len(typed))\n for i, item := range typed {\n result[i] = normalizeNested(item)\n }\n return result\n case map[string]any:\n result := map[string]any{}\n for key, child := range typed {\n switch child.(type) {\n case map[string]any, []any:\n bytes, _ := json.Marshal(normalizeNested(child))\n result[key] = string(bytes)\n default:\n result[key] = child\n }\n }\n return result\n default:\n return value\n }\n}\n\nfunc normalizeValue(value any) *string {\n if value == nil {\n return nil\n }\n\n switch typed := value.(type) {\n case string:\n if typed == \"\" {\n return nil\n }\n return &typed\n case map[string]any, []any:\n bytes, _ := json.Marshal(normalizeNested(value))\n text := string(bytes)\n return &text\n default:\n text := fmt.Sprint(typed)\n return &text\n }\n}\n\nfunc GenerateSignature(payload map[string]any, secret string) string {\n keys := make([]string, 0, len(payload))\n normalized := map[string]*string{}\n\n for key, value := range payload {\n if key == \"sign\" {\n continue\n }\n normalized[key] = normalizeValue(value)\n keys = append(keys, key)\n }\n\n sort.Strings(keys)\n\n canonical := \"\"\n for _, key := range keys {\n if value := normalized[key]; value != nil {\n canonical += *value\n }\n }\n\n sum := sha256.Sum256([]byte(canonical + secret))\n return hex.EncodeToString(sum[:])\n}\nimport { createHash } from 'node:crypto'\n\nfunction isPlainObject(value) {\n return Object.prototype.toString.call(value) === '[object Object]'\n}\n\nfunction normalizeNested(value) {\n if (Array.isArray(value)) {\n return value.map((item) => normalizeNested(item))\n }\n\n if (isPlainObject(value)) {\n const result = {}\n Object.keys(value).forEach((key) => {\n const child = value[key]\n result[key] = child !== null && typeof child === 'object'\n ? JSON.stringify(normalizeNested(child))\n : child\n })\n return result\n }\n\n return value\n}\n\nfunction normalizeValue(value) {\n if (value === null || value === undefined || value === '') {\n return value\n }\n if (typeof value === 'object') {\n return JSON.stringify(normalizeNested(value))\n }\n return String(value)\n}\n\nexport function generateSignature(payload, secret) {\n const canonical = Object.keys(payload)\n .filter((key) => key !== 'sign')\n .sort()\n .map((key) => normalizeValue(payload[key]))\n .filter((value) => value !== null && value !== undefined && value !== '')\n .join('')\n\n return createHash('sha256')\n .update(canonical + secret, 'utf8')\n .digest('hex')\n}",{"id":2780,"title":2781,"titles":2782,"content":2783,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#webhook-验签","Webhook 验签",[2149],"分账、分账回退，以及 Ethoca \u002F RDR 报备状态通知使用通知体中的 sign 验签；其他通知使用下述 X-Rh-Signature header。各通知的签名参与字段见对应 API Reference。",{"id":2785,"title":2786,"titles":2787,"content":2788,"level":667},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#分账及分账回退通知","分账及分账回退通知",[2149,2781],"使用当前环境的 SECRET，按签名规则计算收到的通知的签名，并与通知体中的 sign 比较。排除 sign 自身；relatedTxnId、relatedMerchantTxnId 参与签名，值为 null 时按签名规则排除。receivers 使用收到的原始 JSON 字符串，不要解析后重新序列化。完整字段见分账结果通知。 \u002Fprofit\u002Fquery 查询响应也返回 data.sign，但商户无需对查询响应验签。",{"id":2790,"title":2791,"titles":2792,"content":2793,"level":667},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#ethoca-rdr-报备状态通知","Ethoca \u002F RDR 报备状态通知",[2149,2781],"使用当前环境的 SECRET，按签名规则计算收到的通知的签名，并与通知体中的 sign 比较。排除 sign 自身，其余字段按通用规则参与签名；值为 null 或空字符串时按该规则排除。 id 在通知中为 JSON 数字，可能超出 JavaScript 安全整数范围。接收报文时应使用能无损保留大整数的解析方式，保留原始十进制值用于验签与应答；不要先转换为可能丢失精度的 JavaScript number。 完整字段和应答要求见 Ethoca 报备状态通知与 RDR 报备状态通知。Ethoca 预警通知仍使用下述 header 验签。",{"id":2795,"title":2796,"titles":2797,"content":2798,"level":667},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#其他通知","其他通知",[2149,2781],"Onerway 在通知 header X-Rh-Signature 中携带签名：逗号分隔的一项或多项 v1=\u003C签名>，v1 标识签名方案版本。存在多个同时启用的密钥时（例如密钥轮换期间），每个启用的密钥对应一项： X-Rh-Signature: v1=4bde57c3350c402ca8c3728697cd5d7dbd78c8f0313761607e7f538be3349c39, v1=6b543c2e887e20a98dd4629242dd60050a4cfdda3372cdc17b4422c8fe98d5fa 验签时，使用当前配置的 SECRET 按签名规则计算收到通知的签名，结果与 X-Rh-Signature 中任意一项一致即验签通过。字段选取与拼接沿用同一规则，另有两点差异： 额外排除该 webhook 在 API Reference 页面「验签范围」中标注为不参与验签的字段，即使通知返回了这些字段的值；未来新增的通知字段默认参与验签。对象和数组字段在通知中已按紧凑 JSON 字符串承载，直接使用收到的原始字符串值参与拼接，不要重新解析再序列化。 通知 body 仍返回 sign 字段，但它仅使用第一个启用的密钥计算，密钥轮换期间，它可能与你使用当前配置的 SECRET 计算出的签名不同。这些通知应使用 X-Rh-Signature 验签，不要依赖 body sign；使用 body sign 的通知按前述对应小节处理。",{"id":2800,"title":2801,"titles":2802,"content":2803,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#常见错误","常见错误",[2149],"对象 (Object) 或数组 (Array) 字段没有按最终发送形态序列化为紧凑的 JSON 字符串。txnOrderMsg.products 仍是数组对象，而不是 txnOrderMsg 字符串里的 JSON 字符串。发送了当前接口未定义的字段：网关按接口定义的字段集合计算签名，多发的字段只进入商户侧计算，导致签名不一致；字段结构与文档不符同理。请求环境不匹配，例如沙盒环境的 merchantNo \u002F SECRET 请求了生产环境 API，或生产环境凭证请求了沙盒环境 API。",{"id":2805,"title":2806,"titles":2807,"content":2808,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Frequest-signing#需要协助排查时","需要协助排查时",[2149],"请求验签失败时，请在商户服务端打印并提供以下信息： 签名计算前的最终拼接字符串 (Canonical String)。生成后的 sign。请求环境：沙盒环境或生产环境。请求接口和完整请求体。敏感信息可以脱敏，但不要修改参与签名字段的值。 Webhook 验签失败时，请提供收到的完整通知报文、对应 API Reference 指定的 body sign 或 X-Rh-Signature，以及你计算的 Canonical String 与签名结果。 html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .sizmJ, html code.shiki .sizmJ{--shiki-light:#E2931D;--shiki-default:#024C1A;--shiki-dark:#FFCB6B}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html pre.shiki code .szWXl, html code.shiki .szWXl{--shiki-light:#F76D47;--shiki-default:#024C1A;--shiki-dark:#F78C6C}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .ssWmh, html code.shiki .ssWmh{--shiki-light:#6182B8;--shiki-default:#023B95;--shiki-dark:#82AAFF}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}",{"id":2154,"title":2153,"titles":2810,"content":2811,"level":609},[],"接收并验签 Onerway 支付通知，正确应答与幂等处理，并在未收到通知时查询交易结果。 Onerway 将支付、绑卡、订阅、预授权与退款等交易的最终结果以 Webhook 通知推送到商户服务端。本页说明所有接入方式共用的通知处理契约；收银台、Web SDK 与 API 直连各自的接入指南只补充该接入方式涉及的通知类型与额外注意事项。 本页的投递、验签、应答与去重规则适用于下表所列通知。分账及分账回退通知使用 body sign 验签，其通知地址和应答方式见分账结果通知。 Ethoca \u002F RDR 报备状态通知也使用通知体中的 sign 验签，通知地址在商户后台配置，应答返回收到的 id。完整要求见 Ethoca 报备状态通知和 RDR 报备状态通知。",{"id":2813,"title":2814,"titles":2815,"content":2816,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#通知投递","通知投递",[2153],"Onerway 将通知以 HTTP POST 发送到创建交易时传入的 notifyUrl。报文结构按场景分别见： 通知场景支付结果通知普通支付成功、失败、超时关闭或取消保存支付方式结果通知保存支付方式（绑卡，txnType=BIND_CARD）的结果订阅扣款通知初始订阅、续费、变更、取消等订阅生命周期事件预授权、请款与撤销通知预授权（txnType=AUTH）、请款（txnType=CAPTURE）与撤销（txnType=VOID）结果退款结果通知退款结果（txnType=REFUND）退款审核拒绝通知Onerway 审核拒绝退款申请（notifyType=REFUND_AUDIT） 退款通知发送到原交易请求中的 notifyUrl。仅在 Onerway 审核拒绝退款申请时发送 REFUND_AUDIT。取消退款申请成功不发送通知，请处理申请或取消退款的响应。 支付结果通过 Webhook 或查询接口确认，returnUrl 跳转与客户端事件不作为支付成功的依据。申请退款（refundType=0）时，响应中的 respCode=20000 表示 Onerway 已受理请求，不代表退款成功。",{"id":2818,"title":2819,"titles":2820,"content":2821,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#验签","验签",[2153],"上表所列通知必须使用 header X-Rh-Signature 验签，不要依赖通知 body 中的 sign 字段：sign 仅使用第一个启用的密钥计算，密钥轮换期间，它可能与你使用当前配置的 SECRET 计算出的签名不同。验签规则与不参与验签的字段见请求签名。",{"id":2823,"title":2824,"titles":2825,"content":2826,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#应答与重试","应答与重试",[2153],"处理完成后必须返回 HTTP 200，使用 Content-Type: text\u002Fplain，并在响应体中原样返回该通知的 transactionId。未收到成功响应时，Onerway 以 30 分钟间隔重试，最多 3 次。",{"id":2828,"title":2829,"titles":2830,"content":2831,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#幂等去重","幂等去重",[2153],"单笔交易可能收到多次通知，必须按 transactionId 幂等去重：同一 transactionId 的重复通知只处理一次，但仍须正常应答。 绑卡、订阅并绑卡、预授权及后续请款或撤销等场景会产生多笔 transactionId 各不相同的关联通知，应各自幂等处理，并用 paymentId、contractId 等业务标识关联到同一支付意图或订阅合约。",{"id":2833,"title":2834,"titles":2835,"content":2836,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#状态判断","状态判断",[2153],"status 表示本次操作的结果，例如 S 成功、F 失败。paymentStatus 表示支付意图的状态，例如预授权成功后为 A、请款成功后为 S、撤销成功后为 N（已关闭）。 处理预授权、请款与撤销结果时，结合 paymentId 与 paymentStatus 判断资金处于冻结中、已扣款还是已释放。退款结果使用该笔退款的 transactionId 与 status 处理。各通知对应的字段和取值见其 API Reference 页面。",{"id":2838,"title":2839,"titles":2840,"content":2841,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#查询结果与通知不一致时如何处理","查询结果与通知不一致时如何处理",[2153],"以下规则通用于支付、退款等场景。当查询结果与已收到的 Webhook 不一致时，比较同一笔交易、同一次操作的结果： 查询返回的状态既不是成功（S）也不是失败（F），但 Webhook 已通知成功或失败时，以 Webhook 为准。其他情况以查询结果为准，包括查询已返回成功（S）或失败（F）的情况。",{"id":2843,"title":2844,"titles":2845,"content":2846,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#按需查询结果","按需查询结果",[2153],"收到成功（S）或失败（F）的 Webhook 后即可处理相应的支付或退款结果，不需要再查询确认。 对于支付，客户已返回商户页面但尚未收到 Webhook，或需要对账时，可按递增间隔查询支付结果，直到查询返回成功（S）、失败（F）或收到 Webhook。 对于退款，等待 Webhook 通知退款结果即可，无需持续轮询。需要核对进度或对账时，可使用查询退款记录，按退款交易号或原支付交易号查询。 支付结果查询接口按接入方式选择：收银台接入与 API 直连接入使用查询交易记录；Web SDK 接入使用创建支付时保存的 paymentId 调用查询支付记录。",{"id":2848,"title":2849,"titles":2850,"content":2851,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fwebhooks#上线前检查","上线前检查",[2153],"已对上表所列通知使用 X-Rh-Signature 验签，验签失败的通知不处理。对上表所列通知，处理后返回 HTTP 200 与 transactionId，且按 transactionId 幂等去重。Webhook 端点能接收所用场景涉及的全部通知类型。已参考沙盒测试在沙盒环境验证成功、失败与重试场景。",{"id":2158,"title":2157,"titles":2853,"content":2854,"level":609},[],"在创建支付请求前校验交易币种、金额精度和支付方式能力，避免因金额不合法被拒绝。 创建支付请求前，请在服务端一起校验 orderCurrency、orderAmount 和可用支付方式。orderCurrency 是三位 ISO 4217 交易币种；orderAmount 是按交易币种展示单位提交的正数十进制字符串，例如 USD 99.99 传 99.99，JPY 1000 可传 1000 或 1000.00。 不要用 JavaScript number、二进制浮点数或临时四舍五入后的值直接生成 orderAmount。建议内部用整数 minor unit 值或 decimal library 计算，确认金额后再格式化成 Onerway API 需要的字符串。",{"id":2856,"title":2857,"titles":2858,"content":2859,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#校验顺序","校验顺序",[2157],"校验币种代码orderCurrency 必须使用大写三位 ISO 4217 字母代码，例如 USD、EUR、JPY。不要传货币符号、国家代码、非官方缩写或大小写混用的值。如果某个 ISO 4217 代码是基金、贵金属、测试代码或“无币种”代码，例如 XAU、XTS、XXX，不要用于支付请求，除非 Onerway 已明确为你的商户、支付方式和交易场景开通。校验金额格式与精度orderAmount 必须是正数十进制字符串，以 . 作为小数分隔符。不要包含逗号、空格、货币符号、正负号或指数写法。Minor unit校验规则常见示例0必须表示整数金额；可以不带小数，也可以只带全 0 小数JPY 可传 1000 或 1000.00；不要传 4.122最多两位小数；整数金额可以不带 .00USD 可传 100、100.00、99.993最多三位小数；支付方式可能还有额外限制KWD 可传 10、10.500、0.001币种精度应来自你们维护的已开通币种配置，或来自 ISO 4217 minor unit 数据。不要把所有币种都固定成两位小数；零小数币种和三位小数币种需要单独处理。校验支付方式能力金额格式合法不代表交易一定可处理。支付方式、国家或地区、发卡机构、本地支付提供方、商户配置以及单笔限额都可能影响可用性。在展示币种或让客户输入金额前，建议先调用可用支付方式查询，按国家或地区、币种、金额和商户配置筛选可用方式。对本地支付方式，不要只按币种判断可用性。校验订单合计如果请求包含 txnOrderMsg.products、折扣、运费或其他订单明细，请用同一币种和同一精度计算合计，并确保明细金额与 orderAmount 一致。折扣项应按接口字段要求使用负数。",{"id":2861,"title":2766,"titles":2862,"content":743,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#请求示例",[2157],{"id":2864,"title":2865,"titles":2866,"content":2867,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#服务端校验示例","服务端校验示例",[2157],"下面的示例只演示金额格式校验。生产环境应从你们的商户配置读取已开通币种、minor unit、最小金额、最大金额和可用支付方式。 type CurrencyRule = {\n minorUnit: number\n minAmount?: string\n maxAmount?: string\n}\n\nconst enabledCurrencies: Record\u003Cstring, CurrencyRule> = {\n USD: { minorUnit: 2, minAmount: '0.01' },\n JPY: { minorUnit: 0, minAmount: '1' },\n KWD: { minorUnit: 3, minAmount: '0.001' }\n}\n\nfunction validateOrderAmount(amount: string, currency: string) {\n const code = currency.trim().toUpperCase()\n const rule = enabledCurrencies[code]\n\n if (!rule) {\n return { valid: false, reason: 'invalid_currency_code' }\n }\n\n if (!\u002F^\\d+(?:\\.\\d+)?$\u002F.test(amount)) {\n return { valid: false, reason: 'invalid_amount_format' }\n }\n\n const [, fraction = ''] = amount.split('.')\n const hasTooManyDecimals = fraction.length > rule.minorUnit\n const isWholeAmountWithZeroFraction = rule.minorUnit === 0 && \u002F^0*$\u002F.test(fraction)\n if (hasTooManyDecimals && !isWholeAmountWithZeroFraction) {\n return { valid: false, reason: 'invalid_minor_unit' }\n }\n\n if (\u002F^0+(?:\\.0+)?$\u002F.test(amount)) {\n return { valid: false, reason: 'amount_must_be_positive' }\n }\n\n return { valid: true, code, minorUnit: rule.minorUnit }\n} 前端可以根据币种动态限制小数位并格式化展示；最终仍应以服务端校验结果为准。不要在服务端请求前静默截断或四舍五入客户已经确认的金额。",{"id":2869,"title":2870,"titles":2871,"content":2872,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#常见拦截原因","常见拦截原因",[2157],"场景原因处理方式JPY 传 4.12零小数币种不能包含非零小数改为整数金额或全 0 小数，例如 1000 或 1000.00；否则可能返回 respCode=40000 和 Illegal parameter orderAmountUSD 传 99.999超过两位小数在客户确认金额前按业务规则处理精度KWD 被固定成两位小数三位小数币种被通用金额组件误处理输入控件和服务端校验都按币种配置动态设置精度使用 1,000.00API 金额不接受千分位分隔符提交前移除展示格式，只保留 decimal string支付方式不可用币种格式正确，但支付方式、地区或限额不匹配先查询可用支付方式，或联系 Onerway 确认商户配置",{"id":2874,"title":2875,"titles":2876,"content":2877,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Fcurrency-and-amount#参考资料","参考资料",[2157],"ISO 4217 currency codes — 核对三位字母代码、数字代码和 minor unitSIX Financial Data Standards — 下载 ISO 4217 List One可用支付方式查询 — 按交易条件筛选可用支付方式 html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s1VmB, html code.shiki .s1VmB{--shiki-light:#E53935;--shiki-default:#702C00;--shiki-dark:#F07178}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sO9CA, html code.shiki .sO9CA{--shiki-light:#FF5370;--shiki-default:#023B95;--shiki-dark:#FF9CAC}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .stp_H, html code.shiki .stp_H{--shiki-light:#90A4AE;--shiki-light-font-weight:inherit;--shiki-default:#024C1A;--shiki-default-font-weight:bold;--shiki-dark:#BABED8;--shiki-dark-font-weight:inherit}",{"id":2162,"title":2161,"titles":2879,"content":2880,"level":609},[],"使用沙盒测试卡验证卡支付、3DS 场景、失败响应、订阅、token 支付与钱包支付。 在沙盒环境中使用以下测试卡验证支付流程。测试卡仅适用于沙盒环境，不要在生产环境使用，也不要用真实持卡人信息替换这些测试值。 表格中的“响应”表示用于验证成功或失败分支的典型响应。实际接口返回仍以沙盒环境的当前配置为准。",{"id":2882,"title":2883,"titles":2884,"content":2885,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Ftesting#卡支付测试卡","卡支付测试卡",[2161],"使用这些卡号验证一次性扣款、3DS 认证流程、豁免场景、失败响应、订阅支付和 token 支付。 “3DS 测试场景”表示这些测试卡在沙盒中用于模拟的认证流程或豁免路径。Challenge flow 和 Frictionless flow 是 3DS 认证流程，Exemption 表示豁免场景；它们不是卡片本身的固定属性，也不代表同一国家\u002F地区的所有交易都会触发相同结果。 卡号国家和地区卡组织3DS 测试场景响应订阅保存支付方式4000020951595032🇺🇸 USChallenge flowSuccess4761344136141390🇸🇬 SGExemptionSuccess4000319872807223🇺🇸 USFrictionless flowSuccess4000128449498204🇺🇸 USFrictionless flowDo not honor4021937195658141🇬🇧 GBFrictionless flowInsufficient funds4000164166749263🇮🇳 INFrictionless flowSuspected fraud2221008123677736🇺🇸 USChallenge flowSuccess5333302221254276🇹🇷 TRExemptionSuccess5333418445863914🇲🇽 MXFrictionless flowSuccess5109486948867999🇺🇸 USFrictionless flowRestricted Card4998170000000015🇧🇷 BRChallenge flowSuccess4998170000000023🇧🇷 BRChallenge flowSuspected fraud",{"id":2887,"title":2888,"titles":2889,"content":2890,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Ftesting#apple-pay-沙盒测试","Apple Pay 沙盒测试",[2161],"在沙盒环境测试 Apple Pay 前，请先完成以下准备： 域名验证：通过 Web SDK 或 API 直连在自有页面展示 Apple Pay 按钮的，测试域名需先完成 Apple 域名验证（由商户自有 Apple Developer 账号或 Onerway 代为报备），见 Apple Pay 接入准备；收银台为 Onerway 托管页面，无需此步骤。Sandbox 测试账户：在 App Store Connect 中创建 sandbox 测试账户；测试设备退出 iCloud 账户后，使用该测试账户登录。设备国家与地区：将测试设备的国家与地区设置为 Apple Pay 沙盒支持、且与所用测试卡卡组织匹配的地区；中国大陆地区的 Wallet 仅支持银联测试卡。 测试卡由 Apple 提供并会整批更换，请直接使用 Apple Pay sandbox testing（中文版）页面上的最新测试卡，在测试设备的 Wallet 中手动添加。",{"id":2892,"title":2893,"titles":2894,"content":2895,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Ftesting#google-pay-测试卡","Google Pay 测试卡",[2161],"测试 Google Pay 前，请使用 Google 账号加入 Google Pay 测试卡套件群组，加入后该账号的 Google Pay 会自动展示一组测试卡，无需手动添加。",{"id":2897,"title":2898,"titles":2899,"content":2900,"level":615},"\u002Fzh\u002Fpayments\u002Fget-started\u002Ftesting#建议验证场景","建议验证场景",[2161],"使用预期响应为 Success 的测试卡验证支付创建和支付确认。验证服务端能正常接收支付 Webhook：使用通知 header X-Rh-Signature 完成验签，并在处理后返回确认响应，避免通知被重复投递。使用预期响应为失败原因的测试卡验证错误展示、重试逻辑和订单状态回滚。使用支持订阅的卡验证订阅支付。使用支持保存支付方式的卡验证保存支付方式（绑卡）和后续 token 支付。使用 Apple Pay \u002F Google Pay 测试卡验证钱包支付流程。",{"id":2171,"title":2175,"titles":2902,"content":2903,"level":609},[],"服务端创建收银台支付，重定向客户至 Onerway 托管页面完成支付，并通过 Webhook 确认支付结果。 收银台（Checkout）支付由服务端创建：调用创建收银台支付接口获取 redirectUrl，再将客户浏览器重定向到 Onerway 托管的收银台页面完成支付。支付页面、3DS 认证与 PCI 合规由 Onerway 承担；浏览器、设备和持卡人 IP 信息由收银台页面采集，商户服务端不要采集或传入。 开始前，先按接入准备获取 API 凭证，并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按请求签名生成 sign。上线前，参考沙盒测试在沙盒环境验证集成中使用的全部场景。 收银台使用 Onerway 的 Google Pay 能力，无需报备网站；网站报备仅适用于 API 直连接入。",{"id":2905,"title":2906,"titles":2907,"content":2908,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#接入流程","接入流程",[2175],"在服务端创建支付通过创建收银台支付创建交易。字段 txnOrderMsg 必须包含 returnUrl（同步返回地址）和 notifyUrl（Webhook 通知地址）；字段 products 中商品金额、折扣和运费合计必须等于 orderAmount。创建成功后交易状态为 U（未支付），响应返回字段 redirectUrl。重定向到收银台服务端将客户浏览器重定向到 redirectUrl。客户在托管页面选择支付方式并完成支付；需要 3DS 认证时由收银台页面引导完成，商户无需处理。处理支付返回客户完成支付后经 returnUrl 返回商户网站。同步返回只用于页面流转：建议在 returnUrl 上拼接商户订单号，客户返回时向其展示“处理中”，等待 Webhook 到达后再处理订单。最终支付结果以 Webhook 为准。",{"id":2910,"title":2911,"titles":2912,"content":2913,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#支付方式展示范围","支付方式展示范围",[2175],"收银台展示哪些支付方式由字段 productType 决定；实际交易处理方式还取决于 subProductType 和 txnType。 目标服务端输入只展示卡支付productType=CARD展示全部可用支付方式productType=ALL，由客户在收银台自行选择。锁定单一本地支付方式或钱包productType=ALL，并传入字段 lpmsInfo.lpmsType；收银台只展示该支付方式，Apple Pay、Google Pay 分别取 ApplePay、GooglePay。 各支付方式在收银台下的支持情况与接入准备见支付方式。",{"id":2915,"title":2916,"titles":2917,"content":2918,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#保存卡选项","保存卡选项",[2175],"传入稳定的字段 merchantCustId 后，收银台会向客户提供保存卡信息的选项；该选项不会默认选中，只有客户主动勾选并完成支付后才会保存卡。字段 subProductType 按场景传入 DIRECT、SUBSCRIBE 或 INSTALLMENT 即可，不需要为保存卡使用单独取值。后续支付继续传入同一个 merchantCustId，收银台会向该客户回显可用的已保存卡。 收银台接入需额外注意：订阅场景的客户标识通过外层 merchantCustId 传入；字段 subscription.merchantCustId 选填，如同时传入，两者必须一致。merchantCustId 的取值要求、保存支付方式结果通知与已保存 token 的查询、删除见保存支付方式。",{"id":2920,"title":2218,"titles":2921,"content":2922,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#订阅支付",[2175],"初始订阅在收银台完成：传入字段 subProductType =SUBSCRIBE 和字段 subscription（requestType=0），计费方式由字段 subscription.selfExecute 决定。续费与计划升降级由服务端通过 API 直连发起，收银台不参与。 托管订阅与自主管理订阅的选择、合约凭证、生命周期通知与升降级规则见订阅支付。",{"id":2924,"title":2925,"titles":2926,"content":2927,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#预授权","预授权",[2175],"传入字段 txnType =AUTH 时，收银台完成的是预授权：冻结客户卡上的订单金额，不立即扣款；需要 3DS 时由收银台页面引导完成。预授权成功后保存响应中的 transactionId 与 paymentId，后续请款或撤销由服务端调用预授权请款或撤销完成。 适用范围、请款与撤销的生命周期、通知、边界与状态判断见预授权与请款。",{"id":2929,"title":2226,"titles":2930,"content":2931,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#分账",[2175],"分账是平台模式下的能力：平台商户以收款子商户的 merchantNo 创建支付，并传入字段 paymentMethodOptions 在其中的 share 设置 profitShare=true，该笔支付才可参与分账；收银台的支付流程与普通支付一致。同时设置 profitShareRate 时，SALE 或 CAPTURE 成功后由 Onerway 自动分账；不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时，同时设置 profitShareNotifyUrl。paymentMethodOptions 按接口要求以 JSON 字符串提交。 自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见分账。",{"id":2933,"title":2934,"titles":2935,"content":2936,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fcheckout#确认支付结果","确认支付结果",[2175],"收银台支付的最终结果以 Webhook 为准：普通支付见支付结果通知，订阅见订阅扣款通知，预授权见预授权、请款与撤销通知；客户自选保存卡时，绑卡结果由保存支付方式结果通知单独承载。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 Webhook 通知。 收银台接入需额外注意：returnUrl 同步返回不保证附带交易参数，不要以回跳 URL 上的任何参数作为订单处理依据；客户已返回但未收到 Webhook 时，用查询交易记录补偿。交易状态以响应字段 status 与 Webhook 中的同名字段为准，完整取值见 API Reference。",{"id":2177,"title":2181,"titles":2938,"content":2939,"level":609},[],"服务端创建支付，使用 paymentId 初始化 Web SDK，并处理自定义按钮、钱包、外跳与最终结果确认。 Web SDK 接入分为两部分：服务端创建支付并保存订单与 paymentId 的映射，浏览器加载 SDK 并使用该 paymentId 创建 Checkout。secret、请求签名、客户身份映射和最终支付状态确认始终保留在服务端。 开始前，先按接入准备获取 API 凭证，并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按请求签名生成 sign。上线前，参考沙盒测试在沙盒环境验证集成中使用的全部场景。 Web SDK 使用 Onerway 的 Google Pay 能力，无需报备网站；网站报备仅适用于 API 直连接入。",{"id":2941,"title":2906,"titles":2942,"content":2943,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#接入流程",[2181],"服务端调用创建 SDK 交易，保存返回的 paymentId。浏览器加载与交易环境匹配的 CDN 脚本。使用 paymentId 创建 Checkout，先订阅事件，再挂载 Payment Element。Card、本地支付和其他自定义支付按钮调用 confirmPayment()；Apple Pay、Google Pay 等 SDK 自有按钮只监听 payment_result。客户端根据事件更新页面；服务端通过查询支付记录或支付 Webhook 确认最终状态。",{"id":2945,"title":2946,"titles":2947,"content":2948,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#在服务端创建支付","在服务端创建支付",[2181],"普通 Web SDK v4 支付应通过创建 SDK 交易传入 productType=ALL、subProductType=DIRECT 和 txnType=SALE。标准的一次性扣款示例省略了 billingInformation、shippingInformation、paymentMode 和 osType。 创建交易时，billingInformation 与 shippingInformation 均为可选。信息已具备时即可传入；初始下单省略且业务流程需要时，可以在确认支付前通过更新 SDK 订单补充。传入对象后，其内部字段原有的必填条件仍然生效。更新订单时，服务端应复用原下单的 merchantTxnId，并在客户确认支付前等待更新成功响应。 当前 Web SDK 的字段 txnOrderMsg只包含 returnUrl、products、appId、customerPlatform、periodValue 和 notifyUrl；每个字段是否必填及其适用条件以 API Reference 为准。商户服务端不要采集或传入浏览器、设备和持卡人 IP 字段，这些信息由 Web SDK 采集。 Web SDK 支付通常省略 paymentMode，无需区分桌面和移动浏览器。传入非 WEB 值时，必须同时传入 osType。 服务端只把创建支付响应中的 paymentId 传给浏览器。transactionId 可用于服务端订单关联，但不能替代 paymentId 初始化 SDK。响应仍会返回 redirectUrl，当前 Web SDK 初始化时不消费该字段。",{"id":2950,"title":2951,"titles":2952,"content":2953,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#加载-sdk","加载 SDK",[2181],"CDN 与 environment 必须匹配： 环境CDNenvironmentSandboxhttps:\u002F\u002Fsandbox-checkout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.jssandboxProductionhttps:\u002F\u002Fcheckout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.jsproduction，默认值 v4\u002Flatest 是 Production 正式推荐的长期地址。即使 environment 默认为 production，也建议显式传入，避免复制配置时混用环境。 \u003Cscript src=\"https:\u002F\u002Fcheckout-sdk.onerway.com\u002Fv4\u002Flatest\u002Fonerway.js\">\u003C\u002Fscript>\n\n\u003Cdiv id=\"onerway_checkout\">\u003C\u002Fdiv>\n\u003Cbutton id=\"pay_button\" type=\"button\">Pay now\u003C\u002Fbutton>",{"id":2955,"title":2956,"titles":2957,"content":2958,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#初始化订阅事件并挂载","初始化、订阅事件并挂载",[2181],"const checkout = await Onerway.createCheckout(paymentId, {\n environment: 'production',\n locale: 'en'\n})\n\nconst paymentElement = checkout.createPaymentElement()\n\npaymentElement.on('ready', (event) => {\n console.log(event.availablePaymentMethods)\n})\n\npaymentElement.on('loaderror', (event) => {\n console.error(event.error.code, event.error.message)\n})\n\ncheckout.on('payment_result', handlePaymentResult)\n\npaymentElement.mount('#onerway_checkout') 必须先订阅事件，再调用 mount()： ready.availablePaymentMethods 是当前订单、服务端配置和浏览器钱包能力共同决定的可用支付方式列表。不要把示例值当成固定枚举；钱包不可用时 SDK 会隐藏相应按钮。loaderror 只表示 Checkout 初始化失败。程序逻辑应判断 event.error.code，event.error.message 仅用于展示。公开的 code 只有两个：checkout_load_failed（首次加载支付方式失败，可让客户重新初始化）和 no_available_payment_methods（过滤后没有可展示的支付方式，检查服务端配置与 paymentMethod）。表单校验、支付接口失败、钱包取消和 3DS\u002F外跳异常不属于 loaderror，应从 confirmPayment() 返回值或 payment_result 处理。",{"id":2960,"title":2961,"titles":2962,"content":2963,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#配置-payment-element","配置 Payment Element",[2181],"config 的子字段均为可选，但商户应根据自己的支付方式、表单和品牌要求决定是否传入，不能假定所有业务都使用默认展示。配置在 paymentElement.mount() 时读取；修改后需要重新创建并挂载 Payment Element 才能生效。 字段类型默认值作用paymentMethodString[]不传支付方式显示白名单，只保留服务端实际返回且存在于数组中的方式showBillingAddressBooleantrue是否展示并校验账单地址表单displayCardholdernameBooleantrue是否展示并校验持卡人姓名输入框walletButtonsObject见下文配置 Apple Pay 和 Google Pay 官方按钮支持的外观checkoutThemeStringlightSDK 主题预设；当前公开主题只有 lightvariablesObject{}覆盖主题变量，建议优先使用stylesObject{}按 CSS selector 覆盖 SDK 样式，优先级最高customCssURLStringSDK 默认 CSS替换 SDK 基础样式表来源；variables 和 styles 仍然生效 例如，商户可以只展示当前业务接受的方式、隐藏 SDK 账单地址表单，并对 SDK 可控区域应用品牌样式： const checkout = await Onerway.createCheckout(paymentId, {\n environment: 'production',\n locale: 'en',\n config: {\n paymentMethod: ['CARD', 'DOKU_VA', 'GooglePay'],\n showBillingAddress: false,\n displayCardholdername: true,\n checkoutTheme: 'light',\n variables: {\n colorPrimary: '#2563eb',\n colorText: '#1a202c',\n borderRadius: '8px'\n },\n walletButtons: {\n googlePay: { type: 'pay', color: 'black', height: '44px' },\n applePay: { type: 'pay', color: 'black', height: '44px' }\n }\n }\n})",{"id":2965,"title":2966,"titles":2967,"content":2968,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#限制支付方式","限制支付方式",[2181,2961],"paymentMethod 只负责前端显示过滤，不会为商户开通支付方式： 传值行为不传展示服务端返回且当前设备可用的全部方式['CARD', 'FPX', 'GooglePay']只展示服务端也返回的 CARD、FPX 和 GooglePay[]不展示任何方式，并触发 loaderror；event.error.code 为 no_available_payment_methods 数组值必须与服务端返回的支付方式标识完全一致。数组顺序不控制展示顺序；实际顺序仍由服务端支付方式配置和 SDK 钱包区域决定。是否成功加载某种方式，最终以 ready.availablePaymentMethods 为准。",{"id":2970,"title":2971,"titles":2972,"content":2973,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#配置表单显示","配置表单显示",[2181,2961],"showBillingAddress: false 会隐藏账单地址并停止相应的前端校验，但不会修改 Create transaction 或 Update order 的服务端字段约束。需要账单信息的业务应在确认支付前自行采集并更新订单。displayCardholdername: false 会隐藏持卡人姓名并停止相应的前端校验。",{"id":2975,"title":2976,"titles":2977,"content":2978,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#配置钱包按钮","配置钱包按钮",[2181,2961],"字段默认值支持值或规则googlePay.typepaybook, buy, checkout, donate, order, pay, plain, subscribegooglePay.colorblackblack, whiteapplePay.typepayadd-money, book, buy, check-out, continue, contribute, donate, order, plain, reload, rent, subscribe, support, tip, top-up, payapplePay.colorblackblack, white, white-outlinegooglePay.width \u002F applePay.width100%CSS 尺寸字符串googlePay.height \u002F applePay.height44pxCSS 尺寸字符串googlePay.radius \u002F applePay.radius8pxCSS 尺寸字符串；Apple \u002F Google 平台可能限制最终外观 这些选项只调整 SDK 官方钱包按钮支持的外观，不会使当前设备不支持的钱包变为可用，也不能用 variables、styles 或自定义 CSS 强制覆盖平台控制的按钮外观。Apple Pay 的域名验证等接入准备见支付方式。",{"id":2980,"title":2981,"titles":2982,"content":2983,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#配置主题与样式","配置主题与样式",[2181,2961],"checkoutTheme 当前只支持 light。variables 是推荐的品牌定制方式。支持的常用变量包括 containerBackground、cardBackground、inputBackground、inputBrandBackground、aggregateHeaderBackground、dialogBackground、colorText、colorPrimary、colorDanger、fontFamily、fontSizeBase 和 borderRadius。fontSizeBase 支持 12px–24px，borderRadius 支持 0px–24px。styles 接收 CSS selector 到 CSS 属性对象的映射，例如 { '.onerway-checkout__input': { color: '#1a202c' } }，用于变量无法覆盖的局部样式。customCssURL 用于整体替换 SDK 基础样式表；之后仍可通过 variables 和 styles 覆盖。 主题和样式仅作用于 SDK 可控区域。历史配置 showPayButton 和 payButtonText 已不再支持并会被 SDK 忽略。",{"id":2985,"title":2986,"titles":2987,"content":2988,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#语言locale","语言（Locale）",[2181],"不传 locale 时，SDK 使用浏览器语言。显式传入的值或浏览器语言不受当前支付方式支持时，SDK 默认回退到英语 en。 普通支付方式支持以下 locale 取值（按字母序）： 代码语言代码语言ar阿拉伯语de德语en英语es西班牙语fi芬兰语fr法语it意大利语ja日语ko韩语nl荷兰语no挪威语pl波兰语pt葡萄牙语ru俄语sv瑞典语th泰语zh-cn简体中文zh-tw繁体中文 钱包使用自己的 locale 枚举和大小写，两个钱包的支持范围只有以下差异： 支持范围Locale两个钱包都支持ar, ca, cs, da, de, el, en, es, fi, fr, hr, id, it, ja, ko, ms, nl, no, pl, pt, ru, sk, sv, th, tr, uk, zh仅 Google Paybg, et, sl, sr仅 Apple Payhe, hi, hu, ro, vi, zh-TW 钱包遇到不支持的 locale 时同样回退到英语 en。例如，普通支付方式的简体中文为 zh-cn，钱包为 zh；普通支付方式的繁体中文为 zh-tw，钱包为 zh-TW。不要自行转换其他未列出的值。",{"id":2990,"title":2991,"titles":2992,"content":874,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#确认支付","确认支付",[2181],{"id":2994,"title":2995,"titles":2996,"content":2997,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#card本地支付与自定义按钮","Card、本地支付与自定义按钮",[2181,2991],"这些支付方式必须由商户按钮调用 confirmPayment()： document.querySelector('#pay_button').addEventListener('click', async () => {\n const result = await checkout.confirmPayment()\n handleConfirmResult(result)\n}) 不要重复创建 Checkout 或在重试时重新下单。可重试状态下，保留同一个 paymentId、Checkout 和 Payment Element。",{"id":2999,"title":3000,"titles":3001,"content":3002,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#apple-paygoogle-pay-等-sdk-自有按钮","Apple Pay、Google Pay 等 SDK 自有按钮",[2181,2991],"SDK 自有钱包按钮不能调用 confirmPayment()。用户点击 SDK 渲染的官方按钮后，只通过 payment_result 接收客户端结果： checkout.on('payment_result', (result) => {\n if (result.reason?.type === 'canceled') {\n \u002F\u002F 用户关闭钱包；恢复页面交互，不要把它映射为支付失败。\n return\n }\n\n renderClientResult(result)\n}) 钱包是否展示还取决于服务端配置、浏览器、设备和钱包能力。",{"id":3004,"title":3005,"titles":3006,"content":3007,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#在-app-内嵌-webview-中使用-google-pay","在 App 内嵌 WebView 中使用 Google Pay",[2181,2991],"Google Pay 是否可用由能力检测决定：条件不满足时 ready.availablePaymentMethods 不会包含 GooglePay，SDK 不渲染其按钮，属预期行为而非故障。 Android WebView 官方支持 Google Pay，但需宿主 App 配合：Android WebView 137+、Google Play services 25.18.30+，集成 androidx.webkit:webkit:1.14.0、声明 Chromium payment intent actions、启用 Payment Request API，并向 Google 发布 App integration；使用自定义 User-Agent 时需附加 GOOGLE_PAY_SUPPORTED。详见 Google 官方 WebView 指南。iOS 内嵌 WebView 不支持 Google Pay。宿主 App 不具备上述条件时，可将支付流程外跳系统浏览器完成，并确保支付后引导用户返回原 App。",{"id":3009,"title":3010,"titles":3011,"content":3012,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#paymentstatus-与-nextaction","paymentStatus 与 nextAction",[2181],"只有 paymentStatus === 'R' 时才会返回 nextAction： nextAction.typeSDK 行为商户处理PresentToShopperSDK 在当前页展示二维码、本地支付页等承接界面；此时还没有最终支付结果。保留当前 Checkout，等待 payment_result，不要再次调用 confirmPayment()。RedirectShopperSDK 即将跳转到外部支付页面；此时还没有最终支付结果。3DS 使用此流程。等待 Onerway 回跳到下单时的 returnUrl，再由服务端使用已保存的 paymentId 调用查询支付记录。 R 只表示支付流程需要继续，不代表成功或失败。nextAction 不会在 paymentStatus !== 'R' 时返回。 paymentStatus 的完整取值与定义见响应字段 paymentStatus。客户端状态只用于更新页面，不得据此发货、充值或记账： paymentStatus商户处理I、U、P、A非最终状态。订单保持待处理，不履约。R进入承接或外跳流程，读取 nextAction.type 并按上表处理。O允许继续支付或重试。保留同一个 paymentId、Checkout 和 Payment Element，不重新下单。S、N客户端收到的结果，仍需服务端确认后再完成订单或按订单规则展示。 没有形成支付状态的客户端异常通过 reason 描述： reason.type含义validation_error本地表单校验失败，未形成支付状态sdk_errorSDK 本地状态、配置或调用问题api_error支付接口或后端业务失败；reason.code 是后端原始 respCode，参见响应码canceled客户主动取消当前交互；reason.code 为 presenter_closed（关闭 SDK 承接的二维码或本地支付弹窗）、cvv_closed（关闭 Google Pay 授权后的二次 CVV 验证弹窗）或 wallet_canceled（取消 Apple Pay 或 Google Pay 官方授权窗） 客户取消时可能没有 paymentStatus，只有 reason.type === 'canceled'；取消前端流程不等于最终支付失败，恢复页面交互即可。",{"id":3014,"title":3015,"titles":3016,"content":3017,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#确认最终支付结果","确认最终支付结果",[2181],"confirmPayment() 返回值、payment_result 和 returnUrl 都只能驱动客户端页面流转，最终结果以 Webhook 为准：普通支付见支付结果通知，客户自选保存卡见保存支付方式结果通知，订阅见订阅扣款通知，预授权见预授权、请款与撤销通知。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 Webhook 通知。 Web SDK 接入需额外注意：服务端应保存商户订单与 paymentId 的映射；外跳回到 returnUrl 后不要相信 URL 中携带的支付状态，先把页面交互恢复为“正在确认”，未收到 Webhook 时由服务端使用 paymentId 调用查询支付记录补偿并返回业务结果。不要在浏览器日志、持久化数据或埋点中保存未脱敏的 rawResult、请求响应或支付数据。",{"id":3019,"title":3020,"titles":3021,"content":874,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#保存卡与订阅","保存卡与订阅",[2181],{"id":3023,"title":3024,"titles":3025,"content":3026,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#让客户主动选择是否保存卡","让客户主动选择是否保存卡",[2181,3020],"保持字段 subProductType =DIRECT 并传入稳定的字段 merchantCustId。SDK 会向客户展示保存卡选项，该选项不会默认选中；后续支付复用同一个 merchantCustId，SDK 会回显该客户的已保存卡，并在内部完成选卡和支付，客户端无需为该流程获取 tokenId。 Web SDK 接入需额外注意：subProductType=TOKEN 属于旧版 Web SDK 保存卡流程，不用于当前 Web SDK 的客户自选保存卡流程。merchantCustId 的取值要求、保存支付方式结果通知与已保存 token 的查询、删除见保存支付方式。",{"id":3028,"title":3029,"titles":3030,"content":3031,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#创建固定计划的初始订阅","创建固定计划的初始订阅",[2181,3020],"初始订阅支付使用 subProductType=SUBSCRIBE。服务端应维护允许购买的计划映射，并传入稳定、可读的字段 subscription.productName；计费方式由字段 subscription.selfExecute 决定。托管卡订阅可同时传入字段 subscription.bindCard =true，在订阅成功时保存客户卡，此时会收到两条独立通知。 托管订阅与自主管理订阅的选择、合约凭证、生命周期通知、续费与升降级、订阅并绑卡的双通知处理见订阅支付。",{"id":3033,"title":2925,"titles":3034,"content":3035,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#预授权",[2181],"传入字段 txnType =AUTH（subProductType 保持 DIRECT）时，本次支付是预授权：冻结客户卡上的订单金额，不立即扣款；SDK 集成流程与普通支付一致。预授权成功后保存响应中的 transactionId 与 paymentId，后续请款或撤销由服务端调用预授权请款或撤销完成。 适用范围、请款与撤销的生命周期、通知、边界与状态判断见预授权与请款。",{"id":3037,"title":2226,"titles":3038,"content":3039,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fsdk#分账",[2181],"分账是平台模式下的能力：平台商户以收款子商户的 merchantNo 创建支付，并传入字段 paymentMethodOptions 在其中的 share 设置 profitShare=true，该笔支付才可参与分账；SDK 集成流程与普通支付一致。同时设置 profitShareRate 时，SALE 或 CAPTURE 成功后由 Onerway 自动分账；不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时，同时设置 profitShareNotifyUrl。paymentMethodOptions 按接口要求以 JSON 字符串提交。 自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见分账。 html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sO9CA, html code.shiki .sO9CA{--shiki-light:#FF5370;--shiki-default:#023B95;--shiki-dark:#FF9CAC}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}",{"id":2184,"title":2188,"titles":3041,"content":3042,"level":609},[],"服务端直接调用创建直连交易接口提交卡信息或 token，自行处理 3DS 跳转，并通过 Webhook 确认支付、绑卡、订阅与预授权结果。 直连 API（Direct API）接入由商户自建支付页面并在服务端直接调用创建直连交易：卡信息或 token 由商户服务端提交，3DS 跳转由商户处理，最终结果通过 Webhook 确认。与收银台和 Web SDK 不同，卡数据会经过商户系统，因此本接入方式有 PCI DSS 合规门槛；换来的是完全自定义的支付体验，以及绑卡、token 支付、订阅续费和预授权等服务端场景的直接控制。Apple Pay、Google Pay 与本地支付方式在直连下的接入准备与专属流程见支付方式。",{"id":3044,"title":3045,"titles":3046,"content":3047,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#前提","前提",[2188],"开始前，先按接入准备获取 API 凭证，并将服务端的公网出口 IP 加入对应环境的白名单。每个请求都需按请求签名生成 sign。上线前，参考沙盒测试在沙盒环境验证集成中使用的全部场景。 API 直连接入另有 PCI DSS 合规门槛：在自建页面收集卡号、有效期和 CVC 并提交到 Onerway，商户必须持有有效的 PCI DSS 认证，通过 TLS 安全传输持卡人数据，不得存储 CVC 等敏感认证数据。不具备资质的商户请改用收银台接入或 Web SDK 接入，卡数据不会经过商户服务器。订阅续费和预授权请款不提交卡数据，不受此限制；卡 token 支付仍须提交 cardInfo.cvv，同样在 PCI DSS 范围内。",{"id":3049,"title":2906,"titles":3050,"content":3051,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#接入流程",[2188],"在服务端创建交易调用创建直连交易。交易模型由字段 productType、字段 subProductType 与字段 txnType 共同决定；商户自行采集卡信息的卡支付传 productType=CARD、subProductType=DIRECT、txnType=SALE，并在字段 cardInfo 中提交卡信息。字段 txnOrderMsg 必须包含 returnUrl（3DS 等跳转流程的同步回跳地址）与 notifyUrl（Webhook 通知地址）。与收银台不同，直连接入由商户自行采集浏览器、设备与持卡人 IP 信息（如 transactionIp）并传入 txnOrderMsg；各子字段的必填条件见字段 txnOrderMsg 的字段树。按响应状态处理跳转Onerway 判定是否需要 3DS 认证，同步响应的字段 status 可能直接是终态：响应处理status=S支付成功，等待 Webhook 后完成订单。status=R 且 actionType=RedirectURL将客户浏览器重定向到字段 redirectUrl 完成 3DS 认证或本地支付方式页面。其他取值按 status 与 respCode 处理失败或处理中状态，完整取值见 API Reference。原生 App 可在 WebView 中加载 redirectUrl，监听导航到 returnUrl 后关闭 WebView，再由服务端查询结果。承接同步回跳客户完成认证后经 returnUrl 返回商户页面。回跳只用于页面流转，不保证附带交易参数：建议在 returnUrl 上拼接商户订单号，客户返回时向其展示“处理中”，并由服务端通过查询交易记录核实，不要以回跳 URL 上的任何参数作为订单处理依据。以 Webhook 确认结果Onerway 将最终结果 POST 到 notifyUrl。确认支付结果一节说明验签、应答、重试与幂等处理。",{"id":3053,"title":3054,"titles":3055,"content":3056,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#绑卡与-token-支付","绑卡与 token 支付",[2188],"直连接入的保存支付方式（绑卡）流程是：服务端提交卡信息生成 token，随后用 tokenId 发起 token 支付，并按需查询或删除已保存记录。客户自选保存与服务端绑卡的选择、三类 token 的区分见保存支付方式。 生成卡 token：调用生成卡 token，提交卡信息与稳定的字段 merchantCustId，同时传入 notifyUrl 与 returnUrl。响应字段 status =R 时，将持卡人重定向到 redirectUrl 完成 3DS 认证。确认保存结果：以保存支付方式结果通知（txnType=BIND_CARD）为最终依据，仅当 status=S 时保存 tokenId；回跳到 returnUrl 与同步响应都不代表绑卡成功。也可调用查询已保存 token核对。发起 token 支付：调用创建直连交易，传入 subProductType=TOKEN 与字段 tokenInfo（tokenId 为已保存的卡 token，provider 不传），并在 cardInfo.cvv 提交客户本次输入的 CVC，同时传入绑卡时使用的 merchantCustId。token 支付同样可能返回 status=R 要求 3DS 认证，处理方式与接入流程一致。管理已保存 token：查询已保存 token返回每条绑定记录的 id 与 tokenId；客户要求删除卡时调用删除卡 token，入参是绑定记录的 id，不是 tokenId。 API 直连接入需额外注意：生成卡 token 与 token 支付都经手卡数据（token 支付须提交 cardInfo.cvv），两步都要求 PCI DSS。不具备资质的商户应让保存卡与复购都在收银台或 Web SDK 页面上完成。",{"id":3058,"title":3059,"titles":3060,"content":3061,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#订阅","订阅",[2188],"托管订阅与自主管理订阅的选择、合约凭证与生命周期通知见订阅支付。本节说明选定方案后在直连侧如何调用。三类请求都使用创建直连交易，传入 subProductType=SUBSCRIBE 与字段 subscription，并以字段 subscription.requestType 区分： requestType用途关键输入0初始订阅，建立合约cardInfo 或 tokenInfo、merchantCustId、selfExecute、计费周期与期数1自主管理订阅的本期扣款contractId、tokenId、merchantCustId、本期金额2托管订阅升级或降级contractId、tokenId、changeMode、prorationMode 初始订阅成功后，保存订阅扣款通知中的 contractId 与 tokenId。初始订阅也可以在收银台或 Web SDK 完成，后续扣款与更新仍走直连接口。 自主管理订阅续费（requestType=1）传入 contractId、tokenId、merchantCustId 与本期金额，不传卡信息，因此续费环节没有 PCI DSS 要求。 托管订阅升降级（requestType=2）使用已存储的 contractId 与 tokenId 发起，生效时机由字段 subscription.changeMode 决定，差价由 prorationMode 决定按剩余天数自动计算还是由商户通过 proration 提交。 API 直连接入需额外注意：托管卡订阅同时传入 subscription.bindCard=true 时，会收到保存支付方式结果通知与订阅扣款通知两条 transactionId 不同的通知，应各自幂等处理。",{"id":3063,"title":2925,"titles":3064,"content":3065,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#预授权",[2188],"预授权先冻结持卡人卡上的订单金额、暂不扣款。直连侧的 txnType=AUTH 适用于自行采集卡信息的卡支付和 token 支付（subProductType=DIRECT 或 TOKEN），不适用于本地支付方式、订阅或分期。 调用创建直连交易并传入 txnType=AUTH，其余参数与自行采集卡信息的卡支付或 token 支付相同；需要 3DS 时同样按 status=R 处理跳转。保存响应中的 transactionId 与 paymentId，后续请款或撤销调用预授权请款或撤销。 授权到请款或撤销的生命周期、通知、边界与状态判断见预授权与请款。",{"id":3067,"title":3068,"titles":3069,"content":3070,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#本地支付","本地支付",[2188],"本地支付方式与卡支付共用创建直连交易接口，差别只在参数组合与流程形态：传入 productType=LPMS 与字段 lpmsInfo（lpmsType 指定支付方式，其余子字段按方式条件必填），subProductType 一次性扣款传 DIRECT、订阅传 SUBSCRIBE；本地支付方式不支持 txnType=AUTH。方式清单与可用性查询、跳转与延迟到账的处理、方式专属参数与订阅形态见本地支付方式。 API 直连接入需额外注意：productType=ALL 属于收银台的聚合展示概念，直连接口不支持，商户需自建支付方式列表，并自行处理 status=R 下的客户侧动作与回跳承接。",{"id":3072,"title":2226,"titles":3073,"content":3074,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#分账",[2188],"分账是平台模式下的能力：平台商户以收款子商户的 merchantNo 创建支付，并传入字段 paymentMethodOptions 在其中的 share 设置 profitShare=true，该笔支付才可参与分账；其余参数与普通交易相同。同时设置 profitShareRate 时，SALE 或 CAPTURE 成功后由 Onerway 自动分账；不设置时由服务端通过 API 发起分账。需要接收自动分账及自动分账回退通知时，同时设置 profitShareNotifyUrl。paymentMethodOptions 按接口要求以 JSON 字符串提交。 自动分账与通过 API 发起分账的选择、结果通知、查询与分账回退见分账。",{"id":3076,"title":2934,"titles":3077,"content":3078,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#确认支付结果",[2188],"API 直连接入的最终结果以 Webhook 为准，按场景分别见支付结果通知、保存支付方式结果通知、订阅扣款通知与预授权、请款与撤销通知。验签、应答与重试、幂等去重、状态判断与查询补偿的通用规则见 Webhook 通知。 API 直连接入需额外注意：本接入方式同时使用四类通知，Webhook 端点必须能接收所用场景涉及的全部通知类型；绑卡、订阅并绑卡、预授权及后续请款或撤销会产生多笔 transactionId 各不相同的关联通知，用 paymentId、contractId 关联。同步响应可能直接返回终态 status=S，仍应等待 Webhook 后再完成订单；客户已回跳但未收到 Webhook 时，用查询交易记录补偿。",{"id":3080,"title":2849,"titles":3081,"content":3082,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fapi#上线前检查",[2188],"持有有效的 PCI DSS 认证，支付页面通过 TLS 传输且不存储 CVC。已处理 status=R 跳转与 returnUrl 回跳，回跳后由服务端查询而非信任 URL 参数。Webhook 端点已按 Webhook 通知完成上线前检查，且能接收绑卡、订阅、预授权等所用场景的全部通知类型。已保存的 tokenId、contractId 与 paymentId 以字符串存储并与客户或订单关联。沙盒验证已覆盖 3DS Challenge、3DS Frictionless 以及所用的绑卡、订阅、预授权与本地支付场景。",{"id":2191,"title":2195,"titles":3084,"content":3085,"level":609},[],"卡、钱包与本地支付方式三类支付方式的划分、各接入方式对它们的支持情况，以及展示支付方式前的可用性查询规则。 Onerway 支持的支付方式分为三类：卡（Visa、Mastercard 等卡组织的信用卡与借记卡）、钱包（Apple Pay、Google Pay）与本地支付方式（各国家或地区的银行转账、电子钱包、先买后付等）。 本栏目按支付方式说明接入准备、各接入方式的差异与专属流程。接入方式自身的流程见收银台接入、Web SDK 接入与 API 直连接入；保存支付方式、订阅、预授权等业务场景见支付场景。",{"id":3087,"title":3088,"titles":3089,"content":3090,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#各接入方式的支持情况","各接入方式的支持情况",[2195],"支付方式收银台Web SDKAPI 直连卡由收银台采集卡信息由 SDK 表单采集卡信息商户自行采集卡信息或以卡 token 支付，需 PCI DSSApple Pay 钱包收银台渲染按钮，域名验证由 Onerway 完成SDK 在商户页面内渲染按钮，商户域名需完成验证商户自建按钮，商户域名需完成验证；加密 token 由 Onerway 代解密或商户自解密Google Pay 钱包收银台渲染按钮SDK 在商户页面内渲染按钮商户自行加载 Google Pay JS SDK；加密 token 由 Onerway 代解密或商户自解密本地支付方式收银台展示可用方式，或锁定单一方式SDK 展示可用方式传 productType=LPMS 与 lpmsInfo，按 actionType 承接跳转、二维码或上下文展示 收银台与 Web SDK 路径下，钱包 token 与本地支付方式的跳转都由 Onerway 页面或 SDK 处理，商户系统不接触支付凭证；API 直连路径下，钱包与本地支付方式的参数差异见对应页面。",{"id":3092,"title":3093,"titles":3094,"content":3095,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#先查询可用支付方式","先查询可用支付方式",[2195],"支付方式是否可用取决于商户开通配置、客户所在国家或地区、币种与金额，不能只按币种判断。展示支付方式前，先调用查询可用支付方式按当前订单上下文筛选，并缓存结果、在配置变更时刷新；币种与金额的校验规则见币种与金额校验。 查询结果中钱包记录的 productType 为 LPMS，仅用于分类；通过 API 直连发起钱包支付时固定传 productType=CARD 与 subProductType=DIRECT。钱包记录同时返回前端初始化所需的配置：ApplePay 与 GooglePay 都可能返回 countryCode、subCardTypes、gatewayName 与 merchantId，gatewayMerchantId 只有 GooglePay 返回；取值方式见各钱包页面。",{"id":3097,"title":3098,"titles":3099,"content":3100,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods#通知中的支付方式","通知中的支付方式",[2195],"支付结果通知以 paymentMethod 返回本次实际扣款的支付方式，钱包交易可能另外返回 walletTypeName。这两个字段各自承载哪一层信息因钱包而异，需要识别具体支付方式时请同时读取；walletTypeName 有取值列表，paymentMethod 随实际扣款渠道返回、不预设取值范围。通知的验签、应答与状态判断见 Webhook 通知。",{"id":2197,"title":73,"titles":3102,"content":3103,"level":609},[],"Apple Pay 在收银台、Web SDK 与 API 直连下的接入差异、域名验证与账号配置、API 直连的会话流程与 token 提交方式、钱包订阅，以及常见问题。 Apple Pay 让客户用 Wallet 中已添加的卡，通过 Face ID 或 Touch ID 完成支付。收银台与 Web SDK 由 Onerway 渲染 Apple Pay 按钮并处理 token，商户只需完成域名报备；API 直连由商户自建按钮、驱动 ApplePaySession，并把 Apple 返回的加密 payment token 提交给 Onerway。",{"id":3105,"title":3106,"titles":3107,"content":3108,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#接入方式选择","接入方式选择",[73],"接入方式按钮与会话token 处理商户需要做的收银台收银台渲染并驱动不经过商户系统下单传 productType=ALL，或传 lpmsInfo.lpmsType=ApplePay 锁定 Apple PayWeb SDKSDK 在商户页面内渲染并驱动，外观见配置钱包按钮不经过商户系统完成域名验证；结果通过 payment_result 接收，见 SDK 自有按钮API 直连商户自建按钮与 ApplePaySessionOnerway 代解密或商户自解密完成域名验证；本页「API 直连接入」全部步骤 收银台是 Onerway 托管页面，域名已由 Onerway 向 Apple 报备，商户无需再做域名验证。Web SDK 与 API 直连在商户自己的域名下展示 Apple Pay 按钮，Apple 要求该域名先通过验证，见「接入准备」。 三种接入方式都要求网站全站 HTTPS、TLS 1.2 及以上，且 Onerway 商户账号已开通 Apple Pay。沙盒测试前提与测试卡见 Apple Pay 沙盒测试。",{"id":3110,"title":3111,"titles":3112,"content":3113,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#浏览器与设备支持","浏览器与设备支持",[73,3106],"Apple Pay on the Web 不再只限于 Safari： Safari，以及 iOS \u002F iPadOS 上的第三方浏览器（同为 WebKit 内核）：在设备上直接完成支付。Mac、Windows 与其他设备上的兼容第三方浏览器：页面显示二维码，客户用 iOS 18 \u002F iPadOS 18 及以上的 iPhone 或 iPad 扫码完成支付。API 直连商户需要使用 Apple Pay JS SDK 1.2.0 及以上提供的 \u003Capple-pay-button> 元素，CSS 方式渲染的按钮不支持非 Safari 浏览器。中国大陆：仅支持 iPhone \u002F iPad 上的 Safari，第三方浏览器不可用。 收银台与 Web SDK 由 Onerway 处理以上差异；API 直连商户按本页示例使用官方 SDK 与按钮元素即可获得同样的覆盖范围。以 Apple 官方说明为准。",{"id":3115,"title":2145,"titles":3116,"content":3117,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#接入准备",[73],"Apple 要求每个展示 Apple Pay 按钮的商户域名都完成域名验证，验证依附于某个 Apple Developer 账号的 Merchant ID。按谁持有 Merchant ID，接入准备分三个层级： 层级域名验证与商户验证token 解密适用默认商户自有 Apple Developer 账号：自建 Merchant ID、自行完成域名验证，用自持 Merchant Identity 证书向 Apple 请求 merchant sessionOnerway 代解密：支付处理证书由 Onerway 生成 CSR、商户上传到自己的 Merchant ID绝大多数商户商户自解密同默认商户自解密：自持支付处理证书，解密结果放入 cardInfo，须满足 PCI DSS已具备 PCI DSS 与证书管理能力Onerway 代理域名注册在 Onerway 的 Apple Developer 账号下，商户调用 Apple Pay 商户验证换取 merchant sessionOnerway 代解密没有或不想维护 Apple Developer 账号的商户 Web SDK 只涉及域名验证，按默认层级或 Onerway 代理层级完成即可。不要把商户自有 Merchant ID 与 Onerway 代理验证混用。 商户自有账号与 Onerway 代理两种域名验证方式，验证文件都部署在网站的 .well-known 路径下（以 Apple Developer 后台或 Onerway 提供的路径为准），该地址不可位于代理或重定向之后，且须允许 Apple 验证服务器访问： https:\u002F\u002Fyour-store.com\u002F.well-known\u002Fapple-developer-merchantid-domain-association",{"id":3119,"title":3120,"titles":3121,"content":3122,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#商户自有账号","商户自有账号",[73,2145],"创建 Merchant ID：登录 Apple Developer，在 Certificates, Identifiers & Profiles 的 Merchant IDs 中新建，填写 Description 与 Identifier（如 merchant.com.yourcompany.appname）。已有可用 Merchant ID 可跳过。配置支付处理证书：默认层级先把 Merchant ID 提供给 Onerway 技术支持，取得 Onerway 生成的 CSR。在该 Merchant ID 的 Apple Pay Payment Processing Certificate 中创建证书，「Will payments be processed exclusively in China mainland?」选 No，上传该 CSR。证书创建成功后下载 .cer 文件回传 Onerway：私钥由 Onerway 持有，收到证书后才能解密 Apple Pay token。商户自解密层级则由商户自行生成 CSR 并保管私钥。配置 Merchant Identity 证书（仅 API 直连需要）：在 Apple Pay Merchant Identity Certificate 中按 Apple 的 CSR 指南创建并下载，安全存放在商户验证服务端，用于向 Apple 请求 merchant session。域名验证：在 Merchant Domains 中添加域名，下载验证文件并部署到上述路径，确认 HTTPS 可直接访问后在 Apple Developer 中点击 Verify。域名验证随网站 SSL 证书一起到期：Apple 会在证书到期前 30、15、7 天回查，提前续期 SSL 证书即可自动保持验证；若证书过期后才更换，需重新验证域名。支付处理证书与 Merchant Identity 证书各 25 个月到期，Merchant ID 不过期。",{"id":3124,"title":3125,"titles":3126,"content":3127,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#onerway-代理","Onerway 代理",[73,2145],"向 Onerway 技术支持提供需要展示 Apple Pay 按钮的全部域名，含子域名，沙盒与生产域名都要提供，格式 https:\u002F\u002Fyour-store.com。Onerway 完成注册后返回验证文件，商户部署到上述路径并确认可访问： curl -I https:\u002F\u002Fyour-store.com\u002F.well-known\u002Fapple-developer-merchantid-domain-association Onerway 通过 Apple 完成域名验证后通知商户。支付处理证书与 Merchant Identity 证书由 Onerway 集中持有并续期，商户无需管理。 无论哪个层级，证书都应存放在受控环境、最小权限访问，并监控 SSL 证书与 Apple 证书的到期时间。",{"id":3129,"title":2188,"titles":3130,"content":3131,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#api-直连接入",[73],"商户自建按钮并驱动 ApplePaySession，Apple 返回的加密 payment token 按解密模式提交给 Onerway。两种模式二选一，tokenInfo 与 cardInfo 不可同时提交。 Onerway 代解密（推荐，默认与 Onerway 代理层级）：把 event.payment.token 整体序列化为字符串，原样放入 tokenInfo.tokenId，不要拆解其中的 paymentData、paymentMethod 与 transactionIdentifier。 \"tokenInfo\": \"{\\\"provider\\\":\\\"ApplePay\\\",\\\"tokenId\\\":\\\"\u003Cevent.payment.token 序列化后的字符串>\\\"}\" 商户自解密（自解密层级，须满足 PCI DSS）：不传 tokenInfo，把解密结果按下表放入 cardInfo。 解密后的 Apple 字段cardInfo 字段applicationPrimaryAccountNumbercardNumberapplicationExpirationDate（YYMMDD）month 取第 3、4 位；year 取前两位并补全为四位，如 30 对应 2030onlinePaymentCryptogramcryptogrameciIndicatorecipaymentDataTypewallet.applePay.paymentDataType，取 3DSecure 或 EMV，解密出哪种传哪种 完整报文见创建直连交易的「Onerway 代解密 Apple Pay 支付」与「商户自解密 Apple Pay 支付」示例。 前端先加载 Apple Pay JS SDK：推荐自动更新的 1.latest 地址；跨浏览器支持要求 1.2.0 及以上；固定版本时改用 v1.x.y 路径并加 integrity，1.latest 不支持 integrity。SDK 会在非 Safari 浏览器中注入 ApplePaySession。 能力检测并展示按钮加载 Apple Pay JS SDK 后，仅当 ApplePaySession 存在且 canMakePayments() 为 true 时展示按钮。需要判断客户是否已有可用卡时用 applePayCapabilities()，它在非 Safari 浏览器只会返回 paymentCredentialStatusUnknown，此时仍应展示按钮；canMakePaymentsWithActiveCard() 已废弃。按钮使用 SDK 提供的 \u003Capple-pay-button> 元素，样式属性见 Apple Pay 按钮文档，品牌规范见 Human Interface Guidelines。\u003Cscript src=\"https:\u002F\u002Fapplepay.cdn-apple.com\u002Fjsapi\u002F1.latest\u002Fapple-pay-sdk.js\">\u003C\u002Fscript>\n\u003Capple-pay-button buttonstyle=\"black\" type=\"buy\" locale=\"zh-CN\">\u003C\u002Fapple-pay-button>\n获取 Onerway 配置服务端调用查询可用支付方式，取 paymentMethod=ApplePay 的记录，把 countryCode 与 subCardTypes 返回前端，分别作为支付请求的 countryCode 与 supportedNetworks；两者已按 Apple 要求的格式返回，原样透传。applePayCapabilities() 需要商户标识：自有账号层级用商户自己的 Merchant ID，Onerway 代理层级用查询可用支付方式返回的 merchantId。创建支付会话用 supportsVersion() 从高到低探测浏览器支持的最高版本，再创建 ApplePaySession 并调用 begin()。支付请求至少包含 countryCode、currencyCode、supportedNetworks、merchantCapabilities（含 supports3DS）与 total（label、amount、type: 'final'），amount 为字符串。校验 validationURL 并换取 merchant session在 onvalidatemerchant 事件中取 validationURL，校验其主机是 Apple 的验证网关域名（apple-pay-gateway.apple.com，中国大陆为 cn-apple-pay-gateway.apple.com，沙盒为对应的 -cert 域名），其他 URL 一律调用 abort()，再交给服务端。服务端转发前必须再次校验主机，不要只依赖前端校验，也不要硬编码验证地址。商户自有账号层级由服务端用 Merchant Identity 证书向 Apple 发起 mTLS 请求，请求体含 merchantIdentifier、displayName（稳定的店铺名，不要本地化或拼入订单号）、initiative 取 web、initiativeContext 取完整域名；Onerway 代理层级调用 Apple Pay 商户验证，并把响应中的 data 解析为对象。完成商户验证拿到 merchant session 后立即调用 completeMerchantValidation()。merchant session 只能使用一次，创建后 5 分钟过期，只在服务端即时请求，不要在客户端直接请求 Apple。支付授权在 onpaymentauthorized 事件中取 event.payment.token 交给服务端，服务端调用创建直连交易（productType=CARD、subProductType=DIRECT、txnType=SALE），按解密模式提交 tokenInfo 或 cardInfo。前端根据服务端结果调用 completePayment() 传入成功或失败状态，且必须恰好调用一次，否则 Apple Pay 面板会一直停留。确认最终结果同步响应 status=S 为成功、P 为处理中，最终状态以支付结果通知为准，钱包交易的通知带 walletTypeName=ApplePay。验签、应答与幂等处理见 Webhook 通知。",{"id":3133,"title":3134,"titles":3135,"content":3136,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#前端示例","前端示例",[73],"服务端三个内部接口由商户实现，分别对应上面的获取配置、商户验证与支付授权三步。 \u003Capple-pay-button id=\"applePayButton\" buttonstyle=\"black\" type=\"buy\" locale=\"zh-CN\" style=\"display:none;\">\u003C\u002Fapple-pay-button>\n\u003Cscript src=\"https:\u002F\u002Fapplepay.cdn-apple.com\u002Fjsapi\u002F1.latest\u002Fapple-pay-sdk.js\">\u003C\u002Fscript>\n\u003Cscript>\n const button = document.getElementById('applePayButton')\n\n \u002F\u002F 服务端调用查询可用支付方式，返回 { countryCode, subCardTypes }\n const fetchConfig = () => fetch('\u002Fapi\u002Fapple-pay\u002Fconfig').then(r => r.json())\n \u002F\u002F 服务端按接入层级换取 merchant session：自有账号用 Merchant Identity 证书直连 Apple，Onerway 代理调用 Apple Pay 商户验证接口\n const validateMerchant = (validationURL, website) =>\n fetch('\u002Fapi\u002Fapple-pay\u002Fvalidate-merchant', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ validationURL, website })\n }).then(r => r.json())\n \u002F\u002F 服务端调用创建直连交易（tokenInfo.provider=ApplePay），返回 { success: boolean }\n const processPayment = (paymentToken) =>\n fetch('\u002Fapi\u002Fapple-pay\u002Fprocess-payment', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ paymentToken })\n }).then(r => r.json())\n\n \u002F\u002F 只接受 Apple 的验证网关主机，覆盖中国大陆与沙盒域名\n const APPLE_PAY_GATEWAY = \u002F^(cn-)?apple-pay-gateway(-[a-z0-9-]+)?\\.apple\\.com$\u002F\n\n const highestSupportedVersion = () => {\n for (let version = 14; version >= 3; version -= 1) {\n if (ApplePaySession.supportsVersion(version)) return version\n }\n return 3\n }\n\n function startSession(config) {\n const paymentRequest = {\n countryCode: config.countryCode,\n currencyCode: 'USD',\n supportedNetworks: config.subCardTypes,\n merchantCapabilities: ['supports3DS'],\n total: { label: 'Example Store', amount: '99.99', type: 'final' }\n }\n const session = new ApplePaySession(highestSupportedVersion(), paymentRequest)\n\n session.onvalidatemerchant = async (event) => {\n \u002F\u002F 服务端必须再校验一次，不要只依赖这里\n if (!APPLE_PAY_GATEWAY.test(new URL(event.validationURL).hostname)) {\n session.abort()\n return\n }\n try {\n const merchantSession = await validateMerchant(event.validationURL, window.location.hostname)\n session.completeMerchantValidation(merchantSession)\n } catch {\n session.abort()\n }\n }\n\n session.onpaymentauthorized = async (event) => {\n try {\n const result = await processPayment(event.payment.token)\n session.completePayment(result.success ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE)\n } catch {\n session.completePayment(ApplePaySession.STATUS_FAILURE)\n }\n }\n\n session.oncancel = () => {\n \u002F\u002F 用户关闭了 Apple Pay 面板，恢复页面交互\n }\n\n session.begin()\n }\n\n async function init() {\n if (!window.ApplePaySession || !ApplePaySession.canMakePayments()) return\n const config = await fetchConfig()\n button.style.display = 'block'\n button.addEventListener('click', () => startSession(config))\n }\n init()\n\u003C\u002Fscript> Apple 官方交互式演示可体验完整流程。",{"id":3138,"title":3139,"titles":3140,"content":3141,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#钱包订阅","钱包订阅",[73],"Apple Pay 可用于订阅：初始订阅时传 subProductType=SUBSCRIBE 与 subscription，selfExecute=1（Onerway 托管）与 selfExecute=2（商户自行发起每期扣款）均支持。收银台路径以 lpmsInfo.lpmsType=ApplePay 锁定 Apple Pay；API 直连路径以 tokenInfo 提交钱包加密 token 发起初始订阅。初始订阅成功后，订阅扣款通知返回 contractId 与订阅 tokenId，后续续费与升降级与卡订阅相同，见订阅支付。 与卡订阅的差异：钱包加密 token 是一次性的，不能保存复用，订阅期间的扣款凭证只有订阅 token；钱包订阅不产生保存支付方式结果通知，也不返回卡 token。",{"id":3143,"title":3144,"titles":3145,"content":3146,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#常见问题","常见问题",[73],"现象常见原因处理按钮不显示未加载 Apple Pay JS SDK 或使用了 CSS 按钮、非 HTTPS、设备或浏览器不支持、所在国家或地区不支持 Apple Pay使用 SDK 的 \u003Capple-pay-button>；只在 canMakePayments() 为 true 时展示；非 Safari 浏览器下 applePayCapabilities() 返回未知状态属正常；提供其他支付方式点击后面板一闪而过商户验证失败：validationURL 未通过校验、merchant session 超过 5 分钟或被复用、域名验证文件缺失或不可访问、网站 SSL 证书过期导致域名验证失效、initiativeContext 与验证域名不一致确认 completeMerchantValidation 被调用；用 curl -I 确认验证文件返回 200；核对域名一致；证书问题联系 Onerway 重新生成；沙盒与生产的商户标识不要混用确认支付后页面提示未完成未调用或多次调用 completePayment()；total.amount 不是字符串或精度错误；支付处理证书状态异常自检前端逻辑；仍失败时联系 Onerway 技术支持沙盒测试卡被拒未使用 sandbox 测试账户、设备地区与测试卡卡组织不匹配、卡未添加到 Wallet按 Apple Pay 沙盒测试完成前提 联系 Onerway 技术支持时请提供商户号与接入层级、发生时间与环境（沙盒或生产）、设备、操作系统与浏览器版本、完整的控制台与网络日志、复现步骤。",{"id":3148,"title":2849,"titles":3149,"content":3150,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fapple-pay#上线前检查",[73],"沙盒与生产域名已完成验证，验证文件可访问，SSL 证书续期已纳入监控。merchant session 只在服务端请求，validationURL 在前端与服务端都已校验。completePayment() 在成功与失败时都恰好调用一次。不记录、不存储 Apple Pay payment token。Webhook 验签与幂等已实现。 html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .ssf8z, html code.shiki .ssf8z{--shiki-light:#90A4AE;--shiki-default:#622CBC;--shiki-dark:#BABED8}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .sxVtM, html code.shiki .sxVtM{--shiki-light:#E53935;--shiki-default:#032563;--shiki-dark:#F07178}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .stp_H, html code.shiki .stp_H{--shiki-light:#90A4AE;--shiki-light-font-weight:inherit;--shiki-default:#024C1A;--shiki-default-font-weight:bold;--shiki-dark:#BABED8;--shiki-dark-font-weight:inherit}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}",{"id":2200,"title":77,"titles":3152,"content":3153,"level":609},[],"Google Pay 在收银台、Web SDK 与 API 直连下的接入差异、上线前网站报备、商户标识与解密模式的选择、API 直连的前端配置与下单流程、PAN_ONLY token 的两条处理路径、钱包订阅，以及常见问题。 Google Pay 让用户用 Google 账户中保存的卡快速完成支付，支持 Chrome、Safari、Firefox、Edge 等主流浏览器。收银台与 Web SDK 由 Onerway 渲染 Google Pay 按钮并处理 token；API 直连由商户自行加载 Google Pay JS SDK 取得加密 payment token，再提交给 Onerway。",{"id":3155,"title":3106,"titles":3156,"content":3157,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#接入方式选择",[77],"接入方式按钮与 token商户需要做的收银台收银台渲染按钮，token 不经过商户系统下单传 productType=ALL，或传 lpmsInfo.lpmsType=GooglePay 锁定 Google PayWeb SDKSDK 在商户页面内渲染按钮，外观见配置钱包按钮；token 不经过商户系统结果通过 payment_result 接收，见 SDK 自有按钮；App 内嵌 WebView 的限制见 WebView 说明API 直连商户加载 Google Pay JS SDK 并取得 token本页「API 直连接入」全部步骤 三种接入方式都要求网站 HTTPS 且 Onerway 商户账号已开通 Google Pay；浏览器与设备支持范围以 Google Pay Web 文档为准，沙盒测试用 Google 账号加入测试卡群组，见测试卡。",{"id":3159,"title":2145,"titles":3160,"content":3161,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#接入准备",[77],"API 直连接入前，先确定 token 的认证方式如何处理、由谁解密，以及商户标识的来源。",{"id":3163,"title":3164,"titles":3165,"content":3166,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#token-认证方式","token 认证方式",[77,2145],"authMethod 由用户的卡在 Google 侧的状态决定，商户不能指定；Onerway 要求 allowedAuthMethods 同时声明以下两个取值，不能只接受其中之一： CRYPTOGRAM_3DS：用户在设备上完成过 token 化的卡，token 含动态密文与 3DS 凭证，可直接授权。PAN_ONLY：只保存在 Google 账户、未在设备上 token 化的卡，token 不含 3DS 凭证，扣款前需要补采 CVC，处理方式见「PAN_ONLY token 的两条路径」。 两个取值都会在真实流量中出现，PAN_ONLY 不声明就无法向这部分用户收款。PAN_ONLY 也不意味着商户要接触卡号：Onerway 代解密模式下 token 以 Onerway 密钥加密，卡号不进商户系统；标准路径的 CVC 由 Onerway 页面采集，商户无需 PCI DSS 资质。只有选择商户自解密或商户自行采集 CVC 时，才涉及 PCI DSS。",{"id":3168,"title":3169,"titles":3170,"content":3171,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#解密模式","解密模式",[77,2145],"模式前端 tokenization提交给 Onerway前提Onerway 代解密（推荐）PAYMENT_GATEWAY，网关参数取查询可用支付方式的返回值tokenInfo，token 原样透传无商户自解密DIRECT，ECv2 加商户在自己的 Google Pay & Wallet Console 注册的公钥不传 tokenInfo，解密结果放入 cardInfo须满足 PCI DSS 商户自解密时，解密结果按下表放入 cardInfo： 解密后的 Google 字段cardInfo 字段pancardNumberexpirationMonth、expirationYearmonth、yearauthMethodwallet.googlePay.authMethodcryptogram、eciIndicator（仅 CRYPTOGRAM_3DS）cryptogram、eci",{"id":3173,"title":3174,"titles":3175,"content":3176,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#商户标识","商户标识",[77,2145],"Google 规定 environment 为 PRODUCTION 时 merchantInfo.merchantId 必填（TEST 可省略），取值取决于域名报备方式，二选一： 由 Onerway 在其 Google Pay & Wallet Console 档案下报备商户域名：用查询可用支付方式返回的 merchantId。商户自行注册 Google Pay & Wallet Console 并登记域名：用自己的商户标识。商户自解密只能选这种方式。 向 Onerway 技术支持确认使用的账号后，完成上线前网站报备。",{"id":3178,"title":3179,"titles":3180,"content":3181,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#上线前网站报备","上线前网站报备",[77],"本要求仅适用于 API 直连；收银台和 Web SDK 使用 Onerway 的 Google Pay 能力，无需报备网站。 接受生产环境支付前，需完成网站报备并获得 Google 审批通过，沙盒测试成功不能替代。按使用的 Google Pay 账号，参照 Google 官方发布集成指南完成： Google Pay 账号报备主体商户需要做的商户自有账号商户在自己的 Google Pay & Wallet Console 添加网站，提供域名与集成截图并提交审批。Onerway 账号Onerway将域名和下述五张截图提交给 Onerway 技术支持，由 Onerway 代为报备并通知结果。 域名即实际调用 Google Pay API 的网站。账号只决定 merchantInfo.merchantId 的取值：使用自有账号不要求自行解密 token；由 Onerway 解密时，gatewayName 和 gatewayMerchantId 仍取查询可用支付方式的返回值。",{"id":3183,"title":3184,"titles":3185,"content":3186,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#onerway-代报备所需的五张截图","Onerway 代报备所需的五张截图",[77,3179],"按购买流程的五个阶段各提供一张截图： 截图需要展示的内容商品选择页（Item selection）用户浏览商品或服务。购买前页面（Pre-purchase screen）用户准备进行购买。支付方式页面（Payment method screen）用户选择 Google Pay 作为支付方式。Google Pay 支付面板（Google Pay API payment screen）Google Pay 面板显示用户已保存的支付信息。购买完成页面（Post-purchase screen）用户成功购买后显示的页面。 Android 无法截取 Google Pay 支付面板时，可用另一台设备拍照；仅该项也接受错误信息的截图或照片。",{"id":3188,"title":3189,"titles":3190,"content":3191,"level":667},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#审批通过后切换生产环境","审批通过后切换生产环境",[77,3179],"Google 审批通过后，配置报备账号对应的 merchantInfo.merchantId，创建 PaymentsClient 时将 environment 设为 PRODUCTION，并改用 Onerway 生产环境 API 地址和凭证创建交易。",{"id":3193,"title":2188,"titles":3194,"content":3195,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#api-直连接入",[77],"获取 Onerway 配置服务端调用查询可用支付方式，取 paymentMethod=GooglePay 的记录，把配置返回前端。配置可缓存，变更时刷新。查询返回字段Google Pay 参数gatewayNametokenizationSpecification 的 gatewaygatewayMerchantIdtokenizationSpecification 的 gatewayMerchantIdsubCardTypesallowedCardNetworks，已是 Google 要求的全大写，原样透传merchantIdmerchantInfo.merchantId（按「商户标识」一节二选一）countryCodetransactionInfo.countryCode初始化并展示按钮加载 Google Pay JS SDK，创建 PaymentsClient，用 isReadyToPay() 做能力检测，通过后 createButton() 渲染官方按钮。\u003Cscript async src=\"https:\u002F\u002Fpay.google.com\u002Fgp\u002Fp\u002Fjs\u002Fpay.js\" onload=\"onGooglePayLoaded()\">\u003C\u002Fscript>\nconst paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' }) \u002F\u002F 生产改为 'PRODUCTION'\n发起支付点击按钮时构造 PaymentDataRequest，调用 loadPaymentData()，从返回结果的 tokenizationData.token 取出 token 交给服务端。请求至少包含 apiVersion: 2、含 tokenization 参数的 allowedPaymentMethods、transactionInfo（totalPriceStatus 取 FINAL，以及 totalPrice、currencyCode、countryCode）与 merchantInfo。可按需开启 emailRequired、shippingAddressRequired 让 Google Pay 面板采集联系信息。创建交易服务端调用创建直连交易（productType=CARD、subProductType=DIRECT、txnType=SALE），按解密模式提交 tokenInfo 或 cardInfo；完整报文见该接口的「Onerway 代解密 Google Pay 支付」「商户自解密 Google Pay CRYPTOGRAM_3DS 支付」示例。处理同步响应respCode 不为 20000 为失败；data.status=S 为成功；data.status=R 且 actionType=RedirectURL 表示 token 为 PAN_ONLY、需要补采 CVC，前端立即把用户跳转到 redirectUrl（Onerway 页面），用户输入后回跳 txnOrderMsg.returnUrl；此时响应中的 transactionId 为 null，只能以 merchantTxnId 关联订单。其余状态为处理中，等待通知。确认最终结果最终状态以支付结果通知为准，钱包交易的通知带 walletTypeName=GooglePay；校验通知中的金额、币种与商户订单一致。验签、应答与幂等处理见 Webhook 通知。",{"id":3197,"title":3198,"titles":3199,"content":3200,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#pan_only-token-的两条路径","PAN_ONLY token 的两条路径",[77],"对比项标准路径商户自行采集 CVCCVC 采集Onerway 页面商户自建输入框用户体验一次跳转与回跳无跳转实现只需处理 status=R 跳转多一次检查接口调用与 CVC 输入界面CVC 安全责任Onerway商户：不存储、不落日志、HTTPS 传输、用后即清 两条路径都无需额外开通。 商户自行采集 CVC 的流程： 取得 token 后先调用检查 Google Pay PAN_ONLY token。checkResult=false：向用户采集 CVC，创建直连交易时传同一个 tokenInfo，并在 cardInfo.cvv 提交 CVC。提交 PAN_ONLY token 时，若未传 cardInfo.cvv，交易响应返回 data.status=R 和 data.redirectUrl；商户需引导用户跳转至 data.redirectUrl，在 Onerway 托管页面输入 CVC。是否在创建交易前调用检查接口不影响此行为。checkResult=true：通过同一个 tokenInfo 创建直连交易，无需提交 cardInfo。检查与下单必须使用同一个 token 与同一个 merchantTxnId；检查接口失败时回退到标准路径。CVC 输入框按卡组织要求的位数实时校验（多数卡组织 3 位，American Express 4 位）、以密码类型显示，并向用户说明为何需要输入。",{"id":3202,"title":3134,"titles":3203,"content":3204,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#前端示例",[77],"配置从服务端取得后填入，processPayment 把 token 交给服务端。 \u003Cdiv id=\"container\">\u003C\u002Fdiv>\n\u003Cscript>\n \u002F\u002F 以下配置来自服务端调用查询可用支付方式返回的 GooglePay 记录\n const onerwayConfig = {\n gateway: '\u003CgatewayName>',\n gatewayMerchantId: '\u003CgatewayMerchantId>',\n allowedCardNetworks: ['MASTERCARD', 'VISA'],\n merchantId: '\u003CmerchantId>',\n countryCode: 'US'\n }\n\n const baseRequest = { apiVersion: 2, apiVersionMinor: 0 }\n const baseCardPaymentMethod = {\n type: 'CARD',\n parameters: { allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'], allowedCardNetworks: onerwayConfig.allowedCardNetworks }\n }\n const cardPaymentMethod = {\n ...baseCardPaymentMethod,\n tokenizationSpecification: {\n type: 'PAYMENT_GATEWAY',\n parameters: { gateway: onerwayConfig.gateway, gatewayMerchantId: onerwayConfig.gatewayMerchantId }\n }\n }\n\n let paymentsClient = null\n function getPaymentsClient() {\n if (!paymentsClient) {\n paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' }) \u002F\u002F 生产改为 'PRODUCTION'\n }\n return paymentsClient\n }\n\n function getPaymentDataRequest() {\n return {\n ...baseRequest,\n allowedPaymentMethods: [cardPaymentMethod],\n transactionInfo: { countryCode: onerwayConfig.countryCode, currencyCode: 'USD', totalPriceStatus: 'FINAL', totalPrice: '99.99' },\n merchantInfo: { merchantId: onerwayConfig.merchantId, merchantName: 'Example Store' }\n }\n }\n\n function onGooglePayLoaded() {\n getPaymentsClient()\n .isReadyToPay({ ...baseRequest, allowedPaymentMethods: [baseCardPaymentMethod] })\n .then((res) => {\n if (!res.result) return\n const button = getPaymentsClient().createButton({ onClick: onButtonClicked, allowedPaymentMethods: [baseCardPaymentMethod] })\n document.getElementById('container').appendChild(button)\n })\n }\n\n function onButtonClicked() {\n getPaymentsClient()\n .loadPaymentData(getPaymentDataRequest())\n .then(processPayment)\n .catch(() => {\n \u002F\u002F 用户关闭了 Google Pay 面板或支付失败，恢复页面交互\n })\n }\n\n async function processPayment(paymentData) {\n \u002F\u002F 不要记录或存储 token\n const paymentToken = paymentData.paymentMethodData.tokenizationData.token\n \u002F\u002F 服务端调用创建直连交易（tokenInfo.provider=GooglePay），把 respCode 非 20000 映射为 status 'F'，返回 { status, redirectUrl }\n const res = await fetch('\u002Fapi\u002Fgoogle-pay\u002Fprocess-payment', {\n method: 'POST',\n headers: { 'Content-Type': 'application\u002Fjson' },\n body: JSON.stringify({ paymentToken })\n }).then(r => r.json())\n\n if (res.status === 'R' && res.redirectUrl) {\n window.location.href = res.redirectUrl \u002F\u002F PAN_ONLY：跳转 Onerway 页面采集 CVC，最终状态以通知为准\n } else if (res.status === 'S') {\n \u002F\u002F 同步成功，仍以支付结果通知为准\n } else if (res.status === 'F') {\n \u002F\u002F 失败，提示用户更换支付方式\n } else {\n \u002F\u002F 处理中，等待支付结果通知\n }\n }\n\u003C\u002Fscript>\n\u003Cscript async src=\"https:\u002F\u002Fpay.google.com\u002Fgp\u002Fp\u002Fjs\u002Fpay.js\" onload=\"onGooglePayLoaded()\">\u003C\u002Fscript> Google 官方资源：Web 集成文档、交互式演示、品牌指南。",{"id":3206,"title":3139,"titles":3207,"content":3208,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#钱包订阅",[77],"Google Pay 可用于订阅：初始订阅时传 subProductType=SUBSCRIBE 与 subscription，selfExecute=1（Onerway 托管）与 selfExecute=2（商户自行发起每期扣款）均支持。收银台路径以 lpmsInfo.lpmsType=GooglePay 锁定 Google Pay；API 直连路径以 tokenInfo 提交钱包加密 token 发起初始订阅。初始订阅成功后，订阅扣款通知返回 contractId 与订阅 tokenId，后续续费与升降级与卡订阅相同，见订阅支付。 与卡订阅的差异：钱包加密 token 是一次性的，不能保存复用，订阅期间的扣款凭证只有订阅 token；钱包订阅不产生保存支付方式结果通知，也不返回卡 token。",{"id":3210,"title":3144,"titles":3211,"content":3212,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#常见问题",[77],"现象常见原因处理按钮不显示未加载 pay.js、非 HTTPS、账户无可用卡、App 内嵌 WebView 不满足条件检查 isReadyToPay() 返回值；WebView 见 Web SDK 接入配置获取失败服务端未返回 gatewayName、gatewayMerchantId 或 subCardTypes检查查询可用支付方式的调用与筛选生产环境弹窗报商户未验证merchantInfo.merchantId 缺失或与域名报备方式不匹配按「商户标识」一节确认取值来源PAN_ONLY 未处理创建直连交易返回 redirectUrl 但前端未跳转收到 redirectUrl 立即跳转，或改用商户自行采集 CVC 路径",{"id":3214,"title":2849,"titles":3215,"content":3216,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Fgoogle-pay#上线前检查",[77],"API 直连：已完成网站报备并获得 Google 审批通过。不在客户端解密 token，不记录、不存储 token。已用真实卡验证 PAN_ONLY 跳转与 CRYPTOGRAM_3DS 直接成功两条路径。采用商户自行采集 CVC 路径时，已验证检查接口失败时的回退。Webhook 验签、幂等与金额校验已实现。 html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s6mO7, html code.shiki .s6mO7{--shiki-light:#9C3EDA;--shiki-default:#023B95;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sZ0FG, html code.shiki .sZ0FG{--shiki-light:#E53935;--shiki-default:#0E1116;--shiki-dark:#F07178}html pre.shiki code .si0v_, html code.shiki .si0v_{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#66707B;--shiki-default-font-style:inherit;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sxVtM, html code.shiki .sxVtM{--shiki-light:#E53935;--shiki-default:#032563;--shiki-dark:#F07178}",{"id":2204,"title":2203,"titles":3218,"content":3219,"level":609},[],"本地支付方式的清单与可用性查询、三种接入方式的差异、三种客户侧动作与延迟到账的处理、方式专属参数、支持订阅的方式与两步流程，以及部分区域支付方式的额外要求。 本地支付方式是卡与钱包之外、面向特定国家或地区的支付方式，覆盖银行转账与网上银行、虚拟账户、电子钱包、二维码、便利店与现金凭证、预付卡、运营商代扣与先买后付等形态。它们与卡支付共用同一套下单接口，差别在于客户需要离开商户页面、在支付方式自己的界面完成付费，且部分方式并非即时到账。 三种接入方式都可以使用本地支付方式：收银台与 Web SDK 由 Onerway 展示可用方式并承接客户侧动作，API 直连由商户指定方式并自行承接。本地支付方式不支持预授权（txnType=AUTH）。",{"id":3221,"title":2268,"titles":3222,"content":3223,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#查询可用支付方式",[2203],"Onerway 支持的方式清单以字段 lpmsInfo.lpmsType 的取值为准，每个取值都附有方式说明，可作为接入前的方式名称索引；其中 ApplePay 与 GooglePay 属于钱包，接入方式见 Apple Pay 与 Google Pay。 某笔订单实际可用哪些方式，取决于商户开通配置、客户所在国家或地区、币种与金额，以查询可用支付方式的返回为准：不要只按币种判断可用性。返回的每条记录以 data[].paymentMethod 标识支付方式，下单时 lpmsInfo.lpmsType 使用同一个取值。币种与金额的校验规则见币种与金额校验。 由商户自建支付方式列表时（API 直连，或收银台锁定单一方式），必须先查询再展示，不要把方式清单硬编码在前端；结果可缓存，并在商户配置变更时刷新。收银台与 Web SDK 展示全部可用方式时由 Onerway 侧完成筛选，商户无需自行调用。 单笔限额，以及部分方式额外的商户注册或地区要求，请向 Onerway 技术支持确认。",{"id":3225,"title":3106,"titles":3226,"content":3227,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#接入方式选择",[2203],"接入方式展示与选择关键参数收银台收银台展示当前订单可用的方式，由客户自行选择；也可锁定单一方式展示全部可用方式传 productType=ALL；锁定单一方式在此基础上传 lpmsInfo.lpmsTypeWeb SDKSDK 在商户页面内展示可用方式，二维码与本地支付页等承接界面由 SDK 渲染productType=ALL；本地支付方式由商户按钮调用 confirmPayment() 发起API 直连商户自建支付方式列表并在下单时指定方式，自行承接客户侧动作字段 productType 传 LPMS 与 lpmsInfo；subProductType 一次性扣款传 DIRECT、订阅传 SUBSCRIBE 收银台与 Web SDK 路径下，客户侧动作与承接界面都由 Onerway 页面或 SDK 处理。本页其余内容说明 API 直连路径的调用方式与三种接入方式共同面对的到账时效；本地支付方式订阅目前只说明 API 直连的建立方式。",{"id":3229,"title":2188,"titles":3230,"content":3231,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#api-直连接入",[2203],"创建交易客户选定支付方式后，服务端调用创建直连交易，字段 productType 传 LPMS，并传入 subProductType=DIRECT（订阅传 SUBSCRIBE，见本地支付方式订阅）、txnType=SALE 与字段 lpmsInfo：lpmsType 指定支付方式，其余子字段按方式条件必填，见方式专属参数。productType=ALL 属于收银台的聚合展示概念，直连接口不支持。承接客户侧动作响应 status=R 表示还需要客户完成一次动作，动作形态由字段 actionType 决定，三种取值都要处理：actionType处理RedirectURL把客户重定向到字段 redirectUrl。跳转后的界面由支付方式决定，可能是选行页、银行 App 或网银授权页QrCode在商户页面展示字段 codeForm 承载的二维码或条码；该字段带 expireTime 时按其处理失效ShowContext在商户页面展示字段 presentContext 承载的上下文信息涉及拉起 App 的方式，需在移动浏览器上验证拉起与回跳。承接同步回跳跳转型方式的客户完成或放弃操作后，经 txnOrderMsg.returnUrl 返回商户页面。回跳只用于页面流转，不保证附带交易参数，也不代表支付已完成：建议在 returnUrl 上拼接商户订单号，客户返回时向其展示“处理中”，并由服务端通过查询交易记录核实。确认最终结果最终状态以支付结果通知为准，字段 paymentMethod 返回本次实际扣款的支付方式。验签、应答与重试、幂等去重与查询补偿见 Webhook 通知。",{"id":3233,"title":3234,"titles":3235,"content":3236,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#方式专属参数","方式专属参数",[2203],"除 lpmsType 外，lpmsInfo 还有五个子字段，都按所选支付方式条件必填： 子字段采集内容bankName客户选择的银行；EFT 与 Przelewy24 需要，可选银行见下方 lpmsInfo 字段说明中的取值列表walletAccountId钱包或本地账户标识符walletAccountName钱包或本地账户名称iBan以 IBAN 识别银行的地区转账账号prepaidNumber日本预付类方式的预付卡或充值卡号 各字段的完整必填条件与 bankName 的银行取值见字段 lpmsInfo。 billingInformation 与 shippingInformation 的必填子字段同样随支付方式变化，例如部分本地支付方式要求提供客户的政府身份标识 identityNumber。这些要求由支付方式提供方决定，创建直连交易接口只对个别方式给出了明确条件（例如 lpmsType=MB_WAY 时 phoneCountryCode 必填），其余未逐个列出，请在沙盒环境逐个验证要上线的方式。",{"id":3238,"title":3239,"titles":3240,"content":3241,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#延迟到账与等待态","延迟到账与等待态",[2203],"部分本地支付方式并非即时到账：客户拿到支付码、凭证或转账信息后，可能过一段时间才实际完成付费，银行转账、虚拟账户、便利店与现金凭证类方式都属于这种形态。这类订单需要按以下方式处理： 一次下单对应一个支付意图：响应中的 paymentId 与 transactionId 一一对应。支付意图未关闭前可继续尝试（通知的 paymentStatus 为 O），关闭后（N）该订单不能再支付。支付结果通知只在交易到达终态时发送，已向客户出示支付码或凭证不代表款项已收到。创建交易后订单可能长时间停在处理中，商户需要为订单设计等待态，并明确超时后如何处理；支付意图超时关闭时，通知的 paymentStatus 为 N。不要以回跳或同步响应作为到账依据，也不要在客户回跳后立即发货；未收到通知时用查询交易记录补偿，读交易级 status——该接口不返回支付意图级的 paymentStatus。",{"id":3243,"title":3244,"titles":3245,"content":3246,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#本地支付方式订阅","本地支付方式订阅",[2203],"部分本地支付方式可用于订阅，目前包括 DANA、WeChat、GCash 与 TOUCH_GO_EWALLET；某个方式在当前商户配置下是否支持订阅，可在查询可用支付方式时传 subProductType=SUBSCRIBE 筛选。这些方式只支持自主管理订阅（subscription.selfExecute=2），续费扣款由商户发起；托管订阅与自主管理订阅的区别见订阅支付。 计费频率只能传 frequencyType=D，但这不表示只能按天扣款：字段 subscription.frequencyPoint 按天表示计费周期，例如，月度订阅可传 30，年度订阅可传 365。该值仅用于记录，实际续费扣款时间由商户自行确定。 订阅分两步完成： 订阅授权：调用创建直连交易，传入 productType=LPMS、subProductType=SUBSCRIBE、txnType=SALE、lpmsInfo 与字段 subscription（requestType=0），客户在支付方式提供方的界面完成协议扣款授权，承接方式同样由 actionType 决定。首期扣款方式由 subscription.mode 决定：默认 2 表示客户授权后由 Onerway 立即完成首期扣款；传 1 表示只建立授权、首期扣款改由商户自行发起。授权结果以保存支付方式结果通知为准（txnType=BIND_CARD、scenarios=SUBSCRIPTION_INITIAL），仅在 status=S 时持久化其中的 contractId 与 tokenId。请求中的 orderAmount 填写真实的订阅金额，txnOrderMsg.products 各行合计需与之相等；授权通知本身返回 orderAmount=0.00。后续扣款：商户按计费周期调用创建直连交易，传入 subscription.requestType=1 与已保存的 contractId、tokenId 和 merchantCustId。mode=2 下首期扣款已由 Onerway 在授权后完成，商户从第二期开始发起；mode=1 下首期也由商户发起。每期扣款的结果都由订阅扣款通知返回（txnType=SALE）。 与卡订阅的差异： 授权失败即订阅终止：不会再有订阅扣款通知，保存支付方式结果通知的 subscriptionStatus 为 canceled。mode=2 下订阅授权与首期扣款是两条通知，transactionId 与 channelRequestId 各不相同，merchantTxnId、contractId 与 tokenId 相同（paymentId 有值时同样相同，但首期扣款通知可能不返回该字段，不要用它做唯一匹配键）；两条通知到达商户服务器的先后顺序不保证，都要按各自的 transactionId 幂等处理。这里的 tokenId 是订阅 token，只能用于订阅相关操作，不能用于 subProductType=TOKEN 支付；本地支付方式订阅不返回 cardTokenId。首期扣款的订阅扣款通知不返回 scenarios，订阅场景由保存支付方式结果通知返回。",{"id":3248,"title":3249,"titles":3250,"content":3251,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#部分区域支付方式的额外要求","部分区域支付方式的额外要求",[2203],"stc pay、Tamara、Tabby 与 MADA 的取值分别是 stcpay、tamara、tabby 与 cardpay，可在字段 lpmsInfo.lpmsType 的取值列表中按方式名查到。这几个方式的额外要求不在 lpmsInfo 里，而在商品与订单信息上： 商品行必须区分类别：字段 txnOrderMsg.products[].type 传 virtual 或 physical，字段 txnOrderMsg.products[].productAvatarUrl 传 HTTPS 商品图片链接，格式为 JPG、PNG 或 WebP。字段 txnOrderMsg.customerPlatform 必填：Web 端传网站域名，App 端传应用名称。stc pay 的结算依赖物流信息：交易已成功完成且包裹送达客户并签收后，调用上传物流信息提交承运商编码与运单号；虚拟商品交易与分期交易不适用该结算前置条件。 这几个方式的开通范围请向 Onerway 技术支持确认。",{"id":3253,"title":2849,"titles":3254,"content":3255,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fpayment-methods\u002Flocal-payment-methods#上线前检查",[2203],"自建支付方式列表的接入方式已在展示前调用查询可用支付方式，没有把方式清单硬编码在前端。status=R 下 actionType 的三种取值都已处理，回跳页只承接客户，订单结果由服务端查询或通知确认。Webhook 端点已按 Webhook 通知完成上线前检查，能接收支付结果通知；使用订阅时还能接收保存支付方式结果通知与订阅扣款通知。已为非即时到账的方式设计等待态与超时处理，未在客户回跳后立即发货。已在沙盒环境逐个验证要上线的支付方式，覆盖客户中途取消与移动端跳转。使用本地支付方式订阅时，contractId 与 tokenId 仅在授权成功时保存，以字符串存储并与客户关联。",{"id":2208,"title":2212,"titles":3257,"content":3258,"level":609},[],"按业务场景说明保存支付方式、订阅、预授权、分账与退款的概念、生命周期与通知，并对比收银台、Web SDK 与 API 直连的参数差异。 本栏目按业务场景组织，与接入方式无关：各页说明概念、操作流程与结果通知；涉及下单配置的场景还会对比收银台、Web SDK 与 API 直连的参数差异。各接入方式自身的接入流程见收银台接入、Web SDK 接入与 API 直连接入；通知的验签、应答与重试、幂等去重、状态判断与结果查询见 Webhook 通知。分账通知的地址、验签和应答方式见分账。",{"id":3260,"title":3261,"titles":3262,"content":3263,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios#场景速查","场景速查",[2212],"场景典型业务收银台Web SDKAPI 直连保存支付方式复购时不再重复输入卡信息客户自选保存客户自选保存服务端绑卡、token 支付订阅支付按周期自动或由商户发起扣款初始订阅初始订阅初始订阅、续费、升降级预授权与请款押金、预订、发货前锁定额度预授权下单预授权下单预授权下单、请款、撤销分账平台模式下在支付后分配交易资金下单时配置分账下单时配置分账下单时配置分账 支付成功后的退款由商户服务端通过 API 申请。退款指南说明申请、结果通知、查询与取消流程。 无论在哪种接入方式下单，自主管理订阅的续费、托管订阅的升降级、预授权的请款与撤销都由商户服务端通过 API 直连发起。",{"id":3265,"title":3266,"titles":3267,"content":3268,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios#三类-token","三类 token",[2212],"文档中出现的三类 token 互不通用，接入前请先区分： 卡 token：客户自选保存或服务端绑卡后得到的 tokenId，用于后续 token 支付，见保存支付方式。订阅 token：订阅扣款通知返回的 tokenId，与 contractId 配对用于订阅续费与升降级，见订阅支付。钱包加密 token：Apple Pay、Google Pay SDK 返回的一次性加密报文，原样放入字段 tokenInfo 的 tokenId，并以 provider 指明钱包 token 提供方，由 Onerway 代解密；不能保存复用。 订阅并绑卡时会同时产生卡 token 与订阅 token，两套 token 属不同体系，不可混用。",{"id":2215,"title":2214,"titles":3270,"content":3271,"level":609},[],"保存客户的卡以支持复购：客户自选保存与服务端绑卡的选择、绑卡结果通知、已保存 token 的查询与删除，以及三种接入方式的参数差异。 保存支付方式（绑卡）把客户的卡转换为可复用的 tokenId，后续支付不再重复输入卡信息。收银台与 Web SDK 由客户在 Onerway 页面上自选是否保存；API 直连由商户服务端提交卡信息完成绑卡。",{"id":3273,"title":3274,"titles":3275,"content":3276,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#概念与选择","概念与选择",[2214],"客户自选保存（收银台、Web SDK）：下单时传入稳定的 merchantCustId，Onerway 页面向客户提供保存卡选项。该选项不会默认选中，只有客户主动勾选并完成支付后才会保存卡。后续在相同环境、merchantNo 和 appId 范围内再次支付时，继续传入同一个 merchantCustId，页面会向该客户回显可用的已保存卡并在页面内完成选卡与支付。卡数据不经过商户系统，没有 PCI DSS 要求。服务端绑卡（API 直连）：商户服务端调用生成卡 token提交卡信息，得到 tokenId 后以 token 支付发起后续交易。卡数据经过商户系统，须持有有效的 PCI DSS 认证。 两条路径得到的 tokenId 属同一体系，但服务端发起 token 支付时必须在 cardInfo.cvv 提交客户本次输入的 CVC，仍然经手卡数据，因此同样要求 PCI DSS。不具备资质的商户应让复购也在收银台或 Web SDK 页面上完成：页面回显已保存卡并在页面内完成支付；服务端可通过查询已保存 token 核对保存记录，但不能自行发起 token 支付。 merchantCustId 应来自稳定的服务端客户记录，不要直接使用邮箱、手机号等可变信息，也不要为不同客户复用同一个标识；没有持久客户记录的访客应省略 merchantCustId。卡 token 与订阅 token 属不同体系，区分见场景概览。",{"id":3278,"title":3279,"titles":3280,"content":3281,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#生命周期与通知","生命周期与通知",[2214],"支付成功不等于保存成功。保存结果以保存支付方式结果通知（txnType=BIND_CARD）为最终依据，仅当 status=S 时保存通知中的 tokenId；回跳到 returnUrl 与同步响应都不代表绑卡成功。服务端也可调用查询已保存 token 核对。管理已保存 token：查询已保存 token 返回每条绑定记录的 id 与 tokenId；客户要求删除卡时调用删除卡 token，入参是绑定记录的 id，不是 tokenId。token 支付仍可能触发 3DS：服务端以已保存 tokenId 发起的支付同样可能返回 status=R，按 API 直连接入处理跳转。订阅并绑卡：托管卡订阅传入 subscription.bindCard=true 时，绑卡结果由独立的保存支付方式结果通知承载，与订阅扣款通知的 transactionId 不同，应各自幂等处理，见订阅。",{"id":3283,"title":3284,"titles":3285,"content":3286,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsaved-payment-methods#各接入方式的参数差异","各接入方式的参数差异",[2214],"接入方式接口关键参数差异说明接入指南收银台创建收银台支付merchantCustId由收银台页面展示保存选项与已保存卡；subProductType 按场景传 DIRECT、SUBSCRIBE 或 INSTALLMENT，保存卡无专用取值收银台接入Web SDK创建 SDK 交易merchantCustId、subProductType=DIRECTSDK 内完成选卡与支付，客户端无需获取 tokenIdWeb SDK 接入API 直连生成卡 token、创建直连交易绑卡：卡信息、merchantCustId；卡 token 支付：subProductType=TOKEN、tokenInfo.tokenId、cardInfo.cvv、merchantCustId绑卡与卡 token 支付是两次调用，都需 PCI DSSAPI 直连接入",{"id":2219,"title":2218,"titles":3288,"content":3289,"level":609},[],"托管订阅与自主管理订阅的选择、合约凭证与生命周期通知、续费与升降级，以及三种接入方式的参数差异。 订阅在首次支付时建立合约，之后按计费周期重复扣款。初始订阅可以在收银台、Web SDK 或 API 直连任一接入方式完成；自主管理订阅的续费与托管订阅的升降级由商户服务端通过 API 直连发起。",{"id":3291,"title":3274,"titles":3292,"content":3293,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#概念与选择",[2218],"计费方式由 subscription.selfExecute 决定，在初始订阅时选定： 托管订阅（selfExecute=1）：Onerway 按订阅的计费设置自动发起每期扣款，每期均推送 Webhook；配置 notificationEmail 后，Onerway 向客户发送订阅确认与扣款邮件，客户可通过响应中的 subscriptionManageUrl 自助管理订阅。自主管理订阅（selfExecute=2）：商户自行维护计费周期，使用初始订阅返回的 contractId 和 tokenId，通过创建直连交易（subscription.requestType=1）发起每期扣款；计费频率仅支持 frequencyType=D，但这不表示只能按天扣款：字段 subscription.frequencyPoint 按天表示计费周期，例如，月度订阅可传 30，年度订阅可传 365。该值仅用于记录，实际续费扣款时间由商户自行确定。首期扣款是否由商户发起取决于 subscription.mode，默认 2 时由 Onerway 在客户授权后完成。 卡与钱包都可用于订阅，两种计费方式对 Apple Pay 与 Google Pay 同样适用；钱包订阅的发起方式与差异见 Apple Pay 与 Google Pay。部分本地支付方式也可用于订阅，但只支持自主管理订阅，且订阅授权会单独产生一条通知，见本地支付方式。 计费周期、期数或截止日期、试用期等均在字段 subscription 中定义，字段含义见 API Reference。客户标识通过外层 merchantCustId 传入（subscription.merchantCustId 选填，传则须一致），取值要求与保存支付方式一致。",{"id":3295,"title":3279,"titles":3296,"content":3297,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#生命周期与通知",[2218],"合约凭证：初始订阅成功后，保存订阅扣款通知中的 contractId 与 tokenId，它们是后续扣款、查询与取消的凭证。这里的 tokenId 是订阅 token，与卡 token 不可混用，见场景概览。生命周期事件：首购、续费、换卡、变更、取消、到期与合约状态以订阅扣款通知的字段 scenarios 与字段 subscriptionStatus 为准。自主管理订阅续费：服务端传入 contractId、tokenId、merchantCustId 与本期金额发起扣款，不传卡信息，因此续费环节没有 PCI DSS 要求。每期扣款金额由商户指定，不受首次订阅金额约束。扣款成功后收到 scenarios=SUBSCRIPTION_RENEWAL 的通知；对账由商户负责。托管订阅续费：Onerway 按生效中的计划金额自动扣款，未变更计划前即首次订阅时的金额。单期自动扣款的金额不能单独修改，需要调整后续金额时按下述升降级更新计划。托管订阅升降级：使用已存储的 contractId 与 tokenId 发起（requestType=2），生效方式由 subscription.changeMode 决定。更新成功后收到 scenarios=SUBSCRIPTION_CHANGED 的通知，变更生效后 Onerway 按新计划金额继续自动扣款。\nchangeMode=1 立即生效：Onerway 按当前计费周期剩余天数计算差价（prorationMode=1，默认），或由商户通过 proration 提交差价（prorationMode=0）。升级立即扣取差价；降级如需向客户退还差额，由商户调用申请或取消退款完成。changeMode=2 下个计费周期生效：不立即扣款，适合需要提前告知客户的涨价。订阅并绑卡：托管卡订阅同时传入 subscription.bindCard=true 时，系统创建两笔交易并发送两条独立通知：保存支付方式结果通知（txnType=BIND_CARD）返回可用于后续 token 支付的卡 token，订阅扣款通知（txnType=SALE）返回订阅侧的 contractId 与 tokenId。两条通知的 transactionId 不同，应各自幂等处理。查询与取消：合约详情见查询订阅详情，取消见取消订阅合约。",{"id":3299,"title":3300,"titles":3301,"content":3302,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#扣款失败与重试","扣款失败与重试",[2218],"自主管理订阅（selfExecute=2）由商户自行决定是否重试、重试次数与间隔，每次重试以续费扣款（requestType=1）通过 API 直连发起。 托管订阅（selfExecute=1）由 Onerway 自动重试：每期最多尝试 3 次（含首次扣款），即最多重试 2 次。重试间隔取决于计费周期： 计费周期重试间隔每天1 小时每 2–3 天12 小时超过 3 天24 小时 重试期间 subscriptionStatus 为 pastdue；3 次全部失败后变为 paused，合约仍处于启用状态（dataStatus=1）。两个字段可从订阅扣款通知和查询订阅详情获取。 扣款重试与 Webhook 重发是两回事，后者见 Webhook 通知。",{"id":3304,"title":3305,"titles":3306,"content":3307,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#更换订阅用卡","更换订阅用卡",[2218],"仅托管订阅（selfExecute=1）支持换卡，且只能由客户在 subscriptionManageUrl 指向的订阅管理页面完成，没有对应 API。换卡结果通过 scenarios=SUBSCRIPTION_CARD_REPLACEMENT 的订阅扣款通知推送。",{"id":3309,"title":3284,"titles":3310,"content":3311,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fsubscriptions#各接入方式的参数差异",[2218],"接入方式接口关键参数差异说明接入指南收银台创建收银台支付subProductType=SUBSCRIBE、subscription（requestType=0）只做初始订阅；外层 merchantCustId 如同时传入须与 subscription.merchantCustId 一致收银台接入Web SDK创建 SDK 交易subProductType=SUBSCRIBE、subscription（requestType=0）只做初始订阅；服务端维护允许购买的计划映射Web SDK 接入API 直连创建直连交易subProductType=SUBSCRIBE、subscription.requestType初始订阅、续费与升降级都在此接口，以 requestType 取 0 \u002F 1 \u002F 2 区分API 直连接入",{"id":2223,"title":2222,"titles":3313,"content":3314,"level":609},[],"先冻结额度、后按履约请款：预授权的适用范围、从授权到请款或撤销的生命周期与通知、边界与状态判断，以及三种接入方式的参数差异。 预授权先冻结持卡人卡上的订单金额、暂不扣款，适用于酒店与租车押金、预订类订单、发货前锁定额度等先确保额度、后按履约扣款的业务。预授权下单可以在任一接入方式完成；请款或撤销由商户服务端调用 API 完成。",{"id":3316,"title":3274,"titles":3317,"content":3318,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#概念与选择",[2222],"适用范围：txnType=AUTH 适用于自行采集卡信息的卡支付和 token 支付（subProductType=DIRECT 或 TOKEN），不适用于本地支付方式、订阅或分期。仅支持全额请款：需要少扣时先撤销再重新下单，或请款后通过申请或取消退款退还差额。请款与撤销二选一：对同一笔预授权只能执行其中一个。",{"id":3320,"title":3279,"titles":3321,"content":3322,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#生命周期与通知",[2222],"预授权下单按所用接入方式下单并传入 txnType=AUTH，其余参数与普通支付相同；需要 3DS 时按该接入方式的接入流程处理跳转。确认授权结果收到预授权、请款与撤销通知中 txnType=AUTH、status=S、paymentStatus=A 的通知后确认授权成功。保存响应或通知中的 transactionId 与 paymentId：前者是请款或撤销时 originTransactionId 的取值，后者用于把授权与后续请款或撤销关联到同一支付意图。请款或撤销调用预授权请款或撤销，originTransactionId 传预授权的 transactionId，txnType=CAPTURE 扣划全部冻结金额，txnType=VOID 释放冻结、不扣款。确认最终结果请款成功后收到 txnType=CAPTURE、status=S、paymentStatus=S 的通知；撤销成功后收到 txnType=VOID、status=S、paymentStatus=N 的通知。请款或撤销通知的 transactionId 属于本次操作，与原预授权不同；按各自的 transactionId 幂等处理，并用 paymentId 关联同一支付意图。 边界与状态处理： VOID 只作用于未请款的预授权，释放冻结额度、不产生资金流；已请款的交易只能走退款。请款或撤销请求中不同的 merchantTxnId 视为不同交易，对同一 originTransactionId 的重复请款应由商户侧防重。以 paymentId 加 paymentStatus 判断这笔资金处于冻结中、已扣款还是已释放（AUTH 成功 A，CAPTURE 成功 S，VOID 成功 N），不要用多条通知各自的 status 拼装状态；status 与 paymentStatus 的语义区分见 Webhook 通知。",{"id":3324,"title":3284,"titles":3325,"content":3326,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fpre-authorization#各接入方式的参数差异",[2222],"接入方式接口关键参数差异说明接入指南收银台创建收银台支付txnType=AUTH3DS 由收银台页面引导完成收银台接入Web SDK创建 SDK 交易txnType=AUTH、subProductType=DIRECTSDK 集成流程与普通支付一致Web SDK 接入API 直连创建直连交易txnType=AUTH、subProductType=DIRECT 或 TOKEN需要 3DS 时按 status=R 自行处理跳转API 直连接入",{"id":2227,"title":2226,"titles":3328,"content":3329,"level":609},[],"选择自动分账或通过 API 发起分账，配置结果通知，并将分账与分账回退关联到原支付交易。 分账是平台模式下的能力，用于在支付完成后分配交易资金；是否为平台商户在开户时按约定的合作模式确定，普通商户不适用本页内容。通常由平台商户以收款子商户名义发起分账。自动分账的接收方为平台商户；通过 API 发起时，接收方与金额由请求中的 receivers 指定。创建支付时，merchantNo 使用收款子商户号，后续通过 API 发起分账或查询时保持一致。",{"id":3331,"title":3274,"titles":3332,"content":3333,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#概念与选择",[2226],"创建支付时，必须在 paymentMethodOptions.share 中设置 profitShare=true，该笔支付才可参与分账。收银台、Web SDK 与 API 直连均使用这一配置。 方式创建支付时的配置支付成功后的处理自动分账同时设置 profitShare=true 和 profitShareRateSALE 或 CAPTURE 成功后，Onerway 按比例自动分账给平台商户；每笔原支付只产生一笔自动分账记录通过 API 发起分账设置 profitShare=true，不传 profitShareRate商户服务端调用分账接口，指定接收方与分账金额 profitShareRate 是 1–100 的整数百分比，以字符串提交，\"10\" 表示 10%；小数、0、负数或大于 100 的取值会被拒绝。已自动分账的支付发生退款或拒付时，Onerway 按同一比例退还对应的分账金额。 仅设置 profitShare=true 或通知地址不会触发自动分账。需要自动分账时，还必须设置 profitShareRate。字段要求与完整请求示例见各接入方式的 API 参考。",{"id":3335,"title":3279,"titles":3336,"content":3337,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#生命周期与通知",[2226],"创建支付并配置通知地址按选定方式设置 paymentMethodOptions.share。需要接收自动分账或自动分账回退通知时，同时设置 profitShareNotifyUrl；不传时，不发送自动通知。通知地址必须使用 HTTPS，且与 profitShare=true 同时提交。CAPTURE 交易继承原 AUTH 交易的通知地址。paymentMethodOptions 按接口要求以 JSON 字符串提交，完整示例见下方各接入方式的 API 参考。确认支付成功按所用接入方式确认支付结果，并保存原交易的 transactionId、商户订单号及收款商户号。支付结果的通知处理见 Webhook 通知；分账结果使用独立的分账结果通知。自动分账或调用分账接口选择自动分账时，由 Onerway 在 SALE 或 CAPTURE 成功后执行，无需再调用分账接口。自动分账与自动分账回退的 profitReference 由 Onerway 生成。通过 API 发起时，调用发起分账或分账回退，设置 profitType=share，gatewayReference 使用原支付的 transactionId。为本次请求提供全局唯一的 profitReference，通过 currency 提交分账币种，在 receivers 中指定接收方商户号、资金用途和金额，并按接口要求序列化为 JSON 字符串。profitCompleted 在 profitType=share 时必填，表示本次请求是否结束该笔支付的分账；后续还会继续分账时传 false。一旦传入 true，该笔支付后续分账请求会被拒绝。通过 API 发起时的完整条件见对应字段说明。通过 API 发起的分账或分账回退使用 urlCallback 接收结果。原支付已配置 profitShareNotifyUrl 时，无需再传 urlCallback；未配置时，必须在本次 API 请求中提供 urlCallback。处理分账结果保存 profitReference 和 Onerway 返回的 profitGatewayReference，用于后续查询与分账回退。收到通知后，通过 relatedTxnId、relatedMerchantTxnId 关联原支付；这些字段为字符串，允许返回 null。已有分账记录也可按分账请求号与 Onerway 分账单号关联。分账及分账回退通知使用通知体中的 sign 字段验签，具体算法见分账及分账回退通知验签。使用收到的原始 receivers 字符串参与验签，不要解析后重新序列化。成功接收并受理后返回 HTTP 200，响应体可为空。state=completed 只表示整体处理结束，不代表每条明细都成功。逐条检查 receivers[].result；失败时结合 failReason 排查，但不要根据其文本内容判断处理结果。",{"id":3339,"title":2368,"titles":3340,"content":3341,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#查询分账结果",[2226],"未收到通知或需要核对结果时，调用查询分账结果。使用原支付的收款商户号，并通过 profitType=share 或 return 选择分账或分账回退。 profitReference、gatewayReference、profitGatewayReference、relatedTxnId 和 relatedMerchantTxnId 至少提供一个；同时提供多个时按组合条件过滤。可按原支付的 relatedTxnId 或 relatedMerchantTxnId 查询，也可使用已保存的分账请求号或 Onerway 分账单号。查询字段、适用条件和示例见 API 参考。 查询中的 gatewayReference 随单据类型变化：share 时指原 SALE 支付的 transactionId，return 时指被回退的 Onerway 分账单号。按原支付查询分账回退时，使用 relatedTxnId。 查询请求中的商户号和交易流水号建议使用字符串，避免数值精度损失。查询响应返回 data.sign，但商户无需对查询响应验签；这不改变分账 Webhook 的验签要求。",{"id":3343,"title":3344,"titles":3345,"content":3346,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#分账回退","分账回退",[2226],"需要通过 API 回退已有分账时，调用发起分账或分账回退，设置 profitType=return： 为本次回退提供新的全局唯一 profitReference，并通过 currency 提交回退币种。profitParentReference 使用原分账请求号；自动分账时该请求号由 Onerway 生成，可从查询结果或通知中取得。profitGatewayReference 使用被回退的原 Onerway 分账单号。为每条回退明细提供在本次 profitReference 下唯一的 profitDetailReference。明细中的 profitDetailParentReference 使用原分账明细请求号，profitDetailGatewayReference 使用原 Onerway 分账明细单号。接收方使用原明细的接收方商户号。金额与其他条件见接口字段说明。发起回退时不传 gatewayReference；这与查询回退结果时该字段的含义不同。 分账回退也通过通知或查询确认处理结果，并逐条检查明细。不要将提交回退请求视为回退成功。",{"id":3348,"title":3284,"titles":3349,"content":3350,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Fprofit-sharing#各接入方式的参数差异",[2226],"三种接入方式都在创建支付时配置 paymentMethodOptions.share；自动分账规则相同。通过 API 发起分账、查询或分账回退时，均由商户服务端调用分账接口。 接入方式接口关键参数差异说明接入指南收银台创建收银台支付paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无收银台接入Web SDK创建 SDK 交易paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无Web SDK 接入API 直连创建直连交易paymentMethodOptions.share：profitShare、profitShareRate、profitShareNotifyUrl无API 直连接入",{"id":2231,"title":2230,"titles":3352,"content":3353,"level":609},[],"申请退款、处理退款结果与审核拒绝通知，并在需要时查询结果或取消尚未获批的退款申请。 支付成功后，由商户服务端通过 API 申请退款。无论原支付通过收银台、Web SDK 还是 API 直连创建，均使用申请或取消退款。",{"id":3355,"title":3356,"titles":3357,"content":3358,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#申请前确认","申请前确认",[2230],"是否支持退款、部分退款及多次退款，以及申请退款的时限，均取决于支付方式。大多数支付方式支持部分退款及多次退款；累计退款金额不得超过原支付金额，退款金额使用原支付交易的币种。 保存原支付的 Onerway transactionId，并确认原交易已支付成功。调用接口前，完成接入准备与请求签名。",{"id":3360,"title":3361,"titles":3362,"content":3363,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#申请退款并处理结果","申请退款并处理结果",[2230],"提交退款申请调用申请或取消退款，设置 refundType=0，将原支付交易号放入 originTransactionId，通过 refundAmount 指定本次退款金额。完整字段要求与请求示例见接口参考。可通过 merchantTxnId 提供本次退款的商户交易号，用于跟踪和对账；不传时由 Onerway 自动生成。重复提交会被拒绝。保存退款交易号respCode=20000 仅表示退款申请已受理，不代表退款成功。保存响应 data 返回的新退款交易号，并将其关联到原支付和商户退款记录，供接收通知、查询或取消时使用。处理退款通知退款通知发送到原支付请求中的 notifyUrl。服务端需要处理两类通知：退款结果通知：txnType=REFUND，使用退款的 transactionId 与 status 更新对应退款记录。退款审核拒绝通知：notifyType=REFUND_AUDIT，仅在 Onerway 审核拒绝退款申请时发送。按 Webhook 通知完成验签、应答与幂等处理。收到成功（S）或失败（F）通知后即可更新退款记录，无需再查询确认。",{"id":3365,"title":3366,"titles":3367,"content":3368,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#按需查询退款","按需查询退款",[2230],"等待 Webhook 通知退款结果即可，无需持续轮询。需要核对退款进度或对账时，可调用查询退款记录：查询单笔退款时使用退款交易号 transactionId；查询原支付关联的退款时使用原支付交易号 originTransactionId。 查询结果与通知不一致时，参见查询结果与通知不一致时如何处理。 大部分退款即时到账；非即时到账的退款最长需要 25 天。",{"id":3370,"title":3371,"titles":3372,"content":3373,"level":615},"\u002Fzh\u002Fpayments\u002Fonline-payments\u002Fscenarios\u002Frefunds#取消退款申请","取消退款申请",[2230],"取消须在 Onerway 审核通过前发起。审核通过后，Onerway 将退款请求提交给支付渠道或发卡机构；退款仍在处理中不代表仍可取消。 调用申请或取消退款，设置 refundType=1，并将要取消的退款交易号放入 originTransactionId。其他必填字段与完整示例见接口参考。 取消成功不发送通知，请处理同步响应：成功响应中的 data 等于本次请求的 originTransactionId。需要核对记录时，可按该退款交易号查询。 申请退款时，originTransactionId 指原支付交易号；取消退款申请时，同一字段指退款交易号。两次操作使用的交易号不同。",{"id":2245,"title":2244,"titles":3375,"content":3376,"level":609},[],"创建收银台支付并获取跳转到 Onerway 托管页面的 redirectUrl。 该接口用于创建收银台支付，并获取跳转到 Onerway 托管支付页面的 redirectUrl。",{"id":2249,"title":2248,"titles":3378,"content":3379,"level":609},[],"创建直连交易，支持卡、钱包、已保存 token、订阅、分期和本地支付方式。 该接口用于创建服务端到服务端的直连交易，支持卡、钱包、已保存 token、订阅、分期和本地支付方式。",{"id":2253,"title":2252,"titles":3381,"content":3382,"level":609},[],"创建 SDK 交易并获取用于初始化当前 Onerway Web SDK 的 paymentId。 该接口用于创建 SDK 交易，并获取用于初始化当前 Onerway Web SDK 的 paymentId。",{"id":2257,"title":2256,"titles":3384,"content":3385,"level":609},[],"在 PCI DSS 合规接入中生成卡 token，并通过 notifyUrl 接收最终 tokenization 结果。 该接口用于在 PCI DSS 合规接入中生成卡 token。同步响应承载处理状态与后续动作字段，最终 tokenization 结果通过 notifyUrl 回调接收。",{"id":2261,"title":2260,"titles":3387,"content":3388,"level":609},[],"使用查询已保存 token 返回的绑卡记录 ID 删除已保存卡绑定。 该接口用于解绑已保存的卡。请将查询已保存 token 返回的 data.tokenInfos[].id 作为 id 提交。该值不同于 tokenId；tokenId 用于后续 token 支付，例如直连下单接口。删除成功后，关联的 token 将不能再用于 token 支付。",{"id":2265,"title":2264,"titles":3390,"content":3391,"level":609},[],"对成功的预授权发起全额请款，或撤销预授权以释放冻结金额。 该接口用于对成功的预授权发起全额请款，或撤销预授权以释放冻结金额。",{"id":2269,"title":2268,"titles":3393,"content":3394,"level":609},[],"查询当前订单上下文可用的支付方式。 该接口用于在创建支付前，根据客户国家或地区、币种、金额、支付发起环境和商户开通配置查询可用支付方式。",{"id":2273,"title":2272,"titles":3396,"content":3397,"level":609},[],"按支付意图、交易标识或时间范围查询支付记录。 该接口用于按支付意图维度检索交易结果，支持查询同一个 paymentId 下的多笔 transactionId 并用于对账。",{"id":2277,"title":2276,"titles":3399,"content":3400,"level":609},[],"按支付意图、退款交易、原交易或时间范围查询退款记录。 查询退款记录，并通过 paymentId 关联对应的支付意图。未收到退款通知时，可调用本接口查询结果；通知见退款结果通知与退款审核拒绝通知。",{"id":2281,"title":2280,"titles":3402,"content":3403,"level":609},[],"查询商户客户名下已保存的卡 token 或订阅 token。 该接口用于查询客户名下已保存的 token 列表。响应会返回用于解绑操作的绑定信息 ID，以及用于后续 token 支付或订阅相关操作的 tokenId。",{"id":2285,"title":2284,"titles":3405,"content":3406,"level":609},[],"按订阅合约号查询订阅的计费、状态和 token 信息。 该接口用于按 contractId 查询一份订阅合约详情，返回客户、商品、计费周期、生命周期状态和订阅 token 信息。",{"id":2289,"title":2288,"titles":3408,"content":3409,"level":609},[],"立即、当前计费周期结束或指定日期取消一份订阅合同。 该接口用于按 contractId 取消一份已存在的订阅合同，并指定取消生效方式。",{"id":2293,"title":2292,"titles":3411,"content":3412,"level":609},[],"按通知 ID、欺诈类型、原交易或生成时间范围查询欺诈通知。 该接口用于查询欺诈通知，并通过 originTransactionId 将每条通知关联回原交易。",{"id":2297,"title":2296,"titles":3414,"content":3415,"level":609},[],"按拒付 ID、交易标识或导入时间范围查询拒付记录。 该接口用于查询商户交易产生的拒付记录。调用前需先联系 Onerway 开通拒付查询权限。",{"id":2301,"title":2300,"titles":3417,"content":3418,"level":609},[],"按商户交易号、Onerway 交易号或创建时间范围查询交易记录。 该接口用于按交易流水维度检索交易记录，支持对账、争议处理与报表核对。",{"id":2305,"title":2304,"titles":3420,"content":3421,"level":609},[],"创建托管支付链接并返回 Payment Link ID 和收银台访问 URL。 该接口用于创建支付链接，买家可打开该链接进入 Onerway 托管收银台完成支付。",{"id":2309,"title":2308,"titles":3423,"content":3424,"level":609},[],"按状态、关键词、创建时间和分页条件查询支付链接列表。 该接口用于分页查询支付链接，并返回访问次数、成功支付次数和成功收款总额等运营统计信息。",{"id":2313,"title":2312,"titles":3426,"content":3427,"level":609},[],"按 Payment Link ID 启用或停用支付链接。 该接口用于按 Payment Link ID 更新支付链接状态，可启用或停用已有支付链接。",{"id":2317,"title":2316,"titles":3429,"content":3430,"level":609},[],"对已支付成功的交易发起退款，或取消已提交的退款申请。 该接口用于对已支付成功的交易发起退款，或在 Onerway 审核通过前取消已提交的退款申请。是否支持退款及申请时限取决于支付方式。",{"id":2321,"title":2320,"titles":3432,"content":3433,"level":609},[],"为支付交易上传承运商编码和物流追踪单号。 该接口用于为交易关联物流配送信息，可用于结算确认、订单追踪与争议处理。对于 stc pay 结算场景，仅在实体商品交易已成功完成且包裹已签收后上传物流信息。",{"id":2325,"title":2324,"titles":3435,"content":3436,"level":609},[],"按结算日期和结算币种下载 UTF-8 CSV 结算文件。 该接口用于在 Onerway 开通结算文件下载权限后，按结算日期和结算币种下载结算文件。请求参数需放在 Header 中，成功响应请保存为 UTF-8 CSV 文件。",{"id":2329,"title":2328,"titles":3438,"content":3439,"level":609},[],"为商户或代理子商户提交 Ethoca 预警服务开通申请。 该接口用于提交 Ethoca 预警服务开通申请，并取得后续查询或变更状态所需的申请单号。",{"id":2333,"title":2332,"titles":3441,"content":3442,"level":609},[],"查询 Ethoca 服务申请记录及其当前生命周期状态。 该接口用于查询 Ethoca 服务申请记录、确认预警服务是否已开通，并查看开通失败或被拒时的审核意见。",{"id":2337,"title":2336,"titles":3444,"content":3445,"level":609},[],"撤回 Ethoca 申请、申请关闭服务，或重新提交开通失败的申请。 该接口用于请求 Ethoca 申请状态流转，例如撤回待审核申请、关闭已开通服务，或在开通失败后重新提交申请。",{"id":2341,"title":2340,"titles":3447,"content":3448,"level":609},[],"按预警标识、预警类型、时间范围、账单描述或处理结果查询 Ethoca 预警记录。 该接口用于查询 Ethoca 预警记录，将预警匹配回原交易，并查看最新处理结果和退款状态。",{"id":2345,"title":2344,"titles":3450,"content":3451,"level":609},[],"提交 Ethoca 预警的处理结果和退款状态。 该接口用于回报 Ethoca 预警的处理方式，包括该预警对应的处置结果和退款状态。",{"id":2349,"title":2348,"titles":3453,"content":3454,"level":609},[],"为商户或代理子商户提交 Visa 快速争议解决服务开通申请。 该接口用于提交 RDR 服务开通申请，并取得后续查询或变更状态所需的申请单号。",{"id":2353,"title":2352,"titles":3456,"content":3457,"level":609},[],"查询 RDR 服务申请记录及其当前生命周期状态。 该接口用于查询 RDR 服务申请记录、确认服务是否已开通，并查看开通失败或被拒时的审核意见。",{"id":2357,"title":2356,"titles":3459,"content":3460,"level":609},[],"提交 RDR 申请、撤回申请、申请关闭服务，或重新提交开通失败的申请。 该接口用于请求 RDR 申请状态流转，例如提交待提交申请、撤回待审核申请、关闭已开通服务，或在开通失败后重新提交申请。",{"id":2361,"title":2360,"titles":3462,"content":3463,"level":609},[],"按案件标识、案件类型、接收时间、原交易信息或处理状态查询 RDR 预警案件。 该接口用于查询 RDR 预警案件，将案件匹配回原交易，并查看自动处理规则和处理状态。",{"id":2365,"title":2364,"titles":3465,"content":3466,"level":609},[],"对已完成的支付发起分账，或对一笔已有分账发起回退。 该接口用于对已完成的支付发起分账，或对一笔已有分账发起回退，由 profitType 决定本次执行的操作。",{"id":2369,"title":2368,"titles":3468,"content":3469,"level":609},[],"查询一笔分账或分账回退的处理结果与各接收方明细。 该接口用于查询一笔分账或分账回退的处理结果，查看整体状态，并逐条确认各接收方明细的处理结果。",{"id":2373,"title":2372,"titles":3471,"content":3472,"level":609},[],"在客户确认支付前，更新 SDK 交易的订单金额、账单信息或配送信息。 该接口用于在客户确认支付前，更新 SDK 交易的订单金额、账单信息或配送信息。",{"id":2377,"title":2376,"titles":3474,"content":3475,"level":609},[],"由 Onerway 代为报备 Apple Pay 域名时，通过 Onerway 向 Apple 获取 merchant session，完成 Apple Pay 会话的商户验证。 该接口用于由 Onerway 代为报备 Apple Pay 域名的商户在 onvalidatemerchant 事件中通过 Onerway 向 Apple 获取 merchant session。使用自有 Apple Developer 账号的商户用自己的 Merchant Identity 证书直接向 Apple 请求，不调用本接口；接入层级与会话流程见 Apple Pay。",{"id":2381,"title":2380,"titles":3477,"content":3478,"level":609},[],"商户自行采集 CVC 时，在创建直连交易前检查 Google Pay token 是否为 PAN_ONLY、是否需要补收 CVC。 该接口用于商户自行采集 CVC 的 Google Pay 接入路径，在创建直连交易前检查 token 是否为 PAN_ONLY。由 Onerway 页面采集 CVC 的标准路径不需要调用本接口；两条路径的选择见 Google Pay。",{"id":2390,"title":2389,"titles":3480,"content":3481,"level":609},[],"接收包含欺诈类型、源交易、拒付标志和退款状态的欺诈预警回调报文。 该回调通知用于接收欺诈预警，并通过 originTransactionId 将每条预警关联回原交易。",{"id":2394,"title":2393,"titles":3483,"content":3484,"level":609},[],"接收包含预警标识、原交易、争议信息和处理状态的 Ethoca 预警回调报文。 该回调通知用于接收 Ethoca 预警，并通过 ethocaId 和 transactionId 将每条预警关联回原交易。",{"id":2398,"title":2397,"titles":3486,"content":3487,"level":609},[],"接收普通支付成功、失败、超时关闭或取消等支付结果回调报文。 该回调通知用于接收 TXN \u002F SALE 支付交易的服务端结果，并通过 transactionId 和 paymentId 关联支付链路。",{"id":2402,"title":2401,"titles":3489,"content":3490,"level":609},[],"接收包含订阅合约、token 与扣款场景上下文的首次或后续订阅扣款回调报文。 该回调通知用于接收订阅扣款结果，并通过 contractId、tokenId 和 scenarios 关联对应订阅扣款场景。",{"id":2406,"title":2405,"titles":3492,"content":3493,"level":609},[],"接收预授权创建、请款和撤销回调报文，并通过同一支付意图关联授权生命周期。 该回调通知用于接收 AUTH、CAPTURE 与 VOID 交易通知，并通过 paymentId 关联预授权生命周期。",{"id":2410,"title":2409,"titles":3495,"content":3496,"level":609},[],"接收包含整体状态和各接收方明细的分账或分账回退结果回调报文。 接收分账或分账回退结果，并通过 relatedTxnId 与 relatedMerchantTxnId 关联原支付交易。自动通知使用原交易的 paymentMethodOptions.share.profitShareNotifyUrl；未配置该地址时，不发送自动通知。通过 API 发起分账或分账回退时使用 urlCallback；原交易已配置 profitShareNotifyUrl 时，可省略 urlCallback。",{"id":2414,"title":2413,"titles":3498,"content":3499,"level":609},[],"接收保存支付方式（绑卡）交易的最终结果回调报文，覆盖纯绑卡与订阅并绑卡场景。 该回调通知用于接收 txnType=BIND_CARD 保存支付方式交易的服务端最终结果；仅在 status=S 时保存并使用通知中的 tokenId。",{"id":2418,"title":2417,"titles":3501,"content":3502,"level":609},[],"Ethoca 报备状态变更通知的字段、验签和应答要求。 通过商户后台配置的通知地址接收 Ethoca 报备状态变更通知。",{"id":2422,"title":2421,"titles":3504,"content":3505,"level":609},[],"RDR 报备状态变更通知的字段、验签和应答要求。 通过商户后台配置的通知地址接收 RDR 报备状态变更通知。",{"id":2426,"title":2425,"titles":3507,"content":3508,"level":609},[],"退款结果（txnType=REFUND）发送到原交易请求的 notifyUrl。 通过原交易请求的 notifyUrl 接收退款结果。请勿根据示例判断字段是否始终返回或能否为 null。处理要求见 Webhook 通知，退款请求见申请或取消退款。",{"id":2430,"title":2429,"titles":3510,"content":3511,"level":609},[],"仅在 Onerway 审核拒绝退款申请时，向原交易请求的 notifyUrl 发送通知（notifyType=REFUND_AUDIT）。 仅在 Onerway 审核拒绝退款申请时，向原交易请求的 notifyUrl 发送通知。请勿根据示例判断字段是否始终返回或能否为 null。处理要求见 Webhook 通知，退款请求见申请或取消退款。",{"id":2434,"title":2433,"titles":3513,"content":3514,"level":609},[],"通知拒付预警及其关联交易信息。 在配置的拒付预警通知地址接收预警；应答时原样返回收到的 predisputeId。",{"id":2438,"title":2437,"titles":3516,"content":3517,"level":609},[],"通知拒付状态变化，不进行重试。 接收 notifyType=CHARGEBACK 的拒付状态变化通知。需要查询记录时，请使用查询拒付记录。",{"id":2442,"title":2441,"titles":3519,"content":3520,"level":609},[],"对照 Onerway 支付响应中的英文 message，查看中文说明和建议排查动作。 当 API 响应中的 respCode 不是 20000 时，可用本页定位错误类型、排查请求参数、判断是否需要客户换卡、重试或联系 Onerway 支持。接口响应中的 message 为英文；中文说明是为了方便中文读者理解而整理，不代表接口会返回中文 message。 respCode=20000 表示 Onerway 已处理请求，但不一定代表交易、退款、订阅或绑卡的最终业务结果。最终状态仍应结合接口文档、异步通知和查询接口确认。 发卡机构和收单机构拒绝通常与卡片、账户、发卡机构风控或通道状态有关。不要对硬拒绝、疑似欺诈、AML、法律\u002F监管限制类错误盲目重试。",{"id":3522,"title":3523,"titles":3524,"content":3525,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#错误码范围","错误码范围",[2441],"范围Category中文类别数量11xxxSystem errors系统错误112xxxConfiguration errors配置错误1113xxxParameter errors参数错误35132xxSubscription errors订阅错误1614xxxRefund errors退款错误1520xxxRisk control errors风控错误130xxxValidation errors校验错误2140xxxAcquirer errors收单机构错误650xxx3DS errors3DS 错误560xxxIssuer errors发卡机构错误8370xxxGeneral errors通用错误2",{"id":3527,"title":3528,"titles":3529,"content":3530,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#系统错误11xxx","系统错误（11xxx）",[2441],"错误码message中文说明建议处理11001System exception系统异常联系 Onerway 支持",{"id":3532,"title":3533,"titles":3534,"content":3535,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#配置错误12xxx","配置错误（12xxx）",[2441],"错误码message中文说明建议处理12001System configuration decline系统配置拒绝联系 Onerway 支持12002Merchant ID is disabled or settlement currency is not configured商户号已停用或未配置结算币种联系 Onerway 支持12003Card brand\u002F3DS\u002FService is not supported不支持该卡组织、3DS 或服务联系 Onerway 支持12004Merchant Account is disabled or non-existent商户账户已停用或不存在联系 Onerway 支持12005Invalid transaction ID for SDK initializationSDK 初始化交易 ID 无效确认 SDK 初始化使用的交易号来自服务端响应；确认交易号未被篡改；确认下单接口与 SDK 使用同一环境12006Subscription payment information verification failed订阅支付信息校验失败仅适用于托管订阅（selfExecute=1）：确保订阅支付时间符合扣款频率12007Incorrect transaction ID交易 ID 不正确检查 merchantNo12008Invalid transaction IP交易 IP 无效检查请求中的 transactionIp12009Request channel timed out请求通道超时稍后重试12010Configuration error prevents the request from being processed配置错误导致请求无法处理联系 Onerway 支持确认交易类型已启用120113DS\u002FAPI request initialization failed3DS\u002FAPI 请求初始化失败联系 Onerway 支持",{"id":3537,"title":3538,"titles":3539,"content":3540,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#参数错误13xxx","参数错误（13xxx）",[2441],"错误码message中文说明建议处理13001Invalid appIdappId 无效联系 Onerway 支持13002Invalid card number卡号无效检查卡号后重试13003Invalid transaction URL交易 URL 无效检查请求域名是否与已登记域名一致；联系 Onerway 支持13004Expired card卡片已过期检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡13005Year must be 2 or 4 digits年份必须为 2 位或 4 位数字检查卡片信息后重试；请客户换用其他卡13006Invalid state, please fill in the correct state when the country is US, CA or CN.国家\u002F地区为 US、CA 或 CN 时，state 无效或缺失检查请求中的 state（US、CA、CN 必填）13007Incorrect card information卡片信息不正确检查卡片信息后重试13008Repeat transaction rejected重复交易被拒绝确认交易是否已成功13009Card number is required卡号不能为空检查卡号后重试13010Unsupported card brand: MAESTRO不支持 MAESTRO 卡检查卡组织配置13011Decline - Invalid account number账户号码无效导致拒绝请客户联系发卡机构确认；请客户换用其他卡13012billingAddress.city is longer than 30 charactersbillingAddress.city 长度不能超过 30 个字符检查请求中的 city（最多 30 个字符）13013mpiInfo is required when risk3dsStrategy is EXTERNALrisk3dsStrategy=EXTERNAL 时必须传入 mpiInfo检查请求中的 mpiInfo13014Invalid transaction type交易类型无效检查请求中的 txnType13015merchantCustId is required for subscription订阅场景必须传入商户客户号检查请求中的 merchantCustId13016Subscription contract parameters are required订阅合约参数不能为空检查请求中的 subscription13017Billing information, email, and country are required账单信息不能为空，且 email 与 country 必须填写检查 billingInformation.email 和 billingInformation.country13018Invalid productTypeproductType 无效检查请求中的 productType13019Invalid product information format商品信息格式无效检查 txnOrderMsg.products13020Invalid subscription frequency订阅扣款频率无效检查 subscription.frequencyType 和 subscription.frequencyPoint13021Transaction query time range cannot exceed 90 days交易查询时间范围不能超过 90 天检查 startTime 和 endTime13022Unsupported currency不支持该币种检查国家\u002F地区与币种是否匹配13023Subscription contract unavailable订阅合约不可用检查订阅状态13024contractId or tokenId is required for subscription payment订阅支付必须传入 contractId 或 tokenId检查 contractId 和 tokenId13025Card year\u002Fmonth is invalid卡片年份或月份无效检查 year 和 month13026Invalid subProductTypesubProductType 无效检查 subProductType13027Duplicate order transaction订单交易重复确认请求是否已处理成功13028Query condition is required查询条件不能为空检查 merchantTxnIds、transactionIds、startTime 和 endTime13029Subscription contract expired订阅合约已过期确认订阅是否已过期13030Invalid transaction amount交易金额无效检查 amount13031PAN-only card does not support 3DSPAN-only 卡不支持 3DS换用支持 3DS 的卡13032Order has already been captured or canceled订单已请款或已取消，不能再次请款确认订单是否已请款或取消13033Parameters have already been used for the first subscription purchase该参数组合已用于首次订阅支付确认同一买家是否已用同一张卡完成订阅13034Invalid card verification code lengthCVC 长度无效检查 CVC 长度13035Refund amount is too small退款金额过小退款金额必须大于 0",{"id":3542,"title":3543,"titles":3544,"content":3545,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#订阅错误132xx","订阅错误（132xx）",[2441],"错误码message中文说明建议处理13200Invalid self-execute settingSelf execute 设置无效检查 Self execute13201Invalid email邮箱无效检查 email13202Invalid cycle countCycle count 无效检查 Cycle count13203Invalid trial-from-plan settingTrial from plan 设置无效检查 Trial from plan13204Invalid trial days or trial endTrial days 或 trial end 无效检查 Trial days 或 trial end13205Invalid products information商品信息无效检查 Products information13206Invalid proration settingProration 设置无效检查 Proration13207Invalid billing cycle anchorBilling cycle anchor 无效检查 Billing cycle anchor13208Invalid frequency type订阅频率类型无效检查 frequency type13209Invalid subscription request type订阅请求类型无效检查 subscription request type13210Invalid subscription period订阅周期无效检查 subscription period13211Invalid subscription frequency订阅频率无效检查 subscription frequency13212Invalid merchant customer number商户客户号无效检查 Merchant customer number13213Invalid contract number or token合约号或 token 无效检查 contract number 或 token13214Subscription validity is earlier than the current time订阅有效期早于当前时间检查 Subscription validity13215Invalid contract information合约信息无效检查 contract information",{"id":3547,"title":3548,"titles":3549,"content":3550,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#退款错误14xxx","退款错误（14xxx）",[2441],"错误码message中文说明建议处理14001Refund failed退款失败检查交易状态14002Real-time refund is not supported不支持实时退款稍后重试14003Cumulative refund amount exceeds the transaction amount累计退款金额不能大于交易金额检查本次退款金额和累计退款金额14004Refund has already been processed and cannot be canceled退款已处理，不能取消取消前先检查退款状态14005Online refunds not supported不支持线上退款通过线下渠道手动处理退款14006Real-time refund not supported不支持实时退款改用延迟退款处理14007Refund not supported for this payment method该支付方式不支持退款通过其他渠道手动处理退款14008System automatic refund in progress系统自动退款处理中等待自动退款完成14009Only full refund allowed for chargeback transactions拒付交易只允许全额退款提交全额退款，不要提交部分退款14010Refund must use designated interface退款必须使用指定接口将退款请求发送到指定接口14011Online refund failed because orders are pending or rejected订单待审核或已拒绝导致线上退款失败先处理待审核或已拒绝订单14012Insufficient payout account balance打款账户余额不足确保打款账户余额充足14013Transaction does not support refund initiation该交易不支持发起退款联系 Onerway 支持14014Chargeback already exists, refund not supported已存在拒付，不能再发起退款不要重复退款；款项已通过银行或发卡机构退回14015Original transaction was not successful原交易未成功退款前核实原交易状态",{"id":3552,"title":3553,"titles":3554,"content":3555,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#风控错误20xxx","风控错误（20xxx）",[2441],"错误码message中文说明建议处理20001High risk高风险交易确认客户身份；24 小时后重试或联系 Onerway 支持",{"id":3557,"title":3558,"titles":3559,"content":3560,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#校验错误30xxx","校验错误（30xxx）",[2441],"错误码message中文说明建议处理30001Invalid IP addressIP 地址无效检查请求中的 ip30002Invalid birthDatebirthDate 无效检查 birthDate30003Invalid productproduct 无效检查 product30004Invalid merchantCustIdmerchantCustId 无效检查 merchantCustId30005Invalid productTypeproductType 无效检查 productType30006Invalid appIdappId 无效检查 appId30007Invalid number卡号无效检查卡号后重试30008Invalid card verification codeCVC 无效检查 CVC 后重试30009Invalid pinPIN 无效请客户联系发卡机构确认；请客户换用其他卡30010Invalid expiry month or year有效期月份或年份无效检查有效期后重试；请客户换用其他卡30011Invalid cardholder name持卡人姓名无效检查持卡人姓名后重试30012Invalid country国家\u002F地区无效检查 country30013Invalid state州\u002F省无效检查 state30014Invalid city城市无效检查 city30015Invalid address地址无效检查 address30016Invalid email邮箱无效检查 email30017Invalid postalCode邮编无效检查 postalCode30018Invalid phone电话无效检查 phone30019Invalid account账户无效请客户联系发卡机构确认；请客户换用其他卡30020Invalid parameters参数无效参考 API 文档检查请求参数30021Invalid transaction URL交易 URL 无效联系 Onerway 支持审核并批准网站",{"id":3562,"title":3563,"titles":3564,"content":3565,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#收单机构错误40xxx","收单机构错误（40xxx）",[2441],"错误码message中文说明建议处理40000Illegal parameter {field}请求参数非法；message 中会指出具体字段名按接口文档检查该字段的取值、格式与依赖条件40001Acquirer suspected fraud收单机构疑似欺诈拒绝确认客户身份，并换用其他卡重试40002Acquirer system failure收单机构系统故障稍后重试；请客户换用其他卡；联系 Onerway 支持40003Acquirer decline收单机构拒绝稍后重试；请客户换用其他卡40004Acquirer timeout收单机构超时稍后重试40005Missing or invalid acquirer parameters收单机构参数缺失或无效联系 Onerway 支持",{"id":3567,"title":3568,"titles":3569,"content":3570,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#_3ds-错误50xxx","3DS 错误（50xxx）",[2441],"错误码message中文说明建议处理500013DS authentication required需要完成 3DS 认证重试并完成 3DS 认证；请客户换用其他卡500023DS parameters error3DS 参数错误重试并完成 3DS 认证；请客户换用其他卡500033DS authentication failure3DS 认证失败重试并完成 3DS 认证；请客户换用其他卡500043DS system error3DS 系统错误重试并完成 3DS 认证；请客户换用其他卡50030Order canceled订单已取消确认订单状态后再处理",{"id":3572,"title":3573,"titles":3574,"content":3575,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#发卡机构错误60xxx","发卡机构错误（60xxx）",[2441],"错误码message中文说明建议处理60001Refer to card issuer请联系发卡机构检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60002Refer to card issuer, special condition请联系发卡机构，存在特殊条件检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60003Invalid merchant商户无效联系 Onerway 支持60004Pick up card (no fraud)\u002FCapture card需要收卡（非欺诈）请客户联系发卡机构确认，或换用其他卡60005Do not honor发卡机构拒绝授权检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60006Issuer processing error发卡机构处理错误稍后重试，或请客户换用其他卡60007Pick up card, special condition (fraud account)需要收卡，疑似欺诈账户请客户联系发卡机构确认，或换用其他卡60012Invalid transaction交易无效检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60013Invalid amount or Currency conversion field overflow金额无效或币种转换字段溢出检查交易金额或币种；联系 Onerway 支持60014Invalid account number账户号码无效检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60015Invalid issuer发卡机构无效检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60019Re-enter transaction需要重新提交交易检查报文格式；检查地址信息60021No action taken未采取处理动作请客户联系发卡机构确认；请客户换用其他卡60025Unable to locate record in file无法定位相关记录检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60028File temporarily not available for update or inquiry文件暂时无法更新或查询重新发起交易60030Format error报文格式错误检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60039No credit account无信用账户检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60041Lost card, pick up card (fraud account)遗失卡，需要收卡，疑似欺诈账户请客户联系发卡机构确认，或换用其他卡60043Stolen card, pick up (fraud account)被盗卡，需要收卡，疑似欺诈账户请客户联系发卡机构确认，或换用其他卡60046Closed account账户已关闭检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60051Insufficient funds\u002Fover credit limit余额不足或超过授信额度请客户联系发卡机构确认额度；请客户换用其他卡60052No checking account无支票账户检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60053No savings account无储蓄账户检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60054Expired card or expiration date missing卡片已过期或缺少有效期检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60055PIN incorrect or missing\u002FInvalid PINPIN 不正确或缺失请客户联系发卡机构确认，或换用其他卡60057Transaction not permitted to issuer\u002Fcardholder发卡机构或持卡人不允许该交易请客户联系发卡机构确认，或换用其他卡60058Transaction not permitted to acquirer\u002Fterminal收单机构或终端不允许该交易请客户联系发卡机构确认，或换用其他卡60059Suspected fraud疑似欺诈检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60061Exceeds approval amount limit超过授权金额限制请客户联系发卡机构确认，或换用其他卡60062Restricted card (card invalid in region or country)\u002FRestricted card受限卡或该地区\u002F国家不可用请客户联系发卡机构确认，或换用其他卡60063Security violation (source is not correct issuer)\u002FSecurity violation安全校验失败检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60064Transaction does not fulfill AML requirement交易不满足 AML 要求不要重试；复核交易风险60065Exceeds withdrawal frequency limit超过取现频次限制请客户联系发卡机构确认；请客户换用其他卡；联系 Onerway 支持60070PIN data required or contact card issuer需要 PIN 数据或联系发卡机构请客户联系发卡机构确认，或换用其他卡60071PIN Not ChangedPIN 未变更请客户联系发卡机构确认，或换用其他卡60074Different value than that used for PIN encryption errorsPIN 加密错误相关值不匹配请客户联系发卡机构确认，或换用其他卡60075Allowable number of PIN entry tries exceededPIN 输入尝试次数已超限请客户联系发卡机构确认，或换用其他卡60076Invalid or unsolicited reversal account information冲正账户信息无效或不存在请客户联系发卡机构确认，或换用其他卡60077Invalid\u002Fnonexistent \"From Account\" specified来源账户无效或不存在请客户联系发卡机构确认，或换用其他卡60078Blocked card or invalid account卡片未激活、临时锁定或账户无效请客户联系发卡机构确认卡片是否已激活；请客户换用其他卡60079Reversed or card life-cycle restriction交易已冲正或卡生命周期受限检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60080No financial impact or issuer system unavailable无资金影响或发卡系统不可用检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60081PIN cryptographic error or domestic debit not allowedPIN 加密错误或本地借记交易不允许检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60082Card authentication value failed or issuer policy decline卡片认证值校验失败或发卡机构策略拒绝检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60083Fraud\u002FSecurity (Mastercard use only)欺诈或安全原因拒绝检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60084Invalid Authorization Life Cycle授权生命周期无效检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60086PIN verification is not possible无法验证 PIN当天内重试；如适用，尝试非 PIN 交易60087Purchase Amount Only, No Cash Back Allowed仅允许消费金额，不允许现金返还检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60088Cryptographic failure加密校验失败检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60089Financial position information is not available or PIN retry required无法获取财务状态信息或 PIN 需重试检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60090Cutoff is in progressCutoff 处理中请客户联系发卡机构确认，或换用其他卡60091Issuer or authorization system unavailable发卡机构或授权系统不可用24 小时后重试；请客户联系发卡机构确认；请客户换用其他卡60092Unable to route transaction交易无法路由联系 Onerway 支持60093Transaction violates legal or regulatory requirements交易违反法律或监管要求请客户联系发卡机构确认；不要重试60094Duplication transaction detected检测到重复交易确认交易是否已成功60096System malfunction系统故障检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡60100Exceeds authentication frequency limit超过认证频次限制请客户联系发卡机构确认；请客户换用其他卡；联系 Onerway 支持60101Cancelled交易已取消请客户联系发卡机构确认；请客户换用其他卡；联系 Onerway 支持60102Duplicate transaction重复交易确认交易是否已成功60103Soft decline软拒绝请客户换用其他卡，或完成 3DS challenge60104Hard decline硬拒绝不要重试60105Refund failed退款失败联系 Onerway 支持60106Customer did not pay before the order timed out用户未在有效时间内完成支付，订单已超时关闭请客户在订单有效时间内完成支付60129Suspected Counterfeit Card疑似伪卡请客户联系发卡机构确认；请客户换用其他卡6001AAdditional customer authentication required需要额外客户认证请客户换用其他卡，或完成 3DS 认证6001ZAuthorization system inoperative授权系统不可用请客户联系发卡机构确认，或换用其他卡6006PVerification data failed验证数据失败检查卡片信息后重试；完成 3DS 认证；请客户换用其他卡600B1Surcharge amount not permitted on Visa cards or EBT food stamps (U.S. acquirers only)Visa 卡或美国 EBT 食品券不允许收取附加费请客户换用其他卡600B2Surcharge amount not supported by debit network issuer.借记网络发卡机构不支持附加费请客户换用其他卡600N0Issuer forces stand-in processing发卡机构要求走 STIP 代授权处理检查卡片信息后重试；完成 3DS 认证；请客户换用其他卡600N3Cash service not available现金服务不可用请客户联系发卡机构确认；稍后重试；调整金额；请客户换用其他卡600N4Cash request exceeds issuer or approved limit现金请求超过发卡机构或已批准限额请客户联系发卡机构确认；调整金额；请客户换用其他卡600N5Ineligible for resubmission不符合重新提交条件请客户联系发卡机构确认；请客户换用其他卡600N7Decline for card verification code failureCVC 校验失败导致拒绝检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡600N8Transaction amount exceeds preauthorized approval amount交易金额超过预授权批准金额确认请款金额不超过预授权金额600P5Denied PIN unblock—PIN change or unblock request declined by issuer发卡机构拒绝 PIN 解锁请求请客户联系发卡机构确认，或换用其他卡600P6Denied PIN change—requested PIN unsafe发卡机构拒绝 PIN 变更请求请客户联系发卡机构确认，或换用其他卡600Q1Card Authentication failed卡片认证失败检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡600R0Stop this payment停止本次支付不要重试；联系 Onerway 支持600R1Stop all future payments停止所有后续支付不要重试；联系 Onerway 支持600R2Transaction does not qualify for Visa PIN交易不符合 Visa PIN 条件请客户联系发卡机构确认，或换用其他卡600R3Stop all merchants停止所有商户交易不要重试；联系 Onerway 支持600Z3Unable to go online; offline declined无法联机，离线拒绝检查卡片信息后重试；请客户联系发卡机构确认；请客户换用其他卡",{"id":3577,"title":3578,"titles":3579,"content":3580,"level":615},"\u002Fzh\u002Fpayments\u002Fapi-reference\u002Fresponse-codes#通用错误70xxx","通用错误（70xxx）",[2441],"错误码message中文说明建议处理70001Common decline通用拒绝联系 Onerway 支持70002Unknown decline未知拒绝联系 Onerway 支持",{"id":2451,"title":2455,"titles":3582,"content":3583,"level":609},[],"跨境资金划转与打款服务。 在调用 Transfer API 之前，请先完成沙盒开户、白名单配置和商户凭证准备。建议先把环境和商户信息准备好，再进入签名和集成流程。",{"id":3585,"title":3586,"titles":3587,"content":3588,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#概述","概述",[2455],"沙盒环境和生产环境的差异主要在请求域名。建议先在沙盒环境完成联调，再切换到生产环境。 环境准备主要包括以下事项： 提供开户邮箱提供测试对接域名等待开通邮件登录商户后台获取商户凭证完成白名单和后续配置",{"id":3590,"title":3591,"titles":3592,"content":3593,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#环境说明","环境说明",[2455],"生产环境和沙盒环境的请求地址仅域名不同。也就是说，接入流程通常是： 先在沙盒环境完成联调验证签名和打款流程再切换生产域名和生产配置 这样可以先在测试环境暴露问题，避免把环境和业务问题叠加到生产切换阶段。",{"id":3595,"title":3596,"titles":3597,"content":3598,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#环境域名","环境域名",[2455],"环境域名沙盒环境https:\u002F\u002Fsandbox-api.onerway.com\u002Fpayout生产环境https:\u002F\u002Fapi.onerway.com\u002Fpayout",{"id":3600,"title":3601,"titles":3602,"content":3603,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#商户开通与白名单","商户开通与白名单",[2455],"创建沙盒测试商户前，请先准备： 开户邮箱对接测试使用的域名 开户邮箱会用于创建沙盒账户。提交的域名会被加入白名单，只有白名单中的域名才能调用 Onerway API。 这意味着在环境准备阶段，除了“有没有账号”，还要确认： 域名是否已经提交域名是否已经加入白名单当前实际发起请求的来源是否与白名单配置一致 如果域名未完成白名单配置，即使请求报文本身正确，也可能无法正常调用接口。",{"id":3605,"title":3606,"titles":3607,"content":3608,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#商户凭证","商户凭证",[2455],"收到开通邮件后，请通过邮件中的商户后台链接登录。首次登录需要先重置密码，随后获取商户凭证。 在 Transfer 中，请使用实际请求字段名 merchantNo。 您通常需要准备： merchantNo与签名方式对应的密钥或私钥 Transfer 文档统一使用 merchantNo，不要替换成 merchantId。",{"id":3610,"title":3611,"titles":3612,"content":3613,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#字段必填标识","字段必填标识",[2455],"字段表使用以下标识： 标识含义M必填C条件必填N选填",{"id":3615,"title":3616,"titles":3617,"content":3618,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#接入前准备清单","接入前准备清单",[2455],"在开始构造请求报文、创建收款方或发起打款前，请确认： 沙盒账户已开通对接域名已加入白名单已从商户后台获取商户凭证已确认签名方式已确认目标国家、币种、打款方式和主体类型下的必填字段 完成这里的准备后，后续通常继续进入： 请求签名准备集成流程确认Sandbox 测试与上线准备",{"id":3620,"title":3621,"titles":3622,"content":3623,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started#继续阅读","继续阅读",[2455],"请求签名集成流程测试与上线",{"id":2457,"title":2149,"titles":3625,"content":3626,"level":609},[],"了解 Transfer API 的两种签名方式以及对应示例。 Transfer API 提供两种签名方式：SHA256withRSA 和 SHA256。请使用 Onerway 为您的商户配置的签名方式。",{"id":3628,"title":3629,"titles":3630,"content":3631,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#开始前说明","开始前说明",[2149],"请先确认商户对应的签名方式。两种签名方式使用的密钥类型、签名串规则和输出格式都不相同。",{"id":3633,"title":1510,"titles":3634,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#sha256withrsa",[2149],{"id":3636,"title":3637,"titles":3638,"content":3639,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#签名步骤","签名步骤",[2149,1510],"获取 privateKey使用 SHA256withRSA 算法将待签名字符串转换为 UTF-8生成签名对签名结果进行 Base64 编码",{"id":3641,"title":3642,"titles":3643,"content":3644,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#签名串规则","签名串规则",[2149,1510],"剔除所有值为空的参数，将剩余参数按参数名 ASCII 顺序排序，然后按 key=value&key1=value1... 的格式拼接，最后一个参数后面不加 &。",{"id":3646,"title":3647,"titles":3648,"content":1526,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例私钥","示例私钥",[2149,1510],{"id":3650,"title":3651,"titles":3652,"content":1531,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例请求数据","示例请求数据",[2149,1510],{"id":3654,"title":3655,"titles":3656,"content":1536,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例签名串","示例签名串",[2149,1510],{"id":3658,"title":3659,"titles":3660,"content":1541,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例签名结果","示例签名结果",[2149,1510],{"id":3662,"title":1544,"titles":3663,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#sha256",[2149],{"id":3665,"title":3637,"titles":3666,"content":3667,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#签名步骤-1",[2149,1544],"获取密钥将签名串和密钥拼接为字符串将结果转换为 UTF-8执行 SHA-256 摘要将摘要结果转换为十六进制字符串",{"id":3669,"title":3642,"titles":3670,"content":3671,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#签名串规则-1",[2149,1544],"剔除所有签名列中为 No 的参数，以及值为空的参数。将剩余参数按参数名 ASCII 顺序排序，仅拼接参数值，最后再追加密钥。",{"id":3673,"title":3674,"titles":3675,"content":1558,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例密钥","示例密钥",[2149,1544],{"id":3677,"title":3651,"titles":3678,"content":1562,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例请求数据-1",[2149,1544],{"id":3680,"title":3655,"titles":3681,"content":1566,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例签名串-1",[2149,1544],{"id":3683,"title":3659,"titles":3684,"content":1570,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#示例签名结果-1",[2149,1544],{"id":3686,"title":2748,"titles":3687,"content":3688,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Frequest-signing#下一步",[2149],"环境准备集成流程测试与上线 html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .smIuJ, html code.shiki .smIuJ{--shiki-light:#39ADB5;--shiki-default:#024C1A;--shiki-dark:#89DDFF}html pre.shiki code .sDKE3, html code.shiki .sDKE3{--shiki-light:#9C3EDA;--shiki-default:#024C1A;--shiki-dark:#C792EA}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sP_HR, html code.shiki .sP_HR{--shiki-light:#E53935;--shiki-default:#024C1A;--shiki-dark:#F07178}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .s8Af6, html code.shiki .s8Af6{--shiki-light:#F76D47;--shiki-default:#023B95;--shiki-dark:#F78C6C}",{"id":2461,"title":2460,"titles":3690,"content":3691,"level":609},[],"按四阶段流程完成 Transfer 集成，从前置准备到结果闭环。 Transfer 接入可分为四个阶段：前置准备、发起打款、获取结果和交易结束。",{"id":3693,"title":3586,"titles":3694,"content":3695,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#概述",[2460],"发起打款前，请先确认收款方字段要求。必填字段会随着国家、币种、打款方式和主体类型的不同而变化。",{"id":3697,"title":3698,"titles":3699,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#第一阶段前置准备","第一阶段：前置准备",[2460],{"id":3701,"title":3702,"titles":3703,"content":3704,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#确认收款方字段要求","确认收款方字段要求",[2460,3698],"可使用以下方式之一： 调用 POST \u002Fapi\u002Fv1\u002Facct\u002FqueryPaymentFeild 查询必填字段联系客户经理，获取目标国家、币种、打款方式和主体类型对应的字段模板",{"id":3706,"title":3707,"titles":3708,"content":3709,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#准备收款方信息","准备收款方信息",[2460,3698],"拿到字段要求后，请按返回结果或模板收集并校验收款方信息。 这一阶段的重点是： 先确认目标国家和币种下支持的打款方式再确认该打款方式下的必填字段按字段模板准备收款方、地址和账户信息 如果前置字段没有确认完整，后续无论是创建收款方还是直接发起打款，都容易因为字段缺失或格式不符而失败。",{"id":3711,"title":3712,"titles":3713,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#第二阶段发起打款","第二阶段：发起打款",[2460],{"id":3715,"title":3716,"titles":3717,"content":3718,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#判断使用哪条路径","判断使用哪条路径",[2460,3712],"条件路径已由 Onerway 开通实时打款实时路径未开通实时打款默认路径 已开通实时路径时，可以在一次请求中直接提交收款方信息并发起打款未开通实时路径时，需要先维护收款方，再通过 beneficiaryId 发起打款",{"id":3720,"title":3721,"titles":3722,"content":874,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#默认路径","默认路径",[2460,3712],{"id":3724,"title":3725,"titles":3726,"content":3727,"level":1615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_1-创建收款人-id","1. 创建收款人 ID",[2460,3712,3721],"录入或导入收款方信息调用 POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002Fadd保存返回的 beneficiaryId 这一步是默认路径的起点。默认路径不是“边填边打款”，而是先把收款方资料沉淀成可复用的记录。",{"id":3729,"title":3730,"titles":3731,"content":3732,"level":1615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_2-收款方复用逻辑","2. 收款方复用逻辑",[2460,3712,3721],"判断已有 beneficiaryId 是否可以继续复用如信息一致，可直接继续使用已有 beneficiaryId如信息不一致，先调用 POST \u002Fapi\u002Fv1\u002Fbeneficiary\u002Fedit 更新，再继续使用原 beneficiaryId 这里需要优先复用已有收款方记录。如果收款方信息仍然有效，优先复用原记录；只有信息发生变化时，才先更新再继续下发。",{"id":3734,"title":3735,"titles":3736,"content":3737,"level":1615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_3-发起打款请求","3. 发起打款请求",[2460,3712,3721],"调用 POST \u002Fapi\u002Fv1\u002Ftxn\u002Fremittance交易进入 Onerway 打款处理流程 完成这一步后，交易就进入处理阶段。同步响应只能说明请求已被系统接收，不代表最终结果已经确认。",{"id":3739,"title":3740,"titles":3741,"content":3742,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#实时路径","实时路径",[2460,3712],"实时打款需要由 Onerway 预先开通。",{"id":3744,"title":3745,"titles":3746,"content":3747,"level":1615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_1-动态提交收款方信息","1. 动态提交收款方信息",[2460,3712,3740],"调用 POST \u002Fapi\u002Fv2\u002Ftxn\u002Fremittance在请求体中直接提交收款方信息无需预先创建 beneficiaryId",{"id":3749,"title":3750,"titles":3751,"content":3752,"level":1615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#_2-发起打款","2. 发起打款",[2460,3712,3740],"提交请求交易直接进入打款处理流程 相比默认路径，实时路径少了一步“预创建收款方”。这条路径有开通前提，不能默认认为所有商户都可以直接使用。",{"id":3754,"title":3755,"titles":3756,"content":3757,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#第三阶段获取结果","第三阶段：获取结果",[2460],"可以通过以下两种方式获取打款结果： 主动查询：POST \u002Fapi\u002Fv1\u002Ftxn\u002Fquery异步通知：webhook 回调",{"id":3759,"title":3760,"titles":3761,"content":3762,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#结果获取方式","结果获取方式",[2460,3755],"结果获取分成“主动查询”和“异步推送”两条线： 主动查询适合补偿确认、对账或排查问题异步推送适合作为生产环境里的主结果通道",{"id":3764,"title":3765,"titles":3766,"content":3767,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#推送内容包括","推送内容包括",[2460,3755],"回调报文中通常包含： 交易状态失败时的错误码失败时的错误描述 这也是为什么同步响应成功后仍然要继续跟踪最终状态。",{"id":3769,"title":3770,"titles":3771,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#第四阶段交易结束","第四阶段：交易结束",[2460],{"id":3773,"title":3774,"titles":3775,"content":3776,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#打款成功","打款成功",[2460,3770],"调用 POST \u002Fapi\u002Fv1\u002Ftxn\u002FqueryVoucher 获取电子回单",{"id":3778,"title":3779,"titles":3780,"content":3781,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#打款未成功","打款未成功",[2460,3770],"查询失败原因按内部流程进入人工处理或重试 这一阶段的重点是： 成功单据进入留痕、回单下载和对账流程非成功单据需要按错误原因进入重试或人工处理流程只有完成结果确认和后续动作，交易链路才算真正闭环",{"id":3783,"title":3784,"titles":3785,"content":3786,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#推荐操作方式","推荐操作方式",[2460],"生产环境建议采用以下模式： 以 webhook 作为主结果通道保留查询接口，用于对账、重试判断和兜底确认在信息仍然有效时复用已有收款方记录",{"id":3788,"title":3789,"titles":3790,"content":3791,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#注意事项","注意事项",[2460],"未开通实时路径时，应优先走默认路径，不要直接提交实时打款请求使用默认路径时，请妥善保存 beneficiaryId，避免重复创建收款方打款请求成功受理后，仍需通过 webhook 或查询接口确认最终结果交易成功后如需留痕或提供凭证，应继续调用电子回单接口",{"id":3793,"title":3621,"titles":3794,"content":3795,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fintegration-flow#继续阅读",[2460],"环境准备请求签名测试与上线",{"id":2465,"title":2464,"titles":3797,"content":3798,"level":609},[],"在 Sandbox 完成 Transfer 验证，并准备生产上线前的最终清单。 在切换到 Production 之前，请先在 Sandbox 中完成完整打款链路验证。建议把环境准备、四阶段流程和回调处理一并验证，再进入上线阶段。",{"id":3800,"title":3801,"titles":3802,"content":3803,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#为什么要先在-sandbox-完整验证","为什么要先在 Sandbox 完整验证",[2464],"至少要先验证以下基础能力： 白名单和环境域名是否正确商户凭证和签名是否可用收款方资料是否能按字段模板准备成功打款请求是否能进入处理流程最终结果是否能通过 webhook 或查询接口闭环 如果这些环节只验证一部分，就很容易在上线时遇到“请求能发，但链路没有闭环”的问题。",{"id":3805,"title":3806,"titles":3807,"content":3808,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#建议验证内容","建议验证内容",[2464],"请求签名是否稳定可用beneficiaryId 的创建、复用和查询链路是否正常发起打款后是否能收到 webhook 通知对于未闭环订单，主动查询是否能补齐结果成功订单是否能按需下载电子回单",{"id":3810,"title":3811,"titles":3812,"content":3813,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#额外值得验证的点","额外值得验证的点",[2464],"除了验证主流程成功，还建议补充检查： 重复通知下的幂等处理异常状态下的恢复逻辑失败原因是否能在内部系统中被记录和展示payer、beneficiary 与业务订单 ID 的映射是否完整回单下载、归档和后续访问是否满足内部要求",{"id":3815,"title":3816,"titles":3817,"content":3818,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#推荐测试顺序","推荐测试顺序",[2464],"验证环境、白名单和密钥配置确认目标国家、币种、主体类型下的打款方式查询该组合下的必填字段创建测试收款方通过 beneficiaryId 发起一笔打款接收 webhook 并更新订单状态对未闭环订单执行主动查询对成功订单下载电子回单 如果您的业务同时使用 beneficiaryId 路径和“直接提交收款方信息”路径，请分别验证这两条路径，不要只验证其中一条。",{"id":3820,"title":3821,"titles":3822,"content":3823,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#上线前清单","上线前清单",[2464],"生产域名和白名单配置已确认生产密钥已安全存储回调地址已可被公网访问服务端已支持验签、幂等处理和重试安全业务系统具备清晰的状态流转和异常恢复流程已确认最终使用 webhook、主动查询或两者结合的闭环方式",{"id":3825,"title":3144,"titles":3826,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#常见问题",[2464],{"id":3828,"title":3829,"titles":3830,"content":3831,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#什么时候应该确认-merchantno密钥和回调地址","什么时候应该确认 merchantNo、密钥和回调地址？",[2464,3144],"最好在联调开始前确认，而不是等到上线前临时处理。否则很容易被签名失败、白名单不一致或回调不可达这类基础问题阻塞。",{"id":3833,"title":3834,"titles":3835,"content":3836,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#上线前最容易漏掉的是什么","上线前最容易漏掉的是什么？",[2464,3144],"最常见的是异常闭环，包括 webhook 重试、主动查询补偿、失败原因落库，以及对未闭环订单的定时巡检。",{"id":3838,"title":3839,"titles":3840,"content":3841,"level":667},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#只验证同步响应成功是否足够","只验证同步响应成功，是否足够？",[2464,3144],"不够。同步响应成功并不代表交易结束。至少还要验证 webhook 或主动查询能否拿到最终状态。 如果您的业务会批量提交打款，也建议在上线前一并验证批量查询、监控告警和对账流程。",{"id":3843,"title":3621,"titles":3844,"content":3845,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Ftesting-and-go-live#继续阅读",[2464],"环境准备请求签名集成流程变更记录",{"id":2469,"title":2468,"titles":3847,"content":3848,"level":609},[],"查看打款文档指南的版本变更记录。 本文档记录打款文档指南的版本变更，用于保留当前版本说明信息。 本页当前仅保留最新版本记录。",{"id":3850,"title":1741,"titles":3851,"content":3852,"level":615},"\u002Fzh\u002Ftransfer\u002Fget-started\u002Fchange-log#v1-2026-07-10",[2468],"调整打款文档指南结构，仅保留环境准备、请求签名、集成流程、测试与上线、变更记录五个页面。",{"id":2483,"title":2482,"titles":3854,"content":3855,"level":609},[],"查询指定国家、币种和主体类型支持的打款方式。 不同国家支持的打款方式可能不同；该接口用于查询指定国家、币种和主体类型支持的打款方式。",{"id":2487,"title":2486,"titles":3857,"content":3858,"level":609},[],"查询指定国家、币种、主体类型和打款方式下的字段要求。",{"id":2491,"title":2490,"titles":3860,"content":3861,"level":609},[],"创建可用于后续 Transfer 打款的收款方。",{"id":2495,"title":2494,"titles":3863,"content":3864,"level":609},[],"查询单个收款方的资料详情和审核状态。",{"id":2499,"title":2498,"titles":3866,"content":3867,"level":609},[],"创建可用于后续 Transfer 打款的打款方。",{"id":2503,"title":2502,"titles":3869,"content":3870,"level":609},[],"使用已审核通过的收款人 ID 发起 Transfer 打款。",{"id":3872,"title":3873,"titles":3874,"content":3875,"level":609},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fendpoints\u002Finitiate-transfer-with-beneficiary-details","实时收款方信息打款",[],"在发起打款时直接提交收款方详情。",{"id":2507,"title":2506,"titles":3877,"content":3878,"level":609},[],"通过商户流水号或 Onerway 打款流水号查询单笔打款。",{"id":2511,"title":2510,"titles":3880,"content":3881,"level":609},[],"分页查询多笔打款记录。",{"id":2515,"title":2514,"titles":3883,"content":3884,"level":609},[],"查询并下载成功打款对应的电子凭证。",{"id":2519,"title":2518,"titles":3886,"content":3887,"level":609},[],"分页查询收款人记录。",{"id":2523,"title":2522,"titles":3889,"content":3890,"level":609},[],"更新已有收款人的资料信息。",{"id":2527,"title":2526,"titles":3892,"content":3893,"level":609},[],"删除不再使用的收款人。",{"id":2531,"title":2530,"titles":3895,"content":3896,"level":609},[],"分页查询已保存的打款方。",{"id":2535,"title":2534,"titles":3898,"content":3899,"level":609},[],"更新已有打款方资料。",{"id":2539,"title":2538,"titles":3901,"content":3902,"level":609},[],"删除不再使用的打款方。",{"id":2543,"title":2542,"titles":3904,"content":3905,"level":609},[],"查询商户账户支持的币种及余额。 用于查询商户账户支持的所有币种及其对应余额。",{"id":2547,"title":2546,"titles":3907,"content":3908,"level":609},[],"查询指定币种下的账户余额和交易明细。",{"id":2551,"title":2550,"titles":3910,"content":3911,"level":609},[],"查询源币种到目标币种的参考汇率。 用于查询源币种到目标币种的参考汇率及换算金额。",{"id":2473,"title":2455,"titles":3913,"content":3914,"level":609},[],"查看 Transfer 的接口、Webhook、响应码和常用枚举说明。",{"id":3916,"title":3917,"titles":3918,"content":874,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference#这一组包含什么","这一组包含什么？",[2455],{"id":3920,"title":2239,"titles":3921,"content":3922,"level":667},"\u002Fzh\u002Ftransfer\u002Fapi-reference#接口",[2455,3917],"收录 Transfer 相关接口，包括： 打款方式和必填字段查询收款方与打款方管理接口打款发起、查询、批量查询和电子回单下载账户信息和汇率相关接口",{"id":3924,"title":3925,"titles":3926,"content":3927,"level":667},"\u002Fzh\u002Ftransfer\u002Fapi-reference#webhook","Webhook",[2455,3917],"收录打款结果通知相关内容，用于说明回调报文、请求头约定和服务端应答要求。",{"id":3929,"title":3930,"titles":3931,"content":3932,"level":667},"\u002Fzh\u002Ftransfer\u002Fapi-reference#响应码与枚举","响应码与枚举",[2455,3917],"收录常见响应码、打款状态值、业务枚举和常见对象字段说明。",{"id":3934,"title":3935,"titles":3936,"content":3937,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference#什么情况下看这里","什么情况下看这里",[2455],"如果您当前需要： 确认某个接口的请求方法和路径查看请求或响应字段对照 webhook 报文结构核对响应码、状态值或枚举说明 那么就应优先查看这一组页面。 如果您需要先了解接入流程、操作顺序或场景说明，则建议先返回 Get Started 或 Online Payments。",{"id":2560,"title":2559,"titles":3939,"content":3940,"level":609},[],"接收打款状态变更后的异步回调，并据此更新您的业务订单状态。",{"id":2564,"title":2563,"titles":3942,"content":3943,"level":609},[],"查看 Transfer 接口常见响应码、打款状态值以及相关枚举字典。",{"id":3945,"title":3946,"titles":3947,"content":3948,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#status-状态","Status 状态",[2563],"Status状态码描述说明A待审核交易已创建，等待审核CA合规审核中交易正在进行合规审核B待检查交易等待系统检查U审核不通过交易未通过人工审核V检查不通过交易未通过系统检查R待出款交易已通过审核，等待出款P出款中交易正在出款处理中S成功交易已成功完成F失败交易处理失败",{"id":3950,"title":3951,"titles":3952,"content":3953,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#全额到账标识","全额到账标识",[2563],"chargeFlag状态码描述说明Y全额到账收款方收到的金额等于目标金额N非全额到账收款方收到的金额可能少于目标金额",{"id":3955,"title":3956,"titles":3957,"content":3958,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#swift-打款手续费承担方式","SWIFT 打款手续费承担方式",[2563],"feeBearing状态码描述说明SHA费用分摊SWIFT 费用在打款方和收款方之间分摊OUR打款方承担打款方承担所有 SWIFT 相关费用，收款方收到全额",{"id":3960,"title":3961,"titles":3962,"content":3963,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#transactionpurpose-交易用途","transactionPurpose 交易用途",[2563],"transactionPurpose代码描述说明0转至本人账户资金转入本人其他账户1个人汇款个人之间的资金转账2贷款或信贷偿还用于偿还贷款或信用账单3技术服务支付技术服务费用4运费支付运输相关费用5专业服务\u002F商业服务支付专业或商业服务费用",{"id":3965,"title":3966,"titles":3967,"content":3968,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#payoutmethod-打款方式","payoutMethod 打款方式",[2563],"payoutMethod代码描述说明SWIFTSWIFT打款通过SWIFT网络进行国际转账BANK_TRANSFER银行打款通过本地银行网络转账E_WALLET钱包打款转账至电子钱包账户CASH_PICKUP现金支取收款人可到指定地点提取现金",{"id":3970,"title":3971,"titles":3972,"content":3973,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#entitytype-主体类型","entityType 主体类型",[2563],"entityType代码描述说明0公司企业法人账户1个人自然人账户",{"id":3975,"title":3976,"titles":3977,"content":3978,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#currency-币种","currency 币种",[2563],"currency代码描述说明USD美元美利坚合众国法定货币EUR欧元欧盟成员国法定货币GBP英镑英国法定货币JPY日元日本法定货币PHP菲律宾比索菲律宾法定货币IDR印尼盾印度尼西亚法定货币THB泰铢泰国法定货币MYR马来西亚林吉特马来西亚法定货币",{"id":3980,"title":3981,"titles":3982,"content":3983,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#receiverinfo-收款人信息","receiverInfo 收款人信息",[2563],"receiverInfo参数名类型说明companyNamestring(64)公司名称lastNamestring(64)姓firstNamestring(64)名areaCodestring(32)区号phonestring(16)手机号vatNumberstring(64)增值税号 CPF\u002FCNPJbirthDatestring出生日期(yyyy-MM-dd)emailstring(32)收款人邮箱，条件字段identityTypestring(32)证件类型（例如，SSN等），条件字段",{"id":3985,"title":3986,"titles":3987,"content":3988,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#address-地址","address 地址",[2563],"address 字段说明参数名类型说明statestring(20)省\u002F州citystring(64)城市addressLine1string(256)地址1addressLine2string(256)地址2addressLine3string(256)地址3postalCodestring(32)邮编",{"id":3990,"title":3991,"titles":3992,"content":3993,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#accountinfomation-账户信息","accountInfomation 账户信息",[2563],"accountInfomation 字段说明参数名类型说明cardNumberstring(20)卡号\u002FibanaccountTypestring(64)账户类型 0:checking, 1:saving, 2:ordinaryswiftCodestring(256)swift codebankNamestring(250)银行名称选填,填写以这个为准sortCodestring(256)Sort Code\u002FABAbranchCodestring(256)分行编号bankHolderNamestring(32)银行账户名walletTypestring(20)钱包类型walletPhonestring(64)钱包值pickUpBankNamestring(256)取款机构pickUpBankBranchNamestring(256)分支机构pickUpBankBranchIdstring(256)分支机构IDpickUpBankBranchAddressstring(32)分支机构地址",{"id":3995,"title":3996,"titles":3997,"content":3998,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#respcode-响应码","respCode 响应码",[2563],"respCode代码描述说明0000成功请求处理成功1001参数错误请求参数不符合要求1002签名错误请求验签失败1003余额不足账户余额不足以完成交易1004限额超限超过交易限额2001系统错误系统内部处理异常2002网络超时网络连接超时3001账户冻结账户被冻结无法操作3002重复请求重复提交的请求 说明所有枚举值区分大小写币种代码遵循 ISO 4217 标准响应码仅列出常见状态，详细错误码请参考错误码文档",{"id":4000,"title":4001,"titles":4002,"content":4003,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#records-字段说明","records 字段说明",[2563],"参数名类型说明payoutIdintegerIDpaymentMethodstring交易方式payoutTypestring出款类型settleCurrencystring结算币种settleSumAmountnumber结算单汇总金额serviceFeenumber手续费otherFeenumber其他费用frozenAmountnumber风控冻结金额settleAmountnumber实际结算金额payoutCurrencystring出款币种payoutAmountnumber出款金额convRatenumber转换汇率merchantNointeger商户号payeeIdinteger收款方IDpayeeNamestring收款方名称payeeBankNamestring收款方银行名称payeeBankAddressstring收款方银行地址payeeAccountstring收款方账号payeeAccountCountrystring收款账户所在国家payeeAccountNamestring收款账户户名payeeAccountSwiftCodestring收款账户 SWIFT CODEpayeeAccountLocalCodestring收款账户 LOCAL CODEpayeeCountrystring收款方国家payeeAddressstring收款方地址mobileNumberstring手机号payoutStatusstring出款状态payoutTipsstring客户提示payoutRemarkstring异常提示payoutTimestring出款时间distributeStatusstring代付状态distributePsstring交易附言transactionPurposestring交易用途remarkstring备注createTimestring创建时间updateTimestring更新时间payoutMethodstring打款方式payoutMethod枚举值firstNamestring收款方-名字lastNamestring收款方-姓氏companyNamestring公司名称",{"id":4005,"title":4006,"titles":4007,"content":4008,"level":615},"\u002Fzh\u002Ftransfer\u002Fapi-reference\u002Fresponse-codes#payeestatus-状态说明","payeeStatus 状态说明",[2563],"参数名类型说明WAITINGString等待中PROCESSString处理中REJECTString已拒绝PASSString已通过FAILString失败UNNECESSARYString不需要PENDING_UPDATEString待更新",{"id":2572,"title":2455,"titles":4010,"content":4011,"level":609},[],"面向平台与企业的预付虚拟卡发卡服务，覆盖开卡、持卡人管理、交易查询与卡片生命周期管理。 使用 Onerway Issuing 创建并管理用于线上采购场景的预付虚拟卡。完成开户注册和开卡后，你可以管理卡片状态、查询交易记录，并接收卡操作和卡交易事件通知。",{"id":4013,"title":4014,"titles":4015,"content":4016,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started#核心能力","核心能力",[2455],"通过 Onerway 平台发行预付虚拟卡使用商户后台进行可视化操作，或通过 API 完成自动化发卡流程管理卡片生命周期，包括冻结、解冻、注销、充值和余额退回跟踪授权、结算、退款、验证等卡交易记录和事件状态由 Onerway 承担敏感卡数据相关的 PCI DSS 合规处理边界",{"id":4018,"title":4019,"titles":4020,"content":4021,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started#商户流程","商户流程",[2455],"步骤说明开通账户注册账户，提交 KYC 材料，审核通过后获得发卡权限。账户入金提交入金请求，使对应币种账户余额可用于开卡和卡片操作。选择卡产品与 Onerway 确认卡产品、发卡市场、币种、卡组织和使用规则。创建持卡人创建与卡片关联、承担卡消费责任的持卡人。创建卡片关联持卡人，设置充值金额，并创建虚拟卡。卡片消费开卡成功后，卡片可用于线上消费。交易查询与管理查询交易记录，管理卡片状态，并在适用场景下处理争议等后续动作。",{"id":4023,"title":2735,"titles":4024,"content":4025,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started#从这里开始",[2455],"接入准备 — 准备发卡环境、ApiKey、IP 白名单、商户凭据和事件回调地址接口说明 — 查看公共请求 Header、响应结构、币种与时间戳规则、响应码创建持卡人 — 创建开卡前所需的持卡人创建卡片 — 为持卡人创建预付虚拟卡事件推送 — 接收卡操作和卡交易异步事件",{"id":2577,"title":2145,"titles":4027,"content":4028,"level":609},[],"调用发卡 API 前，请仔细阅读下面流程。",{"id":4030,"title":2743,"titles":4031,"content":4032,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started\u002Fsetup#接入步骤",[2145],"选择请求域名请使用与 ApiKey 所属环境一致的请求域名。环境Base URLProductionhttps:\u002F\u002Fissuer.onerway.com\u002Fapi\u002Fv1\u002FmerchantSandboxhttps:\u002F\u002Fsandbox-issuer.onerway.com\u002Fapi\u002Fv1\u002Fmerchant沙盒与生产环境的凭据相互独立。接口路径、请求方法和请求结构保持一致，但请求域名和 ApiKey 必须来自同一环境。创建沙盒商户账户向 Onerway 提供邮箱、来源 IP 和事件接收 URL。沙盒账户创建后，请通过邮件链接登录商户后台，并获取用于接入和 webhook 验签的商户号与密钥。提供来源 IP调用发卡 API 前，请向 Onerway 提供稳定的服务端来源 IP，用于配置发卡访问白名单。仅提交稳定的服务端来源 IP。如果沙盒与生产环境使用不同来源 IP，请分别提供。如果来源 IP 发生变更，请在切换流量前更新白名单。安全保存凭据发卡 API 通过 ApiKey 请求 Header 识别调用方权限。请在服务端保存 ApiKey、商户号和 webhook secret。不要把发卡凭据暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。配置事件回调配置可接收卡操作和卡交易事件 webhook 的服务端回调地址。回调服务必须校验 x-signature，按 request_id 做事件去重，并在受理事件后返回 respCode=20000。",{"id":4034,"title":2906,"titles":4035,"content":4036,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started\u002Fsetup#接入流程",[2145],"步骤动作接口或来源1获取卡产品信息，并与 Onerway 确认 productId。Card product list2创建与卡产品匹配的持卡人。创建持卡人3使用 productId、cardholderId 和充值金额创建卡片。创建卡片4按需查询卡片操作进度、基础信息、余额和敏感信息。卡片查询5接收卡操作事件通知。卡操作事件6查询卡交易记录，并接收交易事件通知。查询交易记录",{"id":4038,"title":2748,"titles":4039,"content":4040,"level":615},"\u002Fzh\u002Fissuing\u002Fget-started\u002Fsetup#下一步",[2145],"接口说明 — 查看发卡 API 公共规则创建持卡人 — 开卡前创建持卡人创建卡片 — 创建第一张虚拟卡事件推送 — 配置卡操作和卡交易事件处理",{"id":2580,"title":2584,"titles":4042,"content":4043,"level":609},[],"查看发卡 API 的公共请求 Header、响应结构、币种与时间戳规则、响应码。 接入发卡 API 前，请先阅读本页公共规则。除非具体接口页另有说明，发卡商户 API 均使用 \u002Fapi\u002Fv1\u002Fmerchant base path 下的 POST 请求。",{"id":4045,"title":4046,"titles":4047,"content":4048,"level":667},"\u002Fzh\u002Fissuing\u002Fapi-reference#请求-header","请求 Header",[2584],"HeaderTypeRequired说明Content-TypeStringYes使用 application\u002Fjson;charset=UTF-8。ApiKeyStringYesOnerway 分配的发卡 API 商户身份凭据。",{"id":4050,"title":4051,"titles":4052,"content":4053,"level":667},"\u002Fzh\u002Fissuing\u002Fapi-reference#响应结构","响应结构",[2584],"字段Type说明respCodeString响应码。20000 表示请求处理成功。respMsgString响应信息。dataObject \u002F Array业务数据。请求失败时可为 null。",{"id":4055,"title":4056,"titles":4057,"content":4058,"level":667},"\u002Fzh\u002Fissuing\u002Fapi-reference#币种","币种",[2584],"币种值使用 ISO 4217 国际标准。",{"id":4060,"title":4061,"titles":4062,"content":4063,"level":667},"\u002Fzh\u002Fissuing\u002Fapi-reference#时区","时区",[2584],"Long 类型时间戳均为 UTC 时间戳。查询参数默认使用秒，除非具体接口页另有说明；操作、结算、授权和交易事件时间可按毫秒返回。",{"id":4065,"title":2441,"titles":4066,"content":4067,"level":667},"\u002Fzh\u002Fissuing\u002Fapi-reference#响应码",[2584],"当 HTTP 状态码不是 200 时： HTTP 状态码说明401 UnauthorizedAPI 凭据无效。403 Forbidden触发 IP 白名单限制或 API 权限不足。 当 HTTP 状态码为 200 时，请读取业务响应码： Code说明20000成功。40000参数错误。80000内部服务错误，请联系 Onerway。80001持卡人不存在。80002持卡人邮箱已存在。80003持卡人所属商户号不正确。80004商户状态无效。80005商户未开通发卡业务。80006商户账户不存在。80007商户余额不足。80008充值金额超过最大限制。80009充值金额低于最小限制。80010数据重复。80011持卡人卡数量达到限制。81000未授权商户。81001业务不存在。40004系统异常：NoHandlerFoundException。40005系统异常：HttpRequestMethodNotSupportedException。40013系统异常：HttpMessageNotReadableException。40015系统异常：HttpMediaTypeNotSupportedException。",{"id":2591,"title":2590,"titles":4069,"content":4070,"level":609},[],"为指定持卡人和卡产品创建预付虚拟卡。 使用此接口为持卡人创建指定卡产品的卡片，并设置初始充值金额。",{"id":2595,"title":2594,"titles":4072,"content":4073,"level":609},[],"冻结、解冻或注销已有卡片。 使用此接口对卡片执行状态操作，例如冻结、解冻或注销。",{"id":2599,"title":2598,"titles":4075,"content":4076,"level":609},[],"向已有卡片充值指定金额。 使用此接口向卡片充值。",{"id":2603,"title":2602,"titles":4078,"content":4079,"level":609},[],"将卡片可用余额提现到 Onerway 账户。 使用此接口将卡片可用余额提现到 Onerway 账户。",{"id":2607,"title":2606,"titles":4081,"content":4082,"level":609},[],"分页查询卡片操作记录，并支持可选筛选条件。 使用此接口按卡片 ID、幂等请求 ID、操作类型和时间范围查询卡片操作记录。",{"id":2611,"title":2610,"titles":4084,"content":4085,"level":609},[],"查询卡片基础状态信息。 使用此接口查询卡片基础状态信息。",{"id":2615,"title":2614,"titles":4087,"content":4088,"level":609},[],"查询卡片当前余额。 使用此接口查询卡片当前余额。",{"id":2619,"title":2618,"titles":4090,"content":4091,"level":609},[],"从安全的服务端环境查询卡号、CVV 和有效期等敏感信息。 使用此接口从安全的服务端环境查询卡号、CVV 和有效期等敏感信息。",{"id":2623,"title":2622,"titles":4093,"content":4094,"level":609},[],"在商户账户下创建持卡人。 使用此接口在开卡前创建持卡人。",{"id":2627,"title":2626,"titles":4096,"content":4097,"level":609},[],"更新已有持卡人的资料信息。 使用此接口更新已有持卡人的资料信息。",{"id":2631,"title":2630,"titles":4099,"content":4100,"level":609},[],"分页查询商户账户下的持卡人，并支持可选筛选条件。 使用此接口查询商户账户下的持卡人。",{"id":2635,"title":2634,"titles":4102,"content":4103,"level":609},[],"查询发卡持卡人地址支持的地区列表。 使用此接口查询支持的地区。",{"id":2639,"title":2638,"titles":4105,"content":4106,"level":609},[],"查询指定地区下的城市或行政区划。 使用此接口查询指定地区下的城市或行政区划。",{"id":2643,"title":2642,"titles":4108,"content":4109,"level":609},[],"查询支持的手机国际区号。 使用此接口查询支持的手机国际区号。",{"id":2646,"title":2300,"titles":4111,"content":4112,"level":609},[],"分页查询卡交易记录，并支持可选筛选条件。 使用此接口按交易类型、交易状态、卡片 ID 和时间范围查询卡交易记录。",{"id":2650,"title":2649,"titles":4114,"content":4115,"level":609},[],"按卡片、交易订单号和时间范围分页查询 3DS 发送记录。 使用此接口查询发卡交易的 3DS 发送记录。",{"id":2654,"title":2653,"titles":4117,"content":4118,"level":609},[],"查询商户可用的卡产品及相关配置。 使用此接口查询创建卡片时可选择的卡产品。",{"id":2658,"title":2657,"titles":4120,"content":4121,"level":609},[],"了解发卡事件推送的报文头、报文结构、商户响应要求和 HMAC-SHA256 签名验签方式。 接入发卡事件推送前，请先阅读本页公共规则。Onerway 会将卡操作、卡交易和 3DS 事件推送到商户配置的回调地址。",{"id":4123,"title":4124,"titles":4125,"content":4126,"level":615},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#报文头","报文头",[2657],"Header类型必填说明Content-TypeString是固定为 application\u002Fjson;charset=UTF-8。x-timestampString是Unix 秒级时间戳。x-signatureString是使用 webhook_secret、x-timestamp + \".\" + raw_body 生成 HMAC-SHA256 签名，参考验签与签名。",{"id":4128,"title":4129,"titles":4130,"content":4131,"level":615},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#报文结构","报文结构",[2657],"字段类型必填说明request_idString是唯一事件标识，用于幂等去重。event_typeString是事件类型。发卡当前推送 issuing.cardOperateEvent、issuing.cardTransactionEvent 和 issuing.card3dsEvent。created_atString是事件创建时间，ISO 8601 格式。versionString否创建 Webhook 订阅时选择的 API 版本；未指定时默认为 1.0。dataObject是业务数据，结构随 event_type 变化。",{"id":4133,"title":4134,"titles":4135,"content":4136,"level":615},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#商户响应要求","商户响应要求",[2657],"商户回调接口必须返回 JSON 响应。Onerway 根据该响应判断推送是否成功。 字段类型说明respCodeString返回 20000 表示确认收到。respMsgString响应信息。 如果回调响应码不是 20000，Onerway 会每 15 秒重试一次，最多重试 10 次。",{"id":4138,"title":4139,"titles":4140,"content":4141,"level":615},"\u002Fzh\u002Fissuing\u002Fapi-reference\u002Fwebhook-description#验签与签名","验签与签名",[2657],"Onerway 会对卡操作、卡交易和 3DS 等异步通知进行签名。商户处理事件前应先完成验签。 签名原文按以下方式拼接： x-timestamp + \".\" + raw_body 使用 HMAC-SHA256 生成期望签名，并与 x-signature 进行大小写不敏感比较。 import javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.util.Base64;\nimport java.util.HexFormat;\n\npublic final class HmacSHA256Util {\n private HmacSHA256Util() {\n }\n\n public static String signHmacSHA256(String webhook_secret, String content) throws Exception {\n byte[] key = Base64.getDecoder().decode(webhook_secret);\n Mac mac = Mac.getInstance(\"HmacSHA256\");\n mac.init(new SecretKeySpec(key, \"HmacSHA256\"));\n return HexFormat.of().formatHex(mac.doFinal(content.getBytes(StandardCharsets.UTF_8)));\n }\n\n public static boolean verifyHmacSHA256(String webhook_secret, String content, String signed) throws Exception {\n String expected = signHmacSHA256(webhook_secret, content);\n return MessageDigest.isEqual(\n expected.toLowerCase().getBytes(StandardCharsets.UTF_8),\n signed.toLowerCase().getBytes(StandardCharsets.UTF_8)\n );\n }\n}\nimport base64\nimport hashlib\nimport hmac\n\ndef sign_hmac_sha256(webhook_secret: str, content: str) -> str:\n key = base64.b64decode(webhook_secret)\n return hmac.new(key, content.encode(\"utf-8\"), hashlib.sha256).hexdigest()\n\ndef verify_hmac_sha256(webhook_secret: str, content: str, signed: str) -> bool:\n expected = sign_hmac_sha256(webhook_secret, content)\n return hmac.compare_digest(expected.lower(), signed.lower())\n\u003C?php\n\nfinal class HmacSHA256Util\n{\n public static function signHmacSHA256(string $webhook_secret, string $content): string\n {\n $key = base64_decode($webhook_secret, true);\n if ($key === false) {\n throw new InvalidArgumentException('Invalid webhook secret.');\n }\n\n return hash_hmac('sha256', $content, $key);\n }\n\n public static function verifyHmacSHA256(string $webhook_secret, string $content, string $signed): bool\n {\n $expected = self::signHmacSHA256($webhook_secret, $content);\n return hash_equals(strtolower($expected), strtolower($signed));\n }\n} html pre.shiki code .sEYeR, html code.shiki .sEYeR{--shiki-light:#F76D47;--shiki-default:#A0111F;--shiki-dark:#F78C6C}html pre.shiki code .syUt5, html code.shiki .syUt5{--shiki-light:#9C3EDA;--shiki-default:#0E1116;--shiki-dark:#C792EA}html pre.shiki code .swq3L, html code.shiki .swq3L{--shiki-light:#39ADB5;--shiki-default:#0E1116;--shiki-dark:#89DDFF}html pre.shiki code .sL0pc, html code.shiki .sL0pc{--shiki-light:#9C3EDA;--shiki-default:#A0111F;--shiki-dark:#C792EA}html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .sS82C, html code.shiki .sS82C{--shiki-light:#6182B8;--shiki-default:#622CBC;--shiki-dark:#82AAFF}html pre.shiki code .sMOQ8, html code.shiki .sMOQ8{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#702C00;--shiki-default-font-style:inherit;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbWJf, html code.shiki .sbWJf{--shiki-light:#39ADB5;--shiki-default:#702C00;--shiki-dark:#89DDFF}html pre.shiki code .s3Bzk, html code.shiki .s3Bzk{--shiki-light:#90A4AE;--shiki-default:#0E1116;--shiki-dark:#BABED8}html pre.shiki code .s9uKf, html code.shiki .s9uKf{--shiki-light:#39ADB5;--shiki-default:#A0111F;--shiki-dark:#89DDFF}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sap6S, html code.shiki .sap6S{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#A0111F;--shiki-default-font-style:inherit;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .szXr-, html code.shiki .szXr-{--shiki-light:#90A4AE;--shiki-default:#023B95;--shiki-dark:#BABED8}html pre.shiki code .ssWmh, html code.shiki .ssWmh{--shiki-light:#6182B8;--shiki-default:#023B95;--shiki-dark:#82AAFF}html pre.shiki code .s70yF, html code.shiki .s70yF{--shiki-light:#39ADB5;--shiki-default:#023B95;--shiki-dark:#89DDFF}html pre.shiki code .sixsN, html code.shiki .sixsN{--shiki-light:#E2931D;--shiki-default:#023B95;--shiki-dark:#FFCB6B}",{"id":2667,"title":2666,"titles":4143,"content":4144,"level":609},[],"接收开卡、冻结、解冻、充值、注销和余额退回等卡操作状态变化通知。 使用此 webhook 接收卡操作状态变化。",{"id":2671,"title":2670,"titles":4146,"content":4147,"level":609},[],"接收授权、撤销、结算、退款和验证等卡交易事件通知。 使用此 webhook 接收卡交易事件。",{"id":2675,"title":2674,"titles":4149,"content":4150,"level":609},[],"接收发卡交易的 3DS 一次性验证码事件通知。 使用此 webhook 接收 3DS 一次性验证码事件。",{"id":2683,"title":2455,"titles":4152,"content":4153,"level":609},[],"账户余额、账户流水、账户账单与 Global Account（全球收付账户）管理服务。 Onerway Account 面向需要管理账户资金、查询余额变动、导出账单以及使用 Global Account（全球收付账户）能力的商户。你可以通过账户服务 API 查询多币种余额、追踪账户流水、导出每日账单，并在已开通权限后创建和查询 Global Account。 新接入账户余额、账户流水和账户账单接口时，请优先使用当前账户服务接口。页面左侧 API Reference 已按“账户余额”“账户交易”“账户账单”和 Global Account（全球收付账户）相关分组展示，废弃接口不会作为当前接口入口展示。",{"id":4155,"title":4156,"titles":4157,"content":4158,"level":615},"\u002Fzh\u002Faccount\u002Fget-started#能力范围","能力范围",[2455],"能力适用场景推荐入口账户余额查询账户各币种余额汇总，或读取指定币种余额明细。查询账户余额总览账户交易查询账户余额变动流水，或按交易单号反查关联流水。查询账户流水账户账单按日期导出账户账单 CSV，用于财务核对。导出每日账户账单Global Account（全球收付账户）创建 Global Account，查询开户资料、账户状态和通知 URL。创建 Global Account响应码根据账户服务响应码定位原因并决定排查动作。响应码",{"id":4160,"title":4161,"titles":4162,"content":4163,"level":615},"\u002Fzh\u002Faccount\u002Fget-started#接入路径","接入路径",[2455],"完成接入准备先准备账户服务请求域名、apikey、x-timestamp、出口 IP 白名单和接口权限。账户服务 Base URL 当前为：环境Base URLSandboxhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-serverProductionhttps:\u002F\u002Fapi.onerway.com\u002Faccount-server接入准备 页面包含完整请求 Header、示例 apikey、10分钟时间戳窗口和接口地址清单。查询账户余额接入完成后，通常先调用余额接口验证账户权限和币种数据。查询账户余额总览：适合首页看板、资金概览和多币种汇总。查询账户余额：适合在支付、打款或对账前检查指定币种余额。查询账户流水账户流水用于定位余额变化来源，也可以把账户资金变动与业务订单、打款或资金转出记录关联起来。查询账户流水：按币种、时间范围和分页查询流水。按交易单号查询账户流水：当你已经知道交易单号时，用于反查关联的账户流水。导出账户账单财务对账或归档时，使用 导出每日账户账单 下载指定日期的 CSV 文件。建议按自然日归档，并保留请求参数与返回文件的对应关系，方便后续追溯。使用 Global Account如果需要账户开通、收款或资金转出场景，请先确认 Global Account 能力已开通，再调用：创建 Global Account查询 Global Account 详情",{"id":4165,"title":4166,"titles":4167,"content":4168,"level":615},"\u002Fzh\u002Faccount\u002Fget-started#接口字段差异","接口字段差异",[2455],"当前账户余额、账户流水和账户账单接口使用新的账户服务响应结构： 项目当前账户服务接口请求鉴权apikey Header防重放 Headerx-timestamp成功响应码respCode = 20000响应信息字段respMsg错误对象error幂等字段requestId，10分钟内用于安全重试 Global Account 接口仍以当前接口页面展示的字段为准。调用时请不要混用不同接口的响应信封、状态码或必填字段。",{"id":4170,"title":4171,"titles":4172,"content":4173,"level":615},"\u002Fzh\u002Faccount\u002Fget-started#快速入口","快速入口",[2455],"接入准备 - 准备账户服务 Base URL、apikey、x-timestamp 和出口 IP 白名单查询账户余额总览 - 查询多币种账户余额汇总查询账户流水 - 查询账户流水和余额变动记录导出每日账户账单 - 导出指定日期的账户账单 CSV创建 Global Account - 创建 Global Account响应码 - 处理账户服务响应码和排查动作",{"id":2688,"title":2145,"titles":4175,"content":4176,"level":609},[],"配置账户服务请求域名、apikey、x-timestamp 和出口 IP 白名单，开始调用账户余额、账户流水、账户账单与 Global Account 接口。 账户服务 API 使用独立请求域名和特定环境的 apikey 请求 Header。开始调用账户余额、账户流水、账户账单或 Global Account 接口前，请先确认目标环境、接口访问权限、apikey、x-timestamp 和出口 IP 白名单已经准备完成。",{"id":4178,"title":2743,"titles":4179,"content":4180,"level":615},"\u002Fzh\u002Faccount\u002Fget-started\u002Fsetup#接入步骤",[2145],"确认接口权限账户服务接口为受限接口，需要 Onerway 为商户开通对应能力后才能访问。调用账户余额、账户流水和账户账单接口前，请确认账户服务 API 权限已开通。调用 Global Account 接口前，请确认 Global Account 开户、收款或资金转出能力已开通。如果平台商户需要代子商户查询，请确认父子商户关系和 onBehalfOf 使用权限已配置。选择请求域名请使用与 apikey 所属环境一致的账户服务请求域名。环境Base URLProductionhttps:\u002F\u002Fapi.onerway.com\u002Faccount-serverSandboxhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server沙盒与生产环境的凭据相互独立。接口路径以 \u002Fapi\u002Fv2\u002F... 或当前 Global Account 页面展示的 \u002Fapi\u002Fv1\u002F... 开头，Base URL、接口路径和 apikey 必须来自同一环境。保存 apikey账户服务通过 apikey 请求 Header 识别调用方权限。Header必填说明apikey是Onerway 分配的账户服务访问密钥。请将 apikey 保存在服务端。不要把它暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。设置 x-timestamp账户余额、账户流水和账户账单接口需要同时提供 apikey 和 x-timestamp。网关使用 x-timestamp 判断请求是否在有效时间窗口内，降低请求被重放的风险。Header必填说明x-timestamp是请求时间戳；支持 10 位秒级或 13 位毫秒级，必须与服务端时间偏差在 10分钟以内。Content-Type是（POST）application\u002Fjson。提供出口 IP调用账户服务前，请向 Onerway 提供稳定的服务端出口 IP，用于配置账户服务访问白名单。仅提交稳定的服务端出口 IP。如果沙盒与生产环境使用不同出口 IP，请分别提供。如果出口 IP 发生变更，请在切换流量前更新白名单。发起服务端请求环境、apikey、x-timestamp 与 IP 白名单就绪后，从服务端调用接口，并在请求 Header 中传入对应字段。curl https:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002Fquery \\\n -H 'Content-Type: application\u002Fjson' \\\n -H 'apikey: replace_with_account_service_apikey' \\\n -H 'x-timestamp: 1776931200' \\\n -d '{\n \"requestId\": \"REQ-BAL-OV-20260423-0001\",\n \"displayCurrency\": \"USD\"\n }'",{"id":4182,"title":4183,"titles":4184,"content":4185,"level":615},"\u002Fzh\u002Faccount\u002Fget-started\u002Fsetup#接口地址","接口地址",[2145],"当前对外展示的账户服务接口地址如下。请以当前环境的 Base URL 拼接接口路径发起请求。 类别接口MethodPath账户余额查询账户余额总览POST\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002Fquery账户余额查询账户余额POST\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Fquery账户交易查询账户流水POST\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fquery账户交易按交易单号查询账户流水POST\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fservice\u002Fquery账户账单导出每日账户账单POST\u002Fapi\u002Fv2\u002Faccount\u002Fstatement\u002Fdaily\u002FexportGlobal Account（全球收付账户）创建 Global AccountPOST\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FcreateGlobal Account（全球收付账户）查询 Global Account 详情POST\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FgetDetail 完整 Sandbox 示例： https:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Foverview\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fbalance\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Ftransactions\u002Fservice\u002Fqueryhttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv2\u002Faccount\u002Fstatement\u002Fdaily\u002Fexporthttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002Fcreatehttps:\u002F\u002Fsandbox-api.onerway.com\u002Faccount-server\u002Fapi\u002Fv1\u002Faccount\u002Fglobal\u002FgetDetail",{"id":4187,"title":4188,"titles":4189,"content":4190,"level":615},"\u002Fzh\u002Faccount\u002Fget-started\u002Fsetup#幂等","幂等",[2145],"账户余额、账户流水和账户账单接口支持幂等控制。在 10分钟内复用同一个 requestId 可以安全重试请求；命中重复时返回 10006 DUPLICATE_REQUEST 错误，错误类型为 idempotency_error。",{"id":4192,"title":2748,"titles":4193,"content":4194,"level":615},"\u002Fzh\u002Faccount\u002Fget-started\u002Fsetup#下一步",[2145],"查询账户余额总览 - 查询多币种账户余额汇总查询账户余额 - 查询指定币种的账户余额查询账户流水 - 查询账户流水和余额变动记录按交易单号查询账户流水 - 按交易单号查询关联账户流水导出每日账户账单 - 导出指定日期的账户账单 CSV创建 Global Account - 为收单收款与资金转出场景创建 Global Account查询 Global Account 详情 - 查询 Global Account 开户资料与状态响应码 - 处理账户服务响应码和排查动作 html pre.shiki code .s8_pB, html code.shiki .s8_pB{--shiki-light:#E2931D;--shiki-default:#702C00;--shiki-dark:#FFCB6B}html pre.shiki code .s12Wk, html code.shiki .s12Wk{--shiki-light:#91B859;--shiki-default:#032563;--shiki-dark:#C3E88D}html pre.shiki code .sqdQu, html code.shiki .sqdQu{--shiki-light:#90A4AE;--shiki-default:#A0111F;--shiki-dark:#BABED8}html pre.shiki code .s1-4R, html code.shiki .s1-4R{--shiki-light:#91B859;--shiki-default:#023B95;--shiki-dark:#C3E88D}html pre.shiki code .syBtB, html code.shiki .syBtB{--shiki-light:#39ADB5;--shiki-default:#032563;--shiki-dark:#89DDFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"id":2700,"title":2699,"titles":4196,"content":4197,"level":609},[],"创建用于收单收款与资金转出场景的 Global Account（全球收付账户）。 该接口用于为客户初始化 Global Account，并配置开户银行国家或地区以及支持收款的币种。",{"id":2704,"title":2703,"titles":4199,"content":4200,"level":609},[],"通过 Global Account ID 或账号查询 Global Account 详情。 该接口用于读取 Global Account 详情、生命周期状态、支持的业务类型和支持收款的币种。",{"id":2708,"title":2707,"titles":4202,"content":4203,"level":609},[],"查询调用方商户账户或指定子商户账户的余额变动记录。 该接口用于分页查询账户余额变动流水，即收单、资金转出等业务活动在 Onerway Account 中产生的余额增减记录。默认查询 apikey 所属商户的账户流水；平台商户代子商户查询时，通过 onBehalfOf 指定子商户号，返回该子商户账户下符合币种、余额类型、业务类型和余额更新时间范围的流水记录。",{"id":2712,"title":2711,"titles":4205,"content":4206,"level":609},[],"按一个或多个交易单号查询关联的账户余额变动记录。 已知交易单号时，可使用该接口查询关联的账户流水记录。",{"id":2716,"title":2715,"titles":4208,"content":4209,"level":609},[],"查询指定单一币种的账户余额明细。 该接口用于查询指定币种的账户余额结构，包括 Payment、Funding、待结算、冻结、风险保证金和总余额。",{"id":2720,"title":2719,"titles":4211,"content":4212,"level":609},[],"查询多币种账户余额汇总和可选的展示币种总金额。 该接口用于查询各币种账户余额汇总，并在汇率可用时返回用于总览展示的展示币种总金额。",{"id":2724,"title":2723,"titles":4214,"content":4215,"level":609},[],"导出指定日期的每日账户账单 CSV。 该接口用于按指定日期、币种和业务类型导出每日账户账单 CSV。",{"id":2727,"title":2441,"titles":4217,"content":4218,"level":609},[],"对照账户服务响应信封、成功响应码和建议处理动作。 当账户服务响应返回非成功响应码时，可用本页定位错误类型、理解可能原因，并决定下一步排查动作。请始终以当前接口页面展示的响应字段名为准。 当前账户余额、账户流水和账户账单接口不使用 code \u002F message 作为主响应信封。它们使用 respCode \u002F respMsg，其中 20000 表示请求已成功处理。",{"id":4220,"title":4221,"titles":4222,"content":4223,"level":615},"\u002Fzh\u002Faccount\u002Fapi-reference\u002Fresponse-codes#当前账户服务接口","当前账户服务接口",[2441],"账户余额、账户流水接口使用 JSON 响应信封：respCode \u002F respMsg \u002F data \u002F error。 账户账单导出接口成功时返回 CSV 文件流；只有在 CSV 响应尚未提交且请求失败时，才返回 JSON 错误响应，其中包含 respCode、respMsg 和 error。 respCode默认 respMsg错误类型中文说明建议处理20000Success-请求已成功处理。继续读取当前接口的 data 字段、账户余额明细、账户流水记录或分页字段。账户账单导出成功时读取 CSV 文件流。10001Invalid request parameterinvalid_request_error请求参数缺失、格式错误、超出允许范围，或传入了不支持的枚举值。对照接口字段表检查必填字段、币种代码、枚举值、时间戳要求、查询时间范围和请求示例。10006DUPLICATE_REQUESTidempotency_errorrequestId 在幂等窗口内重复使用。先确认原请求的处理结果；只有发起全新操作时才生成新的 requestId。 error 对象用于承载标准化错误信息： 字段说明code对外业务错误码，通常与 respCode 对齐。declineCode兼容字段，当前账户服务接口中通常与 code 保持一致。message可读错误信息。type标准化错误类型，例如 invalid_request_error、idempotency_error 或 api_error。param触发错误的请求参数名；仅在适用时返回。requestId调用方请求 ID，与请求 body 中的 requestId 保持一致。",{"id":4225,"title":4226,"titles":4227,"content":4228,"level":615},"\u002Fzh\u002Faccount\u002Fapi-reference\u002Fresponse-codes#global-account-接口","Global Account 接口",[2441],"Global Account 创建与详情查询接口使用 success \u002F respCode \u002F respMsg 响应信封，成功响应码为 20000。 respCodeConstant默认 respMsg中文说明建议处理20000SUCCESS_CODESuccess请求已成功处理。继续读取当前接口的 data 字段和 Global Account 状态值。10001INVALID_PARAMETERInvalid request parameter请求参数缺失、格式错误、超出允许范围，或传入了不支持的枚举值。对照接口字段表检查必填字段、枚举值、查询约束和请求示例；详情查询时 globalAccountId 必须为数字格式，且 globalAccountId 与 globalAccountNo 至少传入一个。10002INVALID_TIME_RANGEInvalid query time range查询时间范围无效，或超过当前请求支持的范围。按接口查询约束调整开始时间和结束时间后重试。10003UNAUTHORIZED_ACCESSAccess denied调用方无权访问请求的账户服务资源或能力。检查 apikey、环境、商户账户和 IP 白名单是否与目标资源匹配；如应已开通权限，请联系 Onerway 支持。10004RESOURCE_NOT_FOUNDResource not found请求的 Global Account 或关联业务资源不存在。核对 globalAccountId、globalAccountNo、环境和商户归属关系；不要用同一标识盲目重试。10005REQUEST_FAILEDRequest failed账户服务未能完成本次请求。结合响应 respMsg 和请求上下文排查；仅在操作可安全重复或已做幂等保护时重试。10006DUPLICATE_REQUESTDuplicate request请求与之前的请求重复，或使用了已经处理过的幂等标识。先查询既有处理结果；只有发起全新操作时才使用新的 requestId。10007INIT_GLOBAL_ACCOUNT_FAILEDInit global account failedGlobal Account 初始化失败。检查 customerId、onBehalfOf、支持币种、开户银行国家或地区以及账户能力配置；如果请求数据无误，请联系 Onerway 支持。10008GLOBAL_ACCOUNT_CUSTOMER_INVALIDInvalid customer id for global account客户标识不能用于当前 Global Account 操作。确认 customerId 属于当前商户账户；平台代子客户调用时，确认 customerId 与 onBehalfOf 一致且存在有效父子关系。10009GLOBAL_ACCOUNT_CALLER_NOT_AUTHORIZEDCaller identity does not match customer调用方身份与 Global Account 资源关联的客户不匹配。确认 apikey、商户账户、customerId、onBehalfOf 和 Global Account 标识属于同一授权关系。",[2139,2146,2150,2154,2158,2162,2171,2177,2184,2191,2197,2200,2204,2208,2215,2219,2223,2227,2231,2245,2249,2253,2257,2261,2265,2269,2273,2277,2281,2285,2289,2293,2297,2301,2305,2309,2313,2317,2321,2325,2329,2333,2337,2341,2345,2349,2353,2357,2361,2365,2369,2373,2377,2381,2390,2394,2398,2402,2406,2410,2414,2418,2422,2426,2430,2434,2438,2442,2451,2457,2461,2465,2469,2483,2487,2491,2495,2499,2503,3872,2507,2511,2515,2519,2523,2527,2531,2535,2539,2543,2547,2551,2473,2560,2564,2572,2577,2580,2591,2595,2599,2603,2607,2611,2615,2619,2623,2627,2631,2635,2639,2643,2646,2650,2654,2658,2667,2671,2675,2683,2688,2700,2704,2708,2712,2716,2720,2724,2727],{"page":4231,"surround":4249,"requestedLocale":4250,"contentLocale":4250,"isFallback":111,"fallbackNotice":8},{"id":4232,"title":4233,"badge":8,"body":4234,"deprecated":8,"description":4242,"extension":4243,"links":8,"meta":4244,"navigation":111,"path":4245,"seo":4246,"stem":4247,"toc":8,"__hash__":4248},"site_en\u002Findex.md","Build every way money moves.",{"type":4235,"value":4236,"toc":4240},"minimark",[4237],[4238,4239],"home-landing",{},{"title":874,"searchDepth":615,"depth":667,"links":4241},[],"Accept payments, send cross-border transfers, issue virtual cards, and manage Global Account resources—from the first integration step to the exact API contract.","md",{},"\u002F",{"title":4233,"description":4242},"index","mgvynS19uNdDPU85IPlbFKF7i5erKsZgTk_pvyMdzs0",[8,8],"en",1791439486766]