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.
Related API reference
| Step | Reference | Payloads |
|---|---|---|
| Create the payment method | POST /v1/confirmation-tokens | Request · Response |
| Create the intent | POST /v1/payment-intents | Request · Response |
| Confirm the intent | POST /v1/payment-intents/{id}/confirm | Request · 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.comandshop.example.comare 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
TESTenvironment, 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
loadPaymentDatafrom 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.cardFundingSourceorinfo.assuranceDetails, you can send them; other fields are not accepted. customeris 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
last4is the device number's, not the buyer's physical card's. Thebrandis 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
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:
| Code | Cause |
|---|---|
payment_methods.google_pay_not_enabled | Google Pay is not enabled for your account, or card payments or Google Pay are turned off in that mode. |
payment_methods.invalid_google_pay_token | The Google credential is invalid, expired, or was issued for another account. Ask for a new Google Pay payment. |
payment_methods.google_pay_unavailable | Google Pay is not available right now. Retry later; if it persists, contact support. |
google_pay_token_replayed | That device token was already used; ask for a new Google Pay payment. |
google_pay_credential_unavailable | The single-use payment method was already used or no longer has a credential; create a new one. |
google_pay_unsupported_network | ONVO does not accept device tokens from that network; ask the buyer for another card. |
google_pay_not_supported_by_processor | Your 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.