1. Introduction

1.1 About CellPoint Digital

CellPoint Digital is a Payment Orchestration Platform pioneer, enabling merchants to adopt multi-acquirer payment models that open up new opportunities for growth. We help merchants meet customer expectations of a flexible, frictionless checkout with the payment methods they want to use, no matter where they are in the world.

With 400+ payment methods in our ecosystem, CellPoint Digital increases digital revenue while reducing payment costs, total cost of ownership, and time to market. A fintech leader in payment innovation and expanding rapidly into multiple markets, our mission is to help unify and accelerate our customers’ digital transactions.
We are a PCI DSS certified organization.

1.2 About Velocity POP

CellPoint Digital’s Velocity Payment Orchestration Platform (POP) simplifies payment processing across all digital channels while handling PCI DSS compliance through a variety of integration options. Its growing payment ecosystem accommodates several global and local acquiring banks, PSPs, card schemes, alternative payment methods, and offline payment methods.

Velocity also offers business services such as stored cards, pay-by-link, split payments, multi-currency pricing, intelligent routing, recurring, and instalments payment out of the box.

2. Scope of the Document

The document helps you integrate Google Pay™ with your web channel or native application. The document is a sub-set of the CPD Velocity API Integration Guide, which can be made available on request.

3. Glossary of Terms

The terms used in the document are defined in the table below.

4. Integration Prerequisites

The Google PayTM integration prerequisites are listed in the table below.

5. API Specifications – Payments

5.1 Authentication and Security Management

All API requests must be made through HTTPS. You must authenticate all requests by using the HTTP Authorization header. The POP API header value format is as follows:

• Use HTTP basic authentication to authenticate the request.
• Specify the auth-parameter, where the overall parameter value is provided in the form is
  x-cpm-sec-token.

Note: x-cpm-sec-token is a unique value that you generate for a unique request. Velocity uses this value to verify if a request is submitted multiple times. This value must be a valid UUID (Universally Unique Identifier), with a canonical format using hexadecimal text with inserted hyphen characters. You can consult CPD support to check if this is enabled for your account.

The following is an example of parameters in HTTP header section:

x-cpm-sec-token- 6lutO0jd0h1YjlHqjAn6cjKYF5n2ZJjp%2fDNk08IGKS0%3d

To integrate Google Pay™ with your application, complete the following steps:

1. Initialize payment using mpoint/initialize-payment.
2. Authorize payment using /mpoint/authorize-payment.
   Note: You must Process Response of initialize payment to complete the integration process.

5.2 Google Pay™ Integration

Before you start the API integration, you must follow the Google Web Integration checklist and branding guidelines as follows:

• Overview
• Integration checklist
• Brand guidelines

5.3 Google Pay™ Integration flow

6. Initialize Payment

You can invoke the initialize-payment API to initiate a new payment transaction using Velocity POP. It returns the required transaction information and merchant configuration for the payment to be processed successfully. If you have already integrated with CPD Velocity POP Platform APIs, you do not require any additional setup to generate the request. However, you must be able to process the response received during the integration to retrieve the response’s Google PayTM configuration in addition to processing other payment methods.

Note: For details about the initialize-payment API, refer to the CPD Velocity API Integration Guide, section Initialize payment.

You can access the API from the following path:

6.1 Initialize Request

The following is an example of the initialize payment request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<initialize-payment account="[integer]" client-id="[integer]">
		<transaction order-no="CPM1601976034055" type-id="[integer]" >
			<amount currency-id="[integer]" country-id="[integer]">100</amount>
		</transaction>
		<client-info language="en" app-version="1.43" sdk-version="1.43" version="1.43" platform="HTML5">
			<mobile operator-id="[integer]" country-id="200">[mobile number]</mobile>
			<email>[email]</email>
			<customer-ref>[customer-ref]</customer-ref>
		</client-info>
	</initialize-payment>
</root>

The Initialize Request parameters are listed in the table below.

6.2 Initialize Request

The response from Velocity server has information about the transaction such as transaction ID and amount, along with the configured payment methods or cards types. The merchants must call this API when a customer checks out.

The initialize payment response can be divided into the following chunks:

• Merchant configuration
• Transaction information
• Card information

The following fields from the initialize payment response are required to call the /mpoint/pay and /mpoint/authorize API:

6.2.1 Google PayTM response for a WEB channel.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
<name>Test</name>
    <callback-url>[merchant URL for callback]</callback-url>
    <accept-url />
  </client-config>
  <transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
    <amount country-id="[integer]" currency="DKK" format="{PRICE} {CURRENCY}" symbol="">10025</amount>
    <mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
    <callback-url>[CALLBACK URL]</callback-url>
    <accept-url />
  </transaction>
 
    <session id="6143" total-amount="1" type="1">
        <amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="" currency-id="0" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
    </session>
    <wallets>
       <card cvc-length="-1" cvcmandatory="false" dcc="false" enabled="true" id="41" installment="0" max-length="-1" min-length="-1" payment-type="3" preferred="false" presentment-currency="false" processor-type="3" psp-id="-1" state-id="1" type-id="41">
       <name>Google Pay</name>
       <prefixes><prefix id="200"><min>-1</min><max>-1</max></prefix>
       <prefix id="202"><min>-1</min><max>-1</max></prefix></prefixes>
<url method="overlay" />
<head>&lt;script&gt;var baseRequest={apiVersion: 2, apiVersionMinor: 0 };var allowedCardAuthMethods=['PAN_ONLY','CRYPTOGRAM_3DS'];var allowedCardNetworks=['MASTERCARD','DISCOVER','VISA','AMEX'];var assuranceDetailsRequired=true;var tokenizationSpecification={type:'PAYMENT_GATEWAY',parameters:{'gateway':'cellpointmobile','gatewayMerchantId':'10106'}};var baseCardPaymentMethod={type:'CARD',parameters:{allowedAuthMethods:allowedCardAuthMethods,allowedCardNetworks:allowedCardNetworks,assuranceDetailsRequired:assuranceDetailsRequired}};var cardPaymentMethod=Object.assign({},baseCardPaymentMethod,{tokenizationSpecification:tokenizationSpecification});let paymentsClient=null;function getGoogleIsReadyToPayRequest(){return Object.assign({},baseRequest,{allowedPaymentMethods:[baseCardPaymentMethod]})} function getGooglePaymentDataRequest(){var paymentDataRequest=Object.assign({},baseRequest);paymentDataRequest.allowedPaymentMethods=[cardPaymentMethod];paymentDataRequest.transactionInfo=getGoogleTransactionInfo();paymentDataRequest.merchantInfo={ merchantName:'Virgin Holidays'};return paymentDataRequest} function getGooglePaymentsClient(){if(paymentsClient===null){return(new google.payments.api.PaymentsClient({environment:'TEST'}));}} function getGoogleTransactionInfo(){return{countryCode:'GB',currencyCode:'GBP',totalPriceStatus:'FINAL',totalPrice:'152.00'}}</head>
<body>&lt;script async="true" src="https://myurl/js/googlepay.js"&gt;&lt;/script&gt; &lt;script async="true" src="https://pay.google.com/gp/p/js/pay.js"&gt;&lt;/script&gt;</body>
<auth-token>Auth-Token</auth-token>Google Pay
</card>

    </wallets>
</root>

6.2.2 Google Pay™ Response for the Native APP Channel.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
    <name>Test</name>
    <callback-url>[merchant URL for callback]</callback-url>
    <accept-url />
  </client-config>
  <transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
    <amount country-id="[integer]" currency="DKK" format="{PRICE} {CURRENCY}" symbol="">10025</amount>
    <mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
    <callback-url>[CALLBACK URL]</callback-url>
    <accept-url />
  </transaction>
 
    <session id="6143" total-amount="1" type="1">
        <amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="" currency-id="0" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
    </session>
    <wallets>
        <card cvc-length="-1" cvcmandatory="true" dcc="false"
            enabled="true" id="[Google Pay wallet type Id]" installment="0" max-length="-1"
            min-length="-1" payment-type="3" preferred="false" processor-type="3"
            psp-id="[ACQ ID]" state-id="1" type-id="[Google Pay wallet type Id]">
            <name>Google Pay</name>
            <prefixes>
                <prefix>
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
                <prefix>
                    <min>-1</min>
                    <max>-1</max>
                </prefix>
            </prefixes>
            <url method="overlay" />
            <hidden-fields>
                <card-brands>'VISA','MASTERCARD'</card-brands>
                <merchant-request-id>[transaction-id]</merchant-request-id>
                <gatewayMerchantId>[merchant-id]</gatewayMerchantId>
                <gateway>cellpointmobile</gateway>
                <tokenizationType>PAYMENT_GATEWAY</tokenizationType>
                <currency-code>PHP</currency-code>
                <amount>11232.00</amount>
                <environment>TEST</environment>
                <mode>1</mode>
                <payment-methods>'PAN_ONLY'</payment-methods>
                <countryCode>PH</countryCode>
                <merchantName>[Merchant Name]</merchantName>
            </hidden-fields>
            <return-url>[return url]</return-url>
            Google Pay
        </card>
    </wallets>
 
</root>

The Initialize Response parameters are listed in the table below.

Note: The wallets, APM, and gateway have the same parameters as card parameters in this table.

6.3 Process Response

To ensure seamless Google Pay™ configuration with your web or mobile browser, you need to process the response that you receive from the Velocity server.

6.3.1 Process Initialize Response on the Web

To process the initialize response on the web, complete the following steps:

<div wallet-id="41">
    <div />
</div>

Sample Checkout Page for a Web Channel

Sample Checkout Page for an Application.

When the user clicks on the payment page, it opens to the Google Pay™ overlay, which displays the login page to authenticate the user to perform payment. We need to implement the below two method process to handle the callback receive from the Google Pay™ wallet which gives the Successful or Failure Callback to the portal.

onWalletProcess (Payment, Network)

The onWalletProcess (payment, network) function is called every time your customer selects a card from Google Pay™ wallet. Implement this function as shown in the following sample code:

var selectedPayment={};
window.onWalletProcess = (payment, network) => {
  selectedPayment.token = payment.authorization_token;
  selectedPayment.network = network.toLowerCase();
}
 
// Data in the selectedPayment variable is used in authorize-payment request for getting token and network.

onWalletFailureCallback(err)

To handle the payment failure form for Google Pay™ API, implement the onWalletFailure method.
It contains an error argument to, which shows the reason of payment failure from Google Pay™ API.

Note: For the UI branding guidelines, please follow the Google page, which helps the user follow the page https://developers.google.com/pay/api/web/guides/ux-best-practices.

6.3.2 Process Pay Response

You can skip this call as you are not required call /mpoint/pay API for Google Pay™.

6.3.3 Process Response of a Customer's Google Pay™ Card Selection on the Web

After your customer selects a card from the Google Pay™ wallet, the control comes back to the HTML page. After you receive the callback, the payment process is at a stage where the user has selected the card and Google Pay™ has passed the token back on to the page. Use this token and complete the payment in the following manner:

1. Construct the /mpoint/authorize-payment request according to the CPD Velocity API Integration Guide
2. Pass the token that you receive in "SelectedPayment.token" as a "token" element in authorize-payment request. Refer section 7.

7. Authorize Payment

The authorize payment request is used to authorize a payment. The API is available at the following path:

7.1 Authorize Request

The payment authorize request is initiated using the payment token returned by Google Pay™ after a card is selected for completing the transaction by the user. The expected format of <token> is base-64 encoded string.

Sample Token from Google Pay™ after base-64 decode: paymentMethodToken:token:

{"signature":"MEUCIQC3NcKqGIPaVXOPM/Bj+Z7n0aj+4W2tXAGFhUHyiWnAygIgA63/Tua2SoSShO44twYIgoc+iWEYGqwq3OyLW9PgEew\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"CLMBGB3LYeQn3EAVIpJviCSjS0Um82lEM8f1nHzSie2DFe4DcD1kvBtwqYbMgPO2L4g6qIokQGNL5Q6PoDhfaPIfgR4d1mnrDJ86XMN+Dz2CbiePbhHKGU3onUdJgd7aWGU9Mk9FevGJm5sYWdazyReq/PO2ajwuNraoXzNxjxLeXiYsEcl1HvmgwVv50tP9AhKCgf1UnNH1HUQXlSobFaUVayVQpqn3XOtHo/BGv5O92T34vdC7lOpAjVRrHkrHqhdoZ6M4IzZLl6TlA/9NsLvUl2TAKWUFq/1j07yVEDs4K5UwPs5LViJc4rlMPywI44B2zQnhB3h9iZW8TFTOBGU/uf+0f9t0f0D9j5e4o+46+Ki9jp8T5llaDhxpFJJzDPb5u+oAM1ZHZdP6lhVWQ77qDQ4\\u003d\",\"ephemeralPublicKey\":\"BBcuSTInFFydICDeDO6FnXfxgOpyrmRy5klmMGImkjWas1L46bFrFh6zNmZnHEAqXrQHSd/x/HDSCTCo0AFWx0Y\\u003d\",\"tag\":\"033Q7bumMQTQ5r/Ov9DMOQNhrMEpbmYjnvWZCs8C/lU\\u003d\"}"}

The following code is an example of making payment:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <authorize-payment account="[account-id]" client-id="[client-id]">
        <transaction type-id="1009" id="[transaction-id]">
            <card network="visa" type-id="41">
                <amount currency-id="[currency-id]" country-id="[country-id]">[amount-in-decimals]</amount>
                <token>[token]</token>
                <address country-id="[country-id]">
                    <full-name>Name</full-name>
                    <street>Street</street>
                    <postal-code>1111</postal-code>
                    <city>CityName</city>
                    <state>StateName</state>
                </address>
          </card>
            <hmac>f2cd1d924416574d571c6e59d5e00d1a28a462cd9d98f718057267aec380430502ae0640a71af230125af855878fa41571d1fe1ea6fbade401f3fd974c826fd5
            </hmac>
        </transaction>
        <client-info language="us" version="1.46"
            platform="Android/10(29)">
            <mobile operator-id="64300" country-id="[country-id]">[mobile-number]</mobile>
            <email>[email]</email>
            <ip>[ip]</ip>
            <device-id>1f771072-2fc8-4e2a-9d52-7038f8b385e1</device-id>
        </client-info>
    </authorize-payment>
</root>

The Authorize Request parameters are listed in the table below.

7.2 Authorize Response

For Google Pay™, we receive the 2 types of response as per the data we receive from the Google Pay™ Wallet.

7.2.1 Case 1

The Velocity server sends the response informing if the transaction authorization was a success or a failure. The following example shows that a payment request was authorized successfully:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2000">Payment authorized</status>
</root>

The Authorize Response parameters are listed in the table below.

7.2.2 Case 2

In some cases, we will receive the parse challenge from the provider where the user needs to complete the parsed challenge to complete the transaction.

7.2.3 3DS 1.0 Authentication Required

The following is an example of response received for 3DS 1.0 authentication required:

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <status code="2005">3d verification required</status>
   <parsed-challenge>
      <action type-id="11">
         <url content-type="application/x-www-form-urlencoded" method="post">https://3ds-acs.test.modirum.com/mdpayacs/creq?token=220646651.1670842886.KJTk10b79hUunC4uy7erl0gOsaZW7UHoEh56a0-9Un4</url>
         <hidden-fields>
            <creq>ewogICAiYWNzVHJhbnNJRCIgOiAiZjEyZjUxMDItOTI4ZC00N2I3LTg1YjAtZTM5NDhjYjIzZDY1IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiMzIwYmUxM2MtYmQ4ZC01YzliLTgwMDAtMDAwMDAxMjRiYTM1Igp9</creq>
            <TermUrl>https://5j.mesb.sit.cpm.dev/mpoint/first-data/threed-redirect?referencedTransactionId=5721077</TermUrl>
         </hidden-fields>
      </action>
   </parsed-challenge>
</root>

The steps to process the authorize response for the 3DS 1.0 authentication are as follows:

7.2.4 3DS 2.0 Authentication Required

The following is an example of response received for 3DS 2.0 authentication required:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2005" sub-code="2005002">3D Secure Verification Required</status>
    <web-method>&lt;html class="no-js" lang="en" xmlns="http://www.w3.org/1999/xhtml"&gt; &lt;head&gt; &lt;META http-equiv="Content-Type" content="text/html; charset=utf-8"&gt; &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8"&gt; &lt;meta charset="utf-8"&gt; &lt;title&gt;3D Secure Processing&lt;/title&gt; &lt;link href="https://myurl/mdpaympi/static/mpi.css" rel="stylesheet" type="text/css"&gt; &lt;/head&gt; &lt;body&gt; &lt;div id="main"&gt; &lt;div id="content"&gt; &lt;div id="order"&gt; &lt;h2&gt;3D Secure Processing&lt;/h2&gt; &lt;script src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/red.js" defer&gt;/* needed for xsl to xhtml */&lt;/script&gt; &lt;div id="spinner"&gt; &lt;img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/preloader.gif" alt="Please wait.."&gt;&lt;/div&gt; &lt;img src="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/static/mc_idcheck_hrz_ltd_pos_103px.png" alt="MasterCard ID Check"&gt;&lt;iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" xmlns="http://www.w3.org/1999/xhtml"&gt;&lt;!--.--&gt; &lt;/iframe&gt;&lt;form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame"&gt; &lt;input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"&gt;&lt;input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogImRkZjQ5MTYxLTZiYjgtNWY5YS04MDAwLTAwMmVhNzE4N2E0ZCIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovLzNkcy1tcGktY2VsbHBvaW50bW9iaWxlLnRlc3QubW9kaXJ1bS5jb20vbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTIwMDM3MTg5NDg2MSZkaWdlc3Q9UFVyQ3ZnWnZZeHp0cVU1a1N2MTdTdnhjUlVXaTAwWVByNlh5MmttWCUyQkg0JTNEIiB9"&gt; &lt;/form&gt;&lt;div id="formdiv"&gt; &lt;div&gt; &lt;form id="webform0" name="ddcoll" method="POST" action="https://3ds-mpi-cellpointmobile.test.modirum.com/mdpaympi/MerchantServer" accept_charset="UTF-8"&gt; &lt;input type="hidden" name="txid" value="200371894861"&gt;&lt;input type="hidden" name="TDS2_Navigator_language" value=""&gt;&lt;input type="hidden" name="TDS2_Navigator_javaEnabled" value=""&gt;&lt;input type="hidden" name="TDS2_Navigator_jsEnabled" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_colorDepth" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_height" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_width" value=""&gt;&lt;input type="hidden" name="TDS2_Screen_PixelDepth" value=""&gt;&lt;input type="hidden" name="TDS2_TimezoneOffset" value=""&gt;&lt;input type="hidden" name="digest" value="5woOk3ql1bNMosc5yuyLXdk8k47KCTR+uVloWvAA/XQ=" readonly="true"&gt;&lt;input type="submit" name="submitBtn" id="submitBtn" value="Please click here to continue"&gt; &lt;/form&gt; &lt;/div&gt; &lt;/div&gt; &lt;noscript&gt; &lt;div align="center"&gt; &lt;b&gt;Javascript is turned off or not supported!&lt;/b&gt; &lt;br&gt; &lt;/div&gt; &lt;/noscript&gt; &lt;/div&gt; &lt;div id="content-footer"&gt;&lt;/div&gt; &lt;/div&gt; &lt;/div&gt; &lt;/body&gt; &lt;/html&gt;</web-method>
    <return-url>https://av.uat-01.cellpointmobile.net/mpi/modirum/threed-redirect</return-url>
    <card-mask>553571******3561</card-mask>
    <expiry>01/23</expiry>
    <token>4eeb155fc20fa07a7c01d82aa68f9d22cab6257c57b6694d722cfdc8b95dce4d2f8f44e0a5c9aab14065e1f2016fc95eb0185cb62689b78e8e06346429c1aedc</token>
</root>

The steps to process the authorize response for the 3DS 2.0 authentication are as follows:

7.2.5 Authorization Failure

The following is an example of response received for a failed authorization:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <status code="2010" sub-code="2010205"> Unable to authorize</status>
</root>

The parameters are listed and defined in the table below.

8. Transaction Call Back Request

The transaction status along with additional transaction information is posted to the callback URL configured for a merchant. There are two callback requests posted to the URL where the status codes indicate the following:

The following parameters are sent in the callback:

Note: For details about transaction call back, refer to the Callback Request to Merchant from Velocity Integration Guide.

9. Error Scenarios and Status Codes

The error scenarios and corresponding status codes are listed in the tables below.

Status Codes

Note: For details about status codes, refer to the CPD Velocity API Integration Guide- Status Codes.