Local payment 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).

Query available payment methods

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.

Choose an integration method

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.

Direct API integration

Method-specific parameters

Apart from lpmsType, lpmsInfo has five child fields, each conditionally required depending on the method you selected:

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.

Delayed settlement and waiting states

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.

Local payment method subscriptions

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:

1. 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.
2. 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.

Extra requirements of some regional methods

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.

Go-live checklist

• 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.