Pay By Bank Integration

Overview

Pay By Bank is a UK-focused local bank payment method. This guide follows the same structure as other local payment method pages and explains the full technical integration flow for accepting Pay By Bank through the Onerway payment gateway, from prerequisites and key parameters to redirect handling and final webhook confirmation.

Technical Characteristics:

• Payment flow: Redirect-based
• Order currency: GBP (British Pound)
• Supported country: GB (United Kingdom)
• Transaction type: One-time payment
• Integration method: REST API

Supported Features:

• One-time payments
• Redirect to bank selection page
• Bank app / online banking authorization
• Asynchronous webhook result notification

Not Supported:

• Installment payments
• Subscription payments

Payment Result Confirmation Requirements

The browser return in Pay By Bank only indicates that the customer has returned from the bank authorization journey. It must not be treated as final payment confirmation:

• Synchronous response: Usually returns status=R, paymentStatus=R, and actionType=RedirectURL
• Frontend responsibility: Redirect immediately when redirectUrl is returned
• Return page: Recommended to show a Processing / Pending state while waiting
• Final result: Must be determined by webhook; if webhook is delayed, use Transaction Query as fallback

Technical Prerequisites

Ensure your system meets these requirements before starting integration:

Infrastructure Requirements

• HTTPS-enabled endpoints (TLS 1.2 or higher)
• Public-accessible webhook endpoint for receiving notifications
• Ability to generate and verify SHA256 signatures
• UTF-8 character encoding support

Integration Requirements

• Onerway merchant account with Pay By Bank enabled
• API credentials (merchant number and secret key)
• Sandbox environment access for testing
• Support for HTTP redirects (302/303 status codes)

Optional Enhancements

• Processing-state UI on the return page
• Mobile browser and bank-app handoff testing
• Transaction Query fallback logic

Technical Configuration

Step 1: API Credentials Setup

Obtain the following credentials from Onerway:

• merchantNo: Your unique merchant identifier
• secretKey: Used for request/response signature generation
• API endpoint URLs (sandbox and production)

Step 2: Webhook Configuration

Configure your webhook endpoint to receive payment notifications:

1. Endpoint URL: Must be publicly accessible via HTTPS
2. Supported methods: POST
3. Content-Type: application/json
4. Response requirement: Return HTTP 200 with JSON body containing transactionId

Example webhook configuration:

Webhook URL: https://your-domain.com/api/webhooks/onerway
Method: POST
Timeout: 30 seconds
Retry: 3 attempts (30-minute intervals)

Step 3: Return URL Configuration

Set up URLs for customer redirects after payment:

• returnUrl: Where the customer returns after completing, cancelling, or leaving the bank authorization flow
• It is recommended to append merchantTxnId to returnUrl so the merchant can actively trigger Transaction Query after the customer returns
• The Pay By Bank returnUrl must be registered with Onerway for whitelist approval before going live
• Query parameters may include: transactionId, status, merchantTxnId

Payment Status Polling

After receiving the redirect to returnUrl, merchants can actively query Transaction Query or other query APIs to confirm the final result, instead of relying only on browser return parameters.

Integration Flow

The Pay By Bank integration follows a redirect-based bank-authorization flow:

Payment Flow Diagram

Flow Steps Explained

Phase 1: Payment Initiation

1. Customer selects Pay By Bank as payment method
2. Merchant sends payment request to Onerway API
3. Onerway creates the payment session
4. Onerway returns the redirect URL

Phase 2: Bank Authorization

5. Merchant redirects customer to the bank selection page
6. Customer selects their bank
7. The page opens the bank app or redirects to online banking
8. Customer confirms the payment in the bank flow
9. The bank authorization journey returns the customer to the merchant site or hosted result page

Phase 3: Payment Confirmation

10. The bank authorization journey sends the result back to Onerway
11. Onerway sends webhook to merchant
12. Merchant acknowledges webhook
13. Merchant displays result to customer

Important

• Always rely on webhook notifications for the final payment result
• The redirect back to your site may arrive before final confirmation
• The return page should show a processing state while waiting for webhook or query confirmation

Pay By Bank Special Requirements

Pay By Bank requires the following configuration and parameters:

lpmsInfo Configuration

Set the lpmsInfo parameter to identify Pay By Bank:

"lpmsInfo": "{\"lpmsType\":\"PAY_BY_BANK\"}"

Required Parameters

The following parameters are key for Pay By Bank:

billingInformation

Minimum required:

• country

Recommended minimum value:

"billingInformation": "{\"country\":\"GB\"}"

shippingInformation

Minimum required:

• country

Recommended minimum value:

"shippingInformation": "{\"country\":\"GB\"}"

lpmsInfo

Minimum required:

• lpmsType

Not required:

• bankName
• iban/iBan

For Pay By Bank, the merchant does not need to preselect the bank in the request. Bank selection happens later on the redirect page.

txnOrderMsg

Must include the following fields:

• returnUrl - Where the customer returns after completing or leaving authorization
• notifyUrl - Webhook endpoint for the final payment result
• products - Product data for order display and reconciliation

Recommended returnUrl shape:

https://merchant.example.com/payments/return?merchantTxnId=1774494196000

This lets the merchant trigger Transaction Query directly with merchantTxnId after the customer returns. The same returnUrl must also be pre-registered with Onerway for whitelisting.

View TxnOrderMsg for complete field definitions.

API Request Parameters

POST

Key Parameters

For Pay By Bank integration, you must set:

• productType: LPMS
• subProductType: DIRECT
• lpmsInfo: JSON string containing lpmsType set to PAY_BY_BANK
• orderCurrency: GBP

Standard Request Parameters

For complete standard LPMS parameters, please refer to Local Payment Methods.

Parameter	Type	Length	Required	Signed	Description
billingInformation	String	/	Yes	Yes	Transaction billing information in JSON string format. See TransactionAddress for complete structure.
lpmsInfo	String	/	Conditional	Yes	Local payment method information in JSON string format. See LpmsInfo for complete structure.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
merchantTxnOriginalId	String	128	No	Yes	Master transaction ID generated by merchant for grouping related transactions.
merchantTxnTime	String	/	No	Yes	Transaction timestamp when the merchant initiated the transaction.
merchantTxnTimeZone	String	64	No	Yes	Transaction timezone offset for the merchant transaction time.
metaData	String	2048	No	Yes	Merchant-defined custom data.
mpiInfo	String	/	Conditional	Yes	3DS verification result information in JSON string format. See MpiInfo for complete structure.
orderAmount	String	19	Yes	Yes	Transaction amount in the specified currency, formatted as a decimal string.
orderCurrency	String	8	Yes	Yes	Three-letter currency code according to ISO 4217 standard for the transaction amount.
osType	String	16	Conditional	Yes	Operating system type for mobile and app-based transactions. See OsTypeEnum for available options.
paymentMode	String	16	No	Yes	Payment mode indicating the platform or environment for the transaction. See PaymentModeEnum for all available options.
productType	String	16	Yes	Yes	Payment method category that determines which payment options are available to customers. See ProductTypeEnum for all available options.
risk3dsStrategy	String	16	Conditional	Yes	3DS risk control strategy for fraud prevention. See Risk3dsStrategyEnum for available options.
shippingInformation	String	/	Yes	Yes	Transaction shipping information in JSON string format. See TransactionAddress for complete structure.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
subProductType	String	16	Yes	Yes	Specific implementation method within the selected product type, defining how the payment is processed. See SubProductTypeEnum for all available options.
subscription	String	/	Conditional	Yes	Subscription configuration in JSON format including frequency, billing cycle, and subscription type (managed / self-managed).
txnOrderMsg	String	/	Yes	Yes	Transaction business information in JSON string format. See TxnOrderMsg for complete structure.
txnType	String	16	Yes	Yes	Transaction type that defines the payment operation to be performed. See TxnTypeEnum for all available options and detailed usage scenarios.

lpmsInfo Parameter Details

lpmsInfo is a JSON string for Pay By Bank configuration:

Parameter	Type	Required	Description
lpmsType	String	Yes	Fixed value PAY_BY_BANK
bankName	String	No	Not required for this method
iban/iBan	String	No	Not required for this method

Response

The API returns a JSON response with standard Onerway response fields. For Pay By Bank transactions, pay special attention to status, paymentStatus, actionType, and redirectUrl to determine the next required action.

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

The data object in the response contains detailed transaction information:

Name	Type	Description
transactionId	String	Transaction ID created by Onerway
paymentId	String	Payment intent ID
responseTime	String	Response timestamp Format: yyyy-MM-dd HH:mm:ss
txnTime	String	Transaction initiation time Format: yyyy-MM-dd HH:mm:ss
txnTimeZone	String	Transaction timezone Format: +/-HH:mm
orderAmount	String	Order amount
orderCurrency	String	Order currency Refer to ISO 4217 currency codes
txnAmount	String	Settlement amount
txnCurrency	String	Settlement currency Refer to ISO 4217 currency codes
status	String	Transaction status Refer to TxnStatusEnum
paymentStatus	String	Payment intent status Refer to PaymentStatusEnum
redirectUrl	String	Payment redirect URL
contractId	String	Subscription contract ID
tokenId	String	Payment token
eci	String	Electronic Commerce Indicator
periodValue	String	Installment periods
codeForm	String	Code form See CodeFormEnum
presentContext	String	Presentation context
actionType	String	Required action See ActionTypeEnum
subscriptionManageUrl	String	Subscription management URL
sign	String	Response signature Refer to the Signature documentation

Response Handling

Pay By Bank transactions typically return status=R, paymentStatus=R, and actionType=RedirectURL. You must redirect the customer to redirectUrl immediately and wait for final webhook confirmation on the return page.

API Usage Examples

Standard Payment Request

Request

{
  "billingInformation": "{\"country\":\"GB\"}", // Minimum billing information
  "lpmsInfo": "{\"lpmsType\":\"PAY_BY_BANK\"}", // Pay By Bank identifier
  "merchantNo": "<MERCHANT_NO>", // Merchant number from Onerway
  "merchantTxnId": "1774494196000", // Unique transaction ID
  "orderAmount": "10",
  "orderCurrency": "GBP", // British Pound
  "productType": "LPMS", // Local payment method
  "shippingInformation": "{\"country\":\"GB\"}", // Minimum shipping information
  "sign": "<SIGNATURE>", // Request signature
  "subProductType": "DIRECT", 
  "txnOrderMsg": "{\"returnUrl\":\"https://merchant.example.com/payments/return?merchantTxnId=1774494196000\",\"products\":\"[{\\\"price\\\":\\\"10.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"GBP\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"<APP_ID>\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"en-US\",\"notifyUrl\":\"https://merchant.example.com/webhook/payment\"}", // Recommended: include merchantTxnId in returnUrl and whitelist this URL with Onerway
  "txnType": "SALE"
}

Response - Redirect

{
  "respCode": "20000", // Success code
  "respMsg": "Success",
  "data": {
    "transactionId": "2037002425390727168", // Onerway transaction ID
    "paymentId": "2037002425365561344", // Payment intent ID
    "responseTime": "2026-03-26 11:03:21",
    "orderAmount": "10.00",
    "orderCurrency": "GBP",
    "status": "R", // Redirect required
    "paymentStatus": "R", // Payment intent in progress
    "redirectUrl": "https://payment-gateway.example.com/payments?payment_id=59af7f48-fa7a-4f1e-880f-a09d2f2e76d7&resource_token=<RESOURCE_TOKEN>&return_uri=https://sandbox-gw-dmz.onerway.com/front/return/0000000011", // Bank selection page URL
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", // Action type: Redirect
    "subscriptionManageUrl": null,
    "sign": "<RESPONSE_SIGNATURE>"
  }
}

Async Notification

{
  "channelRequestId": "0000000008",
  "merchantNo": "<MERCHANT_NO>",
  "merchantTxnId": "1774494196000",
  "notifyType": "TXN",
  "orderAmount": "10.00",
  "orderCurrency": "GBP",
  "paymentId": "2037002425365561344", // Payment intent ID
  "paymentMethod": "PAY_BY_BANK", // Payment method
  "paymentMethodDetails": "{\"card\":{\"checks\":null,\"holderName\":null,\"year\":null,\"month\":null,\"cardType\":null,\"productCategory\":null,\"issuer\":null,\"cardBinCountry\":null,\"authorizationCode\":null,\"cardNumber\":null}}",
  "paymentStatus": "S", // Payment intent success
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "responseTime": "2026-03-26 11:12:27",
  "sign": "<WEBHOOK_SIGNATURE>", // Verify signature
  "status": "S", // Transaction success
  "transactionId": "2037002425390727168", // Onerway transaction ID
  "txnTime": "2026-03-26 11:03:21",
  "txnTimeZone": "+08:00",
  "txnType": "SALE"
}

Technical Integration Checklist

Before deploying to production:

API Integration

• Payment request API implemented and tested
• Request signature generation working correctly
• Error response handling implemented
• Redirect flow implemented (handle status=R and actionType=RedirectURL)

Pay By Bank Special Requirements

• lpmsInfo uses {"lpmsType":"PAY_BY_BANK"}
• billingInformation includes at least country=GB
• shippingInformation includes at least country=GB
• Request does not incorrectly depend on bankName or iban/iBan
• txnOrderMsg includes returnUrl
• returnUrl includes merchantTxnId for active post-return querying
• returnUrl has been pre-registered with Onerway for whitelisting
• txnOrderMsg includes notifyUrl
• Return page supports Processing / Pending

Webhook Implementation

• Webhook endpoint publicly accessible via HTTPS
• Webhook signature verification implemented
• Idempotent webhook processing implemented
• Webhook acknowledgment returns HTTP 200 with transactionId
• Final webhook state persistence implemented

Security

• TLS 1.2 or higher enabled
• API credentials stored securely
• Signature verification tested
• No sensitive data logged in plain text

Testing Validation

• Successful payment scenario tested
• Failed payment scenario tested
• Customer cancellation or interrupted authorization scenario tested
• Webhook delivery tested
• Return-page processing state tested
• Mobile bank-app handoff tested

Monitoring & Operations

• API request/response logging implemented
• Error monitoring and alerting configured
• paymentId / transactionId status tracking implemented
• Transaction Query fallback logic implemented

Technical Support

For technical integration assistance, contact Onerway technical support with your merchantNo and specific technical questions.