Google Pay PAN_ONLY Check and Custom CVV Collection

Custom Integration Approach

This documentation is for merchants who want to collect CVV themselves, providing a smoother user experience than the standard redirect approach.

If you prefer the simpler standard approach, please refer to Google Pay Integration.

Overview

This document explains how to use the PAN_ONLY Check API to determine if CVV is needed, and pass CVV through the cardInfo.cvv field yourself, avoiding Onerway's redirect page.

Key differences from standard integration:

Feature	Standard Integration (Onerway Redirect)	Custom Approach (Self-Collected CVV)
CVV Collection Method	Onerway-provided redirect page	Merchant-designed UI
User Experience	Requires page redirect	No redirect, smoother flow
Implementation Complexity	Simple	More complex
Technical Requirements	Basic	Higher
CVV Security Handling	Onerway handles	Merchant responsible (no storage, no logging)

For complete Google Pay standard integration flow, see: Google Pay Integration

Integration Prerequisites

Before implementing custom CVV collection, ensure you have:

A valid Google Pay merchant account with token processing enabled
Google Pay basic integration implemented on your website or app
Access to the Onerway payment gateway API
Technical capability to design and implement custom CVV input UI
Understanding of CVV security handling requirements

CVV Security Handling Requirements

While PCI DSS certification is not required, you must follow these CVV security handling guidelines:

No Storage: CVV must only be processed in memory, never stored in database or files
No Logging: Never log CVV to log files
HTTPS Transport: All requests containing CVV must use HTTPS encryption
Immediate Cleanup: Clear CVV from memory immediately after payment completion

API Request Parameters

POST

Note

All JSON fields must be stringified before submission
Nested objects must be serialized to JSON string format
JSON fields must not contain unescaped special characters
Arrays in JSON should be properly formatted
Example of JSON string field:

json

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
appId	String	20	Yes	Yes	Merchant application ID assigned by Onerway for website identification.
gatewayName	String	64	Yes	Yes	Payment gateway identifier for Google Pay token processing.
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.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
tokenInfoJson	String	/	Yes	Yes	Serialized tokenInfo structure as JSON string for checking Google Pay PAN_ONLY mode. See TokenInfo for structure details.

Response

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

data

Name	Type	Description
└cardNum	String	Masked card number extracted from Google Pay token.
└checkResult	Boolean	PAN_ONLY mode check result. `false` means CVV collection is required, `true` means no CVV needed.

Integration Flow Overview

Key Steps:

Get Google Pay token (standard flow, refer to main integration doc)
Call PAN_ONLY Check API to determine if CVV is needed
Based on check result:
- checkResult=false (PAN_ONLY): Collect CVV, pass in cardInfo.cvv
- checkResult=true (CRYPTOGRAM_3DS): Process payment directly, no CVV needed

API Usage Examples

RequestResponse - PAN_ONLY ModeResponse - Standard Mode

json

{
  "appId": "1727880846378401792",
  "gatewayName": "ronghan",
  "merchantNo": "800209",
  "merchantTxnId": "07f6d404-0de4-45fb-b80d-df47815422b4",
  "sign": "14d4b20492692820c39944ad6b63d871161da4b2c9ee15a106565c74fe85fbad",
  "tokenInfoJson": "{\"provider\":\"GooglePay\",\"tokenId\":\"{\\\"signature\\\":\\\"MEYCIQCvwmUnXStC/Qhdv6XQxe5xu3yiOCXYMpEp9tzdeHcQmgIhAOHakh9S47uHSPoObcSjHhIlQncEv+1oRkVY9zoYrYP7\\\",\\\"intermediateSigningKey\\\":{\\\"signedKey\\\":\\\"{\\\\\\\"keyValue\\\\\\\":\\\\\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE+F0IUGuqIge8NpRKXdhF+mHIu90N1X+uLJ0KuiYgqtMCNU/xQyn7FfeMUuIeLFFoFoRr/rvK/y3EtZUpTqjo5A\\\\\\\\u003d\\\\\\\\u003d\\\\\\\",\\\\\\\"keyExpiration\\\\\\\":\\\\\\\"1752655434646\\\\\\\"}\\\",\\\"signatures\\\":[\\\"MEQCID26+6e9vq0IHaWT3ORBCYJVR2Sr6eCpIO7V9fbKnXodAiBcu5gBmT/qwFjTsuRKmRPYYQfmhj4HV0auXrmHaPCPTw==\\\"]},\\\"protocolVersion\\\":\\\"ECv2\\\",\\\"signedMessage\\\":\\\"{\\\\\\\"encryptedMessage\\\\\\\":\\\\\\\"LFCsimI+8uLb6tX1mn0/c63DbvdPqOlLq8fJCJ8MnsTwvvQmaVWnLVFDikH5cePDCLz/D7Y8bUVW+Bfz38qB5WpcHtQrRoIQB1JEVoOL6tnFcrmQ87OeIfq9zgzWUp4TUF9NNJwYUit+2mrUeUR8elxq0ulavtiefhi7K0oIIFemBI2BfrlpIb/YjEsMbaAOLiYL+FvVyVxYiWeeGbsc5gAv0KJ9HrTKSIoMJ2fWoV/aMdX3iNnWTijr5x77JqHUdkMeo5xu/AUiODzqVAUl2UPCj/met2MFQpbvOea0102WdzrsviXisFniG5LQuxHyqXbYuoYRJhnpdk0F0XBL0tUAjiMd9rsULeCBc6JhxGgH+XnYorVVdXNKO08ZrFTQ+ZdaLEsiM+SatwGDa+Pt2+v5nbAq3SPwI0SgNmRdbkiOxdSKd//ZaooR0IQPQ21EJQAtdfr4KfMN0wmqA81VFrSuUySK8sVukyFde/OL9Fa/T0rLi7fqccF0d8Udl+C9Z3xReeMb03UuO+YcLT8g8QrdtDqungfCcP11hpmfx6M5/pebvZ1vYNFi\\\\\\\",\\\\\\\"ephemeralPublicKey\\\\\\\":\\\\\\\"BHcjhYHhu2QxoIGui2b451KY0ISiwi6u1y33bR0BHzqipB8XDx6YPAiRHYPI9umvwM+Pd9jGyNWBvOvI8xXiFaE\\\\\\\\u003d\\\\\\\",\\\\\\\"tag\\\\\\\":\\\\\\\"Ntfma/N099yxBNEd3lwB8aOjQws+K07IYa2Djfm5OeQ\\\\\\\\u003d\\\\\\\"}\\\"}\"}"}

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "cardNum": "411111******1111",
    "checkResult": false
  }
}

json

{
  "respCode": "20000",
  "respMsg": "Success", 
  "data": {
    "cardNum": "411111******1111",
    "checkResult": true
  }
}

Passing CVV to Payment API

For detailed payment API documentation, see: Google Pay Integration - Backend Payment Processing

Key Points

When checkResult is false, you must pass CVV in the cardInfo field of the payment request:

json

{
  "merchantNo": "800209",
  "merchantTxnId": "unique-transaction-id",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "tokenInfo": "{\"provider\":\"GooglePay\",\"tokenId\":\"...\"}",
  "cardInfo": "{\"cvv\":\"123\"}",  // PAN_ONLY mode requires CVV
  "billingInformation": "...",
  "txnOrderMsg": "...",
  "sign": "..."
}

When checkResult is true, no cardInfo field is needed:

json

{
  "merchantNo": "800209",
  "merchantTxnId": "unique-transaction-id",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "tokenInfo": "{\"provider\":\"GooglePay\",\"tokenId\":\"...\"}",
  // No cardInfo field
  "billingInformation": "...",
  "txnOrderMsg": "...",
  "sign": "..."
}

CVV Security Requirements

CVV must only be processed in memory, never stored in database
Never log CVV to log files
Use HTTPS encryption for transport
Clear immediately after payment completion

Common Error Scenarios

Invalid Token Format

Error: Token parsing failed
Cause: The tokenInfoJson parameter contains malformed or invalid Google Pay token data
Solution: Verify the Google Pay token is properly formatted and contains all required fields

Expired Token

Error: Token validation failed
Cause: The Google Pay token has expired and is no longer valid
Solution: Request a new Google Pay token from the customer and retry the check

Invalid Signature

Error: Request signature validation failed
Cause: The sign parameter is incorrect or generated with wrong parameters
Solution: Verify your signature generation process and ensure all parameters are included

Merchant Configuration Error

Error: Merchant not configured for Google Pay
Cause: Your merchant account is not properly configured for Google Pay processing
Solution: Contact Onerway support to verify your Google Pay merchant configuration

Implementation Best Practices

CVV Security Handling

CVV must only be processed in memory, never stored in database or files
Never log CVV to log files
All CVV-related requests must use HTTPS
Clear CVV from memory immediately after payment completion

API Calls

Call PAN_ONLY Check API first, then decide whether to collect CVV
Use the same Google Pay token for both check and payment
Set reasonable timeout (recommend 10-15 seconds)

CVV Collection UI

Clearly explain to users why CVV is needed
Validate CVV format in real-time (3 digits)
Use secure input methods (password type or masked display)

Error Handling

Handle API failures and network errors gracefully
Prepare fallback plan (can revert to standard redirect approach)

Merchant Integration Checklist

Prerequisites

Contact Onerway to enable PAN_ONLY Check feature
Understand CVV security handling requirements

API Integration

Successfully call PAN_ONLY Check API
Correctly parse checkResult field
Pass cardInfo.cvv correctly in payment API (when needed)

CVV Handling

Implement CVV input UI
Conditionally collect CVV based on checkResult
CVV not stored in database
CVV not logged to files

Security Requirements

All CVV-related requests use HTTPS
Clear CVV from memory after payment completion

Testing

Test PAN_ONLY scenario (CVV required)
Test CRYPTOGRAM_3DS scenario (no CVV)
Test error handling flows

Checkout

Credit Card Payment

Alternative Methods(SDK-based)

Order Management

Native SDK

Android SDK

Card Processing APIs (PCI Required)

Transaction Management (No PCI Required)

Local Payment Methods

Apple Pay

Payment Flow

Google Pay

Ethoca

RDR

Google Pay PAN_ONLY Check and Custom CVV Collection

Overview

Integration Prerequisites

API Request Parameters

Response

data

Integration Flow Overview

API Usage Examples

Passing CVV to Payment API

Key Points

Common Error Scenarios

Invalid Token Format

Expired Token

Invalid Signature

Merchant Configuration Error

Implementation Best Practices

CVV Security Handling

API Calls

CVV Collection UI

Error Handling

Merchant Integration Checklist

Prerequisites

API Integration

CVV Handling

Security Requirements

Testing

Android SDK

Local Payment Methods

Apple Pay

Payment Flow

Google Pay

Google Pay PAN_ONLY Check and Custom CVV Collection ​

Overview ​

Integration Prerequisites ​

API Request Parameters ​

Response ​

data ​

Integration Flow Overview ​

API Usage Examples ​

Passing CVV to Payment API ​

Key Points ​

Common Error Scenarios ​

Invalid Token Format ​

Expired Token ​

Invalid Signature ​

Merchant Configuration Error ​

Implementation Best Practices ​

CVV Security Handling ​

API Calls ​

CVV Collection UI ​

Error Handling ​

Merchant Integration Checklist ​

Prerequisites ​

API Integration ​

CVV Handling ​

Security Requirements ​

Testing ​

Google Pay PAN_ONLY Check and Custom CVV Collection

Overview

Integration Prerequisites

API Request Parameters

Response

data

Integration Flow Overview

API Usage Examples

Passing CVV to Payment API

Key Points

Common Error Scenarios

Invalid Token Format

Expired Token

Invalid Signature

Merchant Configuration Error

Implementation Best Practices

CVV Security Handling

API Calls

CVV Collection UI

Error Handling

Merchant Integration Checklist

Prerequisites

API Integration

CVV Handling

Security Requirements

Testing