# Local payment methods

> 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`).

## Query available payment methods

The methods Onerway supports are the values of the [`lpmsInfo.lpmsType` field](/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo-lpmsType); 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](/payments/online-payments/payment-methods/apple-pay) and [Google Pay](/payments/online-payments/payment-methods/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](/payments/api-reference/endpoints/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](/payments/get-started/currency-and-amount).

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

| Integration method | Display and selection | Key parameters |
| --- | --- | --- |
| [Checkout](/payments/online-payments/checkout) | The checkout page displays the methods available for the order and the customer chooses; it can also be locked to a single method | Submit `productType=ALL` to display every available method; add `lpmsInfo.lpmsType` to lock to a single method |
| [Web SDK](/payments/online-payments/sdk) | The SDK displays the available methods on your page and renders QR codes and other presented interfaces | `productType=ALL`; a local payment method is confirmed by your own button calling `confirmPayment()` |
| [Direct API](/payments/online-payments/api) | You build the method list and name the method when creating the transaction, and handle the customer action yourself | The local payment method scope value of the [`productType` field](/payments/api-reference/endpoints/direct-create-transaction#request-productType), `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.

## Direct API integration

<steps level="3">

### Create the transaction

Once the customer has chosen a method, call [Create direct transaction](/payments/api-reference/endpoints/direct-create-transaction) from your server with the local payment method scope value of the [`productType` field](/payments/api-reference/endpoints/direct-create-transaction#request-productType), `subProductType=DIRECT` (use `SUBSCRIBE` for subscriptions, see [Local payment method subscriptions](#local-payment-method-subscriptions)), `txnType=SALE`, and the [`lpmsInfo` field](/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo): `lpmsType` names the method and the remaining child fields are conditionally required per method, see [Method-specific parameters](#method-specific-parameters). `productType=ALL` is an aggregated Checkout display concept and is not supported by the Direct API.

### Handle the customer action

A response of `status=R` means the customer still has one action to take, and the [`actionType` field](/payments/api-reference/endpoints/direct-create-transaction#response-data-actionType) says which. Handle all three values:

| `actionType` | What to do |
| --- | --- |
| `RedirectURL` | Redirect the customer to the [`redirectUrl` field](/payments/api-reference/endpoints/direct-create-transaction#response-data-redirectUrl). What the customer sees is determined by the method: a bank selection page, the bank app, or an online banking authorization page |
| `QrCode` | Display the QR code or barcode carried by the [`codeForm` field](/payments/api-reference/endpoints/direct-create-transaction#response-data-codeForm) on your own page; when that field carries an `expireTime`, handle expiry accordingly |
| `ShowContext` | Display the contextual content carried by the [`presentContext` field](/payments/api-reference/endpoints/direct-create-transaction#response-data-presentContext) on your own page |

For methods that open a native app, verify that opening the app and returning to your site both work in mobile browsers.

### Handle the synchronous return

With 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](/payments/api-reference/endpoints/query-transactions).

### Confirm the final result

The final state comes from the [payment result webhook](/payments/api-reference/webhooks/payment-result), whose [`paymentMethod` field](/payments/api-reference/webhooks/payment-result#webhook-paymentMethod) returns the method that was actually charged. Signature verification, acknowledgement and retries, idempotent deduplication, and query-based compensation are covered in [Webhooks](/payments/get-started/webhooks).

</steps>

## Method-specific parameters

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

| Child field | What it collects |
| --- | --- |
| `bankName` | The bank the customer chose; needed by `EFT` and `Przelewy24`; the selectable banks are listed under the `lpmsInfo` field reference below |
| `walletAccountId` | Wallet or local account identifier |
| `walletAccountName` | Wallet or local account name |
| `iBan` | Account number for regional transfers that identify the bank by IBAN |
| `prepaidNumber` | Prepaid card or voucher number for Japan prepaid methods |

The full required conditions, and the bank values for `bankName`, are on the [`lpmsInfo` field](/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo).

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](/payments/api-reference/endpoints/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](/payments/api-reference/endpoints/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](/payments/online-payments/scenarios/subscriptions).

`frequencyType` accepts only `D`, but that does not limit you to daily billing: the [`subscription.frequencyPoint` field](/payments/api-reference/endpoints/direct-create-transaction#request-subscription-frequencyPoint) 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](/payments/api-reference/endpoints/direct-create-transaction#request-subscription) (`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](/payments/api-reference/webhooks/payment-method-result) (`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](/payments/api-reference/webhooks/subscription-payment) (`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](/payments/api-reference/endpoints/direct-create-transaction#request-lpmsInfo-lpmsType). 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](/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-products-type), and an HTTPS product image URL in JPG, PNG, or WebP format in the [`txnOrderMsg.products[].productAvatarUrl` field](/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-products-productAvatarUrl).
- The [`txnOrderMsg.customerPlatform` field](/payments/api-reference/endpoints/direct-create-transaction#request-txnOrderMsg-customerPlatform) 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](/payments/api-reference/endpoints/upload-logistics-info) 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](/payments/api-reference/endpoints/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](/payments/get-started/webhooks#go-live-checklist) 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.