menu

Payment API

What's on this page

Online Payments / Payment Methods / Google Pay

Google Payâ„¢

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Worldwide ✓ ✓ ✓ ✓

Google Pay is a payment method that allows customers to pay online or in-store via a POS terminal using their Google Pay wallet. The Google Pay wallet is linked to their Google account and backed by a credit or debit card.

A typical customer journey when using Google Pay involves:

  1. The customer selects the Google Pay payment method on a checkout page by clicking the Google Pay button.
  2. Google Pay shows a pop-up to the customer, where the customer can change the credit/debit card to be used for the transaction.
  3. The customer confirms the payment inside the pop-up window and the transaction is completed.

Visit the Google Pay home page for more information.

Note

Google Pay benefits from liability shift to issuers for Mastercard and Visa cards issued in the EU or the UK. For transactions that use Mastercard and Visa Android device tokens (CRYPTOGTAM_3DS), this occurs by default.

To receive a liability shift for PAN_ONLY transactions you would need to apply 3D Secure authentication to Google Pay. This step is handled by CCV for both direct integration and the hosted payment page integration.

Supported Networks

CCV currently supports the following card networks for Google Pay:

  • Mastercard
  • Visa

Terms and conditions

By using Google Pay, you agree to all Google Pay terms and conditions. For more information visit:

Integration Guide

Before you begin

  • If you haven’t done so already, make sure to set up your CCV test account and get your API key to start testing. For questions regarding your test account and credentials, contact ecommerce@ccv.eu. Contact psp-support@ccvlab.eu for technical support.

Note

Keep in mind that your API key must not be exposed to the customer for any reason whatsoever.

Hosted Payment Page Integration

The CCV hosted payment page integration for Google Pay provides an effortless solution for integrators to incorporate Google Pay into their web checkout process. This integration solution handles all necessary interactions with Google Pay, eliminating the need for you to manage payment credentials directly or register individually for Google Pay.

The below steps describe a typical web payment flow using the CCV hosted payment page for Google Pay transactions:

  1. The customer is done shopping and proceeds to checkout.

  2. The webshop presents the customer with the possible payment methods.

  3. The customer selects payment method Google Pay.

  4. At this point you want us to handle the payment. Create a new payment.

    • Specify a returnUrl to where the customer should be redirected after the payment is completed (successfully or otherwise). This can be a link to your webshop or a deeplink to your mobile application.
    • You can register to our notification system to receive notifications regarding the transaction.

    Example cURL request

    curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '<INSERT REQUEST BODY HERE>' https://api.psp.ccv.eu/payment

    Request body details

    {
  "amount" : 0.10,
  "currency" : "eur",
  "method" : "googlepay",
  "returnUrl" : "http://shop/return?order=123456",
  "merchantOrderReference" : "123456",
  "description" : "Order 123456",
  "language" : "eng"
}

  5. After we validate the input parameters, we’ll return a new payment transaction.

    Example response

    {
  "created" : 1667212745322,
  "method" : "googlepay",
  "language" : "eng",
  "currency" : "eur",
  "lastUpdate" : 1667212745322,
  "returnUrl" : "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP221031113905285CB87E194.1",
  "reference" : "A221031113905285CB87E194.1",
  "merchantOrderReference" : "123456",
  "amount" : 0.10,
  "paidout" : "no",
  "type" : "sale",
  "description" : "Order 123456",
  "status" : "pending"
}

  6. Redirect your customer to the payUrl as generated for the payment.

    • Your customer will be shown the Google Pay Hosted Payment page from CCV, and asked to click the Google Pay button.

  7. The Operating System will show a pop-up to the customer, where the customer can choose the credit/debit card to be used for this transaction.

  8. The customer will confirm the payment in the Google Pay pop-up.

  9. At this point, depending on the used authentication method of the Google Pay Token, CCV will directly process the payment or firstly ask the customer to authenticate themselves on the Google Pay Hosted Payment page before processing the payment.

  10. After the payment is successful, CCV will redirect the customer back to the returnUrl you provided in the initial payment request, see step 5. Import note: You should not assume that the customer will return! See the integration consideration below.

  11. At this point you don’t know whether the payment was successful or not. You must request the status of the payment to complete your order correctly.

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/transaction?reference=GP221031113905285CB87E194.1

    Example response

    {
  "method": "googlepay",
  "merchantOrderReference": "123456",
  "lastUpdate": 1632127457400,
  "details": { },
  "paidout": "no",
  "returnUrl": "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP221031113905285CB87E194.1",
  "amount": 0.10,
  "reference": "GP221031113905285CB87E194.1",
  "entryMode": "ecom",
  "created": 1631889346517,
  "currency": "eur",
  "language": "eng",
  "description": "Order 123456",
  "status": "success",
  "type": "sale"
}

  12. Assuming the payment is successful, you can contact the customer by email with a confirmation, show an appropriate notification on the shop, …

  13. As a side effect of completing a payment (successfully or not), we will notify you using either a webhook or notifications. This allows you to perform additional operations in your system like sending an email to your customer.

    Import note: A webhook does not contain any data except our payment reference. You must request the status of the payment before taking actions like shipping the order!

Integration Considerations

Many reasons exist for why the customer does not return to your app or webshop (e.g. the customer closes the browser window before CCV was able to redirect to the returnUrl). It is therefore highly recommended that your business logic does not depend on the customer returning to your app or webshop. The actual transaction status is independent of whether the customer returns. You should always verify the transaction status with CCV to determine if the payment succeeded.

You can do this by using webhooks, notifications on your backend system, or by polling the transaction status. For more details, see Read a transaction.

Direct Integration

Direct integration provides the most flexibility regarding styling and placement of the Google Pay payment method within the checkout process. This way you, as a merchant, are able to customize the Google Pay button to perfectly align with your brand and user experience. However, this approach requires more effort compared to CCV hosted checkout, as it involves direct integration with Google.

To begin processing Google Pay payments using direct integration, you need to complete the following four steps:

  1. Set up your Google Pay merchant account
  2. Integrate with Google Pay
  3. Add Google Pay to your payment form
  4. Request a payment and handle the result

Step 1: Set up Google Pay merchant account

You are required to register with Google Pay & Wallet Console and select CCV as your payment processor. Next, you need to set up an allow list for your domain inside the console. Make sure you are signed in as a Google Developer otherwise you will be redirected to Google Pay’s support page.

In addition, you have to retrieve your Google Pay merchant ID from your merchant account and use it in the next step.

Step 2: Integrate with Google Pay API

Google Pay provides an extensive guide that shows all the necessary steps to integrate the Google Pay API for your, web or Android application.

In this step, we focus on the web integration and provide examples to guide you through the CCV-related configuration.

Set your merchant ID

When building the MerchantInfo object, set the merchantId to your Google Pay merchant ID obtained in Set up your Google Pay merchant account.

Example: Google Pay API tokenizationSpecification

  {
    "merchantInfo": {
      "merchantId": "<YOUR GOOGLE PAY MERCHANT ID HERE>"
    }
  }

Defining your payment gateway

When providing your payment tokenization method, you enter the following parameters:

  • 'gateway': 'ccv'

  • 'gatewayMerchantId': '<YOUR CCV MERCHANT ID HERE>'

    Example: Google Pay API tokenizationSpecification

      "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "ccv",
      "gatewayMerchantId": "<YOUR CCV MERCHANT ID HERE>"
    }
  }

Note

The gatewayMerchantId is CCV generated merchant ID value which you receive during the boarding process.

For more information on the above statements, contact ecommerce@ccv.eu.

Define the supported card networks

The Google Pay API payment data request requires you to define the accepted card networks in the request. Make sure you only specify the card brands that you have enabled with CCV during the boarding process.

Example

const allowedCardNetworks = ["MASTERCARD", "VISA"];

Define the allowed card authentication methods

Google Pay offers two authentication methods:

  • CRYPTOGRAM_3DS: Google Pay links the payment credentials to an Android device and thereby ensures SCA compliance, allowing issuers to delegate authentication to Google for all subsequent payments made on that device.
  • PAN_ONLY: The card is stored on file inside the customer’s Google account, so the payment credentials are not tied to a specific Android device. This allows payments to be made from various platforms, including desktop or non-Android mobile web.

Since CCV handles the decryption of the encrypted token for you, you won’t be able to determine whether the authentication method used is PAN_ONLY or CRYPTOGRAM_3DS.

Example

const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];

Warning

As mentioned in 3D Secure for PAN_ONLY authentication we currently support CRYPTOGRAM_3DS and PAN_ONLY authentication methods.

When allowing both allowedCardAuthMethods you won’t be able to determine whether the authentication method used is PAN_ONLY or CRYPTOGRAM_3DS. Therefore, you should always redirect the customer to the payUrl received in the initial transaction response. The customer will then have to perform additional authentication on the Google Pay Hosted Payment page, or immediately be redirected back to the returnUrl provided in the initial request when no additional authentication is needed.

Note

If you restrict your accepted credentials to CRYPTOGRAM_3DS authentication method only, this limitation restricts the Google Pay payment method to customers using Android devices or Chrome desktop. When using this restriction, you do not have to redirect the customer to the payUrl, as there will be no additional authentication required.

Step 3: Add Google Pay to your payment form

Google Pay provides guidelines for displaying the Google Pay button on your checkout page and payment form. In this guide you can expect to find the following information:

  • Assets for all Google Pay related images;
  • Customizable button widget to easily create style adjustments;
  • Google Pay placement guides and best practices;
  • An example reference implementation;

Step 4: Request a payment and handle result

  1. Retrieve the unmodified token from the PaymentData response object that you received from the Google Pay API on your server.

  2. From your server make a request to the CCV payment endpoint using the token as part of the request details.

    Name Required Description Max Length
    googlePayEncryptedToken Yes The entire unmodified encrypted token as received by Google Pay in String format N/A

    Example

    {
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "googlepay",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "googlePayEncryptedToken": "<UNMODIFIED ENCRYPTED TOKEN HERE>"
  }
}

  3. After we validate the input parameters, we’ll return a new payment transaction.

    Example response

    {
  "created" : 1667212745322,
  "method" : "googlepay",
  "language" : "eng",
  "currency" : "eur",
  "lastUpdate" : 1667212745322,
  "returnUrl" : "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP221031113905285CB87E194.1",
  "reference" : "GP221031113905285CB87E194.1",
  "merchantOrderReference" : "123456",
  "amount" : 0.10,
  "paidout" : "no",
  "type" : "sale",
  "description" : "Order 123456",
  "status" : "pending"
}

  4. Redirect your customer to the payUrl as generated for the payment. Your customer will be presented with possible scenarios.

    • Your customer will be shown the Google Pay Hosted Payment page from CCV, that includes a popup screen to perform additional authentication.
    • Your customer will be redirected to the returnUrl provided in the initial transaction request when no additional authentication is needed.

  5. Conditional step: In case the transaction status is pending, an additional status request is necessary to complete your order correctly. If the transaction status is final e.g. success, you can proceed to the next step without performing a status check.

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/transaction?reference=GP221031113905285CB87E194.1

    Example response

    {
  "method": "googlepay",
  "merchantOrderReference": "123456",
  "lastUpdate": 1632127457400,
  "details": { },
  "paidout": "no",
  "returnUrl": "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP221031113905285CB87E194.1",
  "amount": 0.10,
  "reference": "GP221031113905285CB87E194.1",
  "entryMode": "ecom",
  "created": 1631889346517,
  "currency": "eur",
  "language": "eng",
  "description": "Order 123456",
  "status": "success",
  "type": "sale"
}

  6. Assuming the payment is successful, you can contact the customer by email with a confirmation, show an appropriate notification on the shop, …

  7. As a side effect of completing a payment (successfully or not), we will notify you using either a webhook or notifications. This allows you to perform additional operations in your system like sending an email to your customer.

    Import note: A webhook does not contain any data except our payment reference. You must request the status of the payment before taking actions like shipping the order!

3D Secure for PAN_ONLY authentication

At CCV, we support both the CRYPTOGRAM_3DS and PAN_ONLY authentication methods for both direct integration and the hosted payment page integration.

When the authentication method used is PAN_ONLY, then additional authentication is required. This is automatically handled by the CCV Google Pay Hosted Payment Page. You should always redirect the customer to the payUrl provided in the initial response to allow the customer to complete the authentication if needed.

Note

If you restrict your accepted credentials to CRYPTOGRAM_3DS authentication method only with a direct integration, this limitation restricts the Google Pay payment method to customers using Android devices or Chrome desktop. When using this restriction, you do not have to redirect the customer to the payUrl, as there will be no additional authentication required.

Authentication Exemptions and soft declines

Authentication exemptions are supported for Google Pay for both direct integration and the hosted payment page integration. See Exemptions for more information. When an exemption is provided, authentication will be skipped for a PAN_ONLY authentication method and the exemption will be passed to the acquirer. It is up to the issuer to accept the exemption or to soft decline the transaction and require additional authentication. Tokens using the CRYPTOGRAM_3DS authentication method are always authenticated. When the issuer requires additional authentication, the customer will be required to perform this. Without the additional authentication, the payment cannot proceed. After the authentication and payment, the customer is redirected to the returnUrl.

Note

It is possible that although you are providing an exemption and the issuer requires additional authentication, the authentication will be performed successfully frictionless without customer input.

Name Description
TRANSACTION_RISK_ANALYSIS Choose to trigger the Risk analysis for each transaction or to disable the TRA from being applied.
LOW_VALUE Transactions with an amount lower than 30 EURO. Every 5 transactions authentication is required or if the total amount of 100 euro non authenticated transactions is exceeded.
SECURE_CORPORATE Business to Business.

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "googlepay",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "authExemption": "LOW_VALUE"
  }
}

Test and go live

Testing Google Pay requires you to have:

  • A Google account, where you have to create a Google Pay wallet.
  • A CCV test API key that is used in combination with our API at https://api.psp.ccv.eu.

In order to test your Google Pay integration with your wallet, you have two options:

  • You can add a real card to your wallet which is mapped to a CCV test card of the same brand. Google Pay uses automatic payment data encryption to make sure your card info is safe and a test card is returned by the Google test environment. This ensures that your card is not charged during the testing phase!
  • You can enroll your wallet in Google’s test card suite and make use of the CCV test cards collection. This is the preferred option as this allows you to test FPAN and DPAN cards that are associated with actual TEST cards in our system. In addition, there is no need for you to add a real card to your wallet.

Simulation of different payment flows is done by adjusting the payment amount field to trigger various test scenarios.

See the testing page for more information.

Before going live

If you decide to integrate Google Pay using direct integration there are some additional steps you have to take into account before going live:

  • Request the CCV generated gatewayMerchantId during the boarding process.
  • Finish all the steps in the Google Pay API deploy to production documentation for web or for Android.

Refunds

Google Pay payments can be refunded within a limited time frame, depending on the card network that was used by the customer. Only successful payments can be refunded.

Visit our refund endpoint documentation for more info.

Authorise / Capture

Visit our Authorise and Capture documentation for more info.

Mandates

This section provides Google Pay-specific documentation on mandates.

Please refer to Mandates for more context regarding the following sections.

Creating mandates

Mandate API

Hosted payment page integration steps

  1. Create a Google Pay mandate with sequenceInfo to indicate the type of merchant initiated transaction

    • You can register to our notification system to receive notifications regarding the mandate.

    Example cURL request

    curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '<INSERT REQUEST BODY HERE>' https://api.psp.ccv.eu/api/v1/mandate

    Request body details

     {
   "merchantOrderReference": "123456",
   "type": "GOOGLEPAY",
   "returnUrl": "http://shop/return?order=123456",
   "sequenceInfo": {
     "type": "UNSCHEDULED",
     "source": "MIT"
   },
   "notificationRequests": [
     {
         "eventType": "MandateUpdated",
         "notificationUrl": "https://notifiy.shop/1233455"
     }
   ]
 }

    Example response

    {
  "type": "googlepay",
  "merchantOrderReference": "123456",
  "created": 1719302197405,
  "status": "pending",
  "mandateId": "MAN240625075637386CB87E193.0",
  "signUrl": "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP240625095637388CB87E191.E",
  "details": {},
  "returnUrl": "http://shop/return?order=123456"
}

  2. The response contains a mandateId that identifies the created mandate and a signUrl to complete the validation of the mandate. The mandate can only become active (or usable) after a successful signature is performed by visiting the signUrl.

  3. Redirect the customer to the signUrl where he/she can complete the Google Pay card check transaction (no funds are deducted from the customer since this a zero-amount transaction)

  4. If you subscribed for mandate status update notifications in the initial mandate create request, you will receive a notification on the specified notificationUrl once the validation Google Pay transaction is finished (successful or otherwise).

    • In case you did not subscribe to any notifications, manual polling of the mandate status is required to retrieve the final status of the mandate contract.

    Example cURL request

    curl --basic --user apikey: -H "User-Agent: Shop123456" https://api.psp.ccv.eu/api/v1/mandate/MAN240625075637386CB87E193.0

    Example response

    {
  "type": "googlepay",
  "merchantOrderReference": "123456",
  "created": 1719302197392,
  "status": "active",
  "mandateId": "MAN240625075637386CB87E193.0",
  "modified": 1719304200379,
  "signUrl": "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP240625095637388CB87E191.E",
  "details": {},
  "returnUrl": "http://shop/return?order=123456",
  "externalMandateReference": "ABC3076490714"
}

  5. Assuming the mandate validation is successful, you can now start using mandateId in conjunction with our payment API to create transactions on behalf of the customer without the need for further customer interaction.

Direct integration steps

  1. Retrieve the unmodified token from the PaymentData response object that you received from the Google Pay API on your server.

  2. From your server make a request to creating a Google Pay mandate. The request body should include sequenceInfo to indicate the type of merchant initiated transaction and the unmodified token as part of the request details.

    • You can register to our notification system to receive notifications regarding the mandate.
    • The mandate can only become active (or usable) after a successful signature is performed by visiting the signUrl when you are allowing both authentication methods PAN_ONLY and CRYPTOGTAM_3DS.

    Example cURL request

    curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '<INSERT REQUEST BODY HERE>' https://api.psp.ccv.eu/api/v1/mandate

    Request body details

     {
   "merchantOrderReference": "123456",
   "type": "GOOGLEPAY",
   "returnUrl": "http://shop/return?order=123456",
   "sequenceInfo": {
     "type": "UNSCHEDULED",
     "source": "MIT"
   },
   "details": {
     "googlePayEncryptedToken": "<UNMODIFIED ENCRYPTED TOKEN HERE>"
   },
   "notificationRequests": [
     {
         "eventType": "MandateUpdated",
         "notificationUrl": "https://notifiy.shop/1233455"
     }
   ]
 }

    Example response

    {
  "type": "googlepay",
  "merchantOrderReference": "123456",
  "created": 1719302197405,
  "status": "active",
  "mandateId": "MAN240625075637386CB87E193.0",
  "signUrl": "https://onlinepayments.ccv.eu/googlepay/payment.html?reference=GP240625095637388CB87E191.E",
  "details": {},
  "modified": 1719999440503,
  "returnUrl": "http://shop/return?order=123456",
  "externalMandateReference": "ABC3076490714"
}

  3. Redirect the customer to the signUrl where he/she can complete the Google Pay card check transaction (no funds are deducted from the customer since this a zero-amount transaction) when you are allowing both authentication methods PAN_ONLY and CRYPTOGTAM_3DS.

  4. Assuming the mandate validation is successful, you can now start using mandateId in conjunction with our payment API to create transactions on behalf of the customer without the need for further customer interaction.

Payment API

The same considerations as described previously regarding a “hosted payment page” versus “direct” integration, also apply here.

Below, you can find an example request and response for creating a Google Pay mandate using the Payment API in combination with the hosted payment page. If a direct integration is desired, the googlePayEncryptedToken can be provided directly in the request details as described here.

Example request (hosted payment page)

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "googlepay",
  "language" : "NLD",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "obtainMandate" : "yes",
  "sequenceInfo" : {
    "source" : "MIT",
    "type" : "UNSCHEDULED"
  }
}

Example response (hosted payment page)

{
  "reference": "GP221031113905285CB87E194.1",
  "method": "googlepay",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1720535647724,
  "created": 1720535647724,
  "status": "pending",
  "amount": 0.1,
  "returnUrl": "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "payUrl": "http://onlinepayments.ccv.eu/vpos/googlepay/payment.html?reference=GP221031113905285CB87E194.1",
  "paidout": "no",
  "details": {
    "mandateId": "MAN240709143407731CB87E19D.0"
  }
}

Performing payments using mandates

The steps required for performing payments using mandates are the same regardless of the used payment method.