Skip to main content

Google Pay

Google Pay lets you charge the cards the buyer keeps in their Google account, from Chrome and Android devices. There are two ways to accept it:

  • ONVO Checkout: turn Google Pay on in the Dashboard and the button appears in your Checkout, with no code.
  • Your own site or app: integrate Google Pay with your own Google account, turn the payment into an ONVO payment method, and charge with payment intents.

Google Pay accepts the same card networks as your account.

StepReferencePayloads
Create the payment methodPOST /v1/confirmation-tokensRequest · Response
Create the intentPOST /v1/payment-intentsRequest · Response
Confirm the intentPOST /v1/payment-intents/{id}/confirmRequest · Response

Before you start​

  • Turn on Google Pay in the Dashboard, under Settings → Payment methods. It requires card payments to be on, and the switch applies per mode: test and live are enabled separately.
  • If you don't see Google Pay among your payment methods, contact support to have it enabled for your account.
  • The button appears in Chrome and on Android devices when the buyer has a supported card in their Google account.

ONVO Checkout (no code)​

If you charge with Checkout, turning Google Pay on in the Dashboard is enough. ONVO is already registered with Google for its Checkout, so the button appears without you registering anything. You need nothing else from this guide.

Google Pay on your own site or app​

Four steps: register your business with Google, set up Google Pay with ONVO as the gateway, turn Google's response into an ONVO payment method, and charge from your server with a payment intent.

1. Register your business with Google​

On your own site or app, the merchant Google knows is you, not ONVO:

  • Sign up in the Google Pay & Wallet Console as a merchant and accept the Google Pay terms. Google assigns you a Google merchant ID (merchantId).
  • For production, create the Google Pay integration in the console. Choose the Gateway integration type and ONVO as the payment processor.
  • Add every fully qualified domain where you will show the button, or your Android app's package, together with the screenshots of your purchase flow that Google asks for. example.com and shop.example.com are two domains.
  • Submit the integration for approval. Google reviews it manually before it enables production access, so request it early.
  • While you build, use Google's TEST environment, which needs no registration or approval.

Google sets the requirements and the approval process; see its production access guide for websites or for Android apps.

If your account has Google Pay among its payment methods, ONVO already accepts Google credentials from your own site or app. Ask ONVO support to confirm your ONVO account ID, which you will use in the next step.

2. Set up Google Pay with ONVO as the gateway​

In the Google Pay request, set onvopay as the gateway and your ONVO account ID as gatewayMerchantId:

const cardPaymentMethod = {
type: "CARD",
parameters: {
allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
allowedCardNetworks: ["MASTERCARD", "VISA", "AMEX"],
},
tokenizationSpecification: {
type: "PAYMENT_GATEWAY",
parameters: {
gateway: "onvopay",
gatewayMerchantId: "<YOUR_ONVO_ACCOUNT_ID>",
},
},
};

const paymentsClient = new google.payments.api.PaymentsClient({
environment: "TEST", // "PRODUCTION" with your approved access and ONVO live keys
});

const paymentData = await paymentsClient.loadPaymentData({
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [cardPaymentMethod],
merchantInfo: {
merchantId: "<YOUR_GOOGLE_MERCHANT_ID>",
merchantName: "My store",
},
transactionInfo: {
totalPriceStatus: "FINAL",
totalPrice: "5000.00",
currencyCode: "CRC",
countryCode: "CR",
},
});
  • ONVO checks that every Google credential was issued for your account ID. A credential issued for another account is rejected.
  • Only advertise the card networks your account accepts.
  • Call loadPaymentData from the buyer's interaction with the Google Pay button, following Google's brand guidelines.

3. Create the payment method in ONVO​

Send Google's response (paymentData) to ONVO unchanged. Do not modify, parse, or log the encrypted token in paymentMethodData.tokenizationData.token.

In the browser, with ONVO.js and your publishable key:

<script src="https://js.onvopay.com/v1/"></script>
<script>
const onvo = ONVO("onvo_live_publishable_key_...");

// Call it from the Google Pay button click, with the full
// loadPaymentData response.
async function payWithGooglePay(paymentData) {
const { paymentMethodId } = await onvo.createGooglePayPaymentMethod({
paymentData,
});

// Send the paymentMethodId to your own server: this route is yours, not ONVO's.
// Your server creates and confirms the intent with your secret key (step 4).
const response = await fetch("/orders/1001/pay", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ paymentMethodId }),
});
return response.json();
}
</script>

From your server (for example, from an Android app that sends paymentData to your backend), with your secret key:

curl https://api.onvopay.com/v1/confirmation-tokens \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "google_pay",
"payload": {
"apiVersion": 2,
"apiVersionMinor": 0,
"paymentMethodData": {
"type": "CARD",
"description": "Visa •••• 1234",
"info": { "cardNetwork": "VISA", "cardDetails": "1234" },
"tokenizationData": {
"type": "PAYMENT_GATEWAY",
"token": "<Google tokenizationData.token, unchanged>"
}
}
},
"customer": { "name": "Ana Pérez", "email": "ana@example.com" }
}'
{
"paymentMethodId": "cl502zv0d0127ebdp3zt27651",
"cardWalletId": "cm2wal3t0000108l5c6r1h2kq"
}
  • Use the real values from Google's response. If Google returns info.cardFundingSource or info.assuranceDetails, you can send them; other fields are not accepted.
  • customer is optional. ONVO.js does not forward the email or addresses Google collected: associate the customer from your server if you need it.
  • Creating the payment method does not charge the buyer.
  • If you use fraud monitoring, call onvo.startSignalSession({ paymentIntentId }) before you confirm the intent, as with cards.

4. Charge from your server​

Create the payment intent with your secret key. The amount is in the currency's smallest unit: 500000 is ₡5,000.00 and must match the total in the Google Pay sheet (totalPrice: "5000.00" in the previous example).

curl https://api.onvopay.com/v1/payment-intents \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 500000,
"currency": "CRC",
"description": "Order #1001"
}'

Confirm the intent with the paymentMethodId:

curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
-X POST \
-H "Authorization: Bearer $ONVO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentMethodId": "cl502zv0d0127ebdp3zt27651"
}'

Handle the result like any payment intent. If status is succeeded, the payment is approved. If the intent requires authentication (requires_action), present it with onvo.handleNextAction({ paymentIntentId }), as described in 3D Secure. If confirmation fails, the intent goes back to requires_payment_method with the details in lastPaymentError. Check the intent's final status on your server before you fulfill the order.

Identify a Google Pay payment​

The payment intent shows that the charge came from Google Pay in paymentMethod.card.wallet:

{
"paymentMethod": {
"type": "card",
"card": {
"brand": "Visa",
"last4": "1234",
"wallet": { "type": "google_pay" }
}
}
}

When the payment did not come from a wallet, wallet is null.

Device tokens​

With CRYPTOGRAM_3DS, Google can return a device token: a card number specific to the phone that comes with a cryptogram that already authenticates the payment. ONVO decides how to charge it based on your account; there is nothing for you to configure. When ONVO charges with the cryptogram:

  • The payment method is single use: it confirms one intent only.
  • ONVO charges with the cryptogram and the electronic commerce indicator (ECI) Google returns, with no extra 3D Secure step.
  • The intent's last4 is the device number's, not the buyer's physical card's. The brand is the real one.

So treat every Google Pay payment method as single use: confirm the intent right away, while Google's credential is still valid, and if you need to retry, ask the buyer for a new Google Pay payment.

Important​

Don't modify Google's response

Send paymentMethodData.tokenizationData.token exactly as Google returns it, as JSON text inside the request: do not parse it, Base64-encode it, or log it. Google's credentials expire: create the payment method and confirm the intent without delay.

Common errors and their cause:

CodeCause
payment_methods.google_pay_not_enabledGoogle Pay is not enabled for your account, or card payments or Google Pay are turned off in that mode.
payment_methods.invalid_google_pay_tokenThe Google credential is invalid, expired, or was issued for another account. Ask for a new Google Pay payment.
payment_methods.google_pay_unavailableGoogle Pay is not available right now. Retry later; if it persists, contact support.
google_pay_token_replayedThat device token was already used; ask for a new Google Pay payment.
google_pay_credential_unavailableThe single-use payment method was already used or no longer has a credential; create a new one.
google_pay_unsupported_networkONVO does not accept device tokens from that network; ask the buyer for another card.
google_pay_not_supported_by_processorYour account can't charge that device token right now; ask for a new Google Pay payment and, if it persists, contact support.

Testing​

In test mode, with onvo_test_ keys and Google's TEST environment, charges are simulated and no money moves. You need no Google registration or approval to test. In TEST, Google returns test cards even when the buyer picks a real card from their account.

For production, use Google's PRODUCTION environment with your approved merchant ID and onvo_live_ keys. Live keys work once your ONVO account is activated.