Google Pay API Integration Guide-V1.05

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.

TermsDescription
MerchantAny business who sells goods or services and accepts payments from customers
CustomersThose who want to buy goods and services from merchants
PSPPayment Service Provider
CPDCellPoint Digital
MSISDNMobile Station International Subscriber Directory Number
MACMessage Authentication Code
POPPayment Orchestration Platform
HPPHosted Payment Page
B2BBusiness to Business
B2CBusiness to Consumer

4. Integration Prerequisites

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

OwnerOwner ResponsibilitiesDetails
CellPoint DigitalClient onboarding and configuration and merchant onboarding with Google
  • Client setup - account and clientid
  • API Authorization Credentials
  • Configure redirect URLs for successful and failed transactions
  • API version
  • Supported Country-id list
  • Gateway ID: cellpointmobile
Merchant / GoogleProduction validation
by Google
  • Merchant to contact Google for validating - web integration
  • merchantid as provided by Google once production review is completed for merchant app or web integration
  • Request production access

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:

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:

End point[ VELOCITY URL]/mpoint/initialize-payment
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

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.

ParameterTypeMandatoryDescription
Parameters for Initializing Payments
client-idIntegerYesThe unique ID configured for a merchant on the Velocity POP.
productidIntegerNoThe product of a merchant. For example, ticket and insurance.
Currency-idIntegerNoThe currency configured for a country. It depends on the configuration available with Velocity.
accountIntegerNoThe unique ID associated with a payment transaction. It is optional. If you omit this parameter, the payment transaction is associated with the default sub-account.
order-noStringYesThe order ID that a merchant generates. It is an alphanumeric string.
Note: Some Payment Providers have strict guidelines for the order-no. The recommended pattern is [a-zA-Z0-9._-]
accept-urlStringNoThe URL where Velocity directs a customer after successfully completing a payment transaction.
Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment completion.
cancel-urlStringNoThe absolute URL where Velocity directs customers if they cancel a payment transaction midway.
Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment cancellation.
decline-urlStringNoThe absolute URL where Velocity directs customers if the payment transaction fails. The URL is used for redirecting back to the HPP or the merchant’s page after a payment failure.
auth-urlStringNoThe URL which is used for single sign-on (SSO) authentication if provided by an external system.
session-idIntegerNoThe ID of a session used for multiple payment transactions during one payment flow. For example, a split payment or a retry of a failed payment transaction.
product-typeStringNoThe product type used to select the payment methods to be displayed or acquirer to be selected. The typical values include TICKET and INSURANCE.
type-idIntegerYesThe type of a transaction. For example, 40 indicates a mobile application purchase and 30 indicates a web purchase.
amountIntegerYesThe total amount that a customer is charged for a payment transaction in a country’s smallest currency. For example, the smallest currency of USD is a penny. If the transaction amount is $120.30, then the amount field contains the value 12030.
country-idIntegerYesThe CPD-specific country code, which is available on request only.
callback-urlStringNoThe absolute URL to the back office of a merchant where Velocity POP sends the payment status.
Velocity uses the default URL if merchants do not provide this parameter.
auth-tokenStringNoA unique token sent to the specified auth-url to authenticate customer when they pay with a stored card and use single sign-on.
HMACStringNoThe Message Authentication Code. It is calculated by creating a sha-512 hash comprising the following input fields in the listed order:
  • clientid
  • account
  • orderid
  • callback-url
  • amount
  • auth-url
  • customer-ref
  • auth-token
  • email
  • mobile
  • [salt]

Note: CPD provides the salt value to merchants.
MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.
ordersObjectNoThe order details which contain event, location, date or time, ticket type, cost, booking fee, quantity, and total price data.
Note: This parameter is used for airline data only.
Merchant Information Parameters
platformStringYesThe platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
sdk-versionIntegerYesThe software development kit (SDK) version used.
versionStringYesThe version of the application programming interface (API) or application that sends the request.
languageStringYesThe language that Velocity uses as default when translating the payment pages.
Velocity uses a default language set by a merchant if this parameter is omitted.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
mobileIntegerYesThe MSISDN of a customer without International Dialling Code.
Note: Mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.
country-idIntegerNoThe CPD-specific country code, which is provided on request.
operator-idIntegerNoThe ID of a customer’s mobile network operator. CPD recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.
emailStringNoThe email address of a customer. If your customer provides this parameter, the Email input field on the Send Email Receipt page is automatically populated with this value.
Note: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.
customer-refStringNoThe unique reference ID given by a merchant for a customer. Velocity uses this token to identify a user. The customer reference is included in the request to a specified auth-url to identify customers when they:
  • Pay with a stored card
  • Use single sign-on.
Note: Customer-ref can be mandatory or optional, based on the requirement of a merchant or a PSP.

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:

FieldTypeDescription
transaction/@idxs:positiveIntegerA unique transaction ID generated for the initialize payment request. This identifies a transaction within CPD systems.
cards/card/@type-idxs:positiveIntegerA unique ID that identifies the payment methods configured.
type-id = 41 indicates the internal id defined for Google Pay™ payment method.

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.

ParameterTypeMandatoryDescription
versionIntegerYesThe version of the API or application that sends the request.
Client-config Parameters
accountIntegerNoThe number for the sub-account with which the payment transaction is associated. The Account ID is an integer greater than 100000 and account number is an integer smaller than 1000.
The payment transaction is associated with the default sub-account if you do not provide this parameter. CPD recommends you provide this parameter.
auto-captureBooleanYesShows if you have enabled auto-capture
modeIntegerNoA parameter used in the SDK to switch between production and staging environment.
store-cardIntegerYesIt defines the type of configuration merchants have done to store cards.
IntegerMeaning
0Cards are not stored
1INVALID!
2Stored cards are available for specific accounts only.
3Use stored cards only and make them available for specific accounts only. The e-money based prepaid account is unavailable.
4Stored cards are available for all accounts.

Note: Velocity must be hosted by a Master Merchant.

nameStringNoThe name a merchant gives to a card as configured in Velocity.
callback-urlStringYesThe absolute URL to a merchant’s back office where Velocity sends the payment status.
Note: If you do not provide this parameter, Velocity uses the default URL. This parameter is not applicable for most of the API-based integrations.
accept-urlStringYesThe absolute URL where Velocity directs a customer after successfully completing a payment transaction.
Note: If you do not provide this parameter, Velocity uses the default URL. This parameter is not applicable for most of the API-based integrations.
Transaction Parameters
auto-captureBooleanYesShows if you have enabled auto-capture.
eua-idIntegerNoA parameter which identifies if the API to be called is for saving account or saving card.
idIntegerYesThe unique ID of a merchant for Velocity platform.
languageStringYesThe language that Velocity uses as default when translating the payment pages.
Velocity uses a default language set by a merchant if this parameter is omitted.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
modeIntegerNoA parameter used in SDK to switch between production and staging environment.
order-noStringYesThe order ID that a merchant generates for a customer. It is an alphanumeric string.
Note: Some payment providers have strict guidelines for the order-no. The recommended pattern is "[a-zA-Z0-9._-]
type-idIntegerYesThe type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
country-idIntegerYesThe CPD-specific country code, provided to merchants on request.
currencyStringYesThe format of currency used for a transaction.
formatStringYesThe format in which price is presented.
mobile country-idIntegerYesThe CPD-specific country code, which is made available to merchants on request.
operator-idIntegerYesThe ID of a customer’s mobile network operator. CPD recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
Session Parameters
idIntegerYesThe unique ID of a merchant for Velocity platform
total-amountIntegerYesThe total amount that a customer pays for a transaction.
alpha2codeStringYesThe three-letter alphabetic code for a currency.
alpha3codeIntegerYesThe two-letter numeric code for a country.
codeIntegerYesThe CPD currency code for a country.
country-idIntegerYesThe CPD-specific country code, provided to merchants on request.
currencyStringYesThe format of currency used for a transaction.
currency-idIntegerYesThe currency code of a currency.
formatStringYesThe format in which price is presented.
symbolYesA symbol used to indicate the currency of a country.
Card Parameters
cvc-lengthIntegerYesThe length of the card verification code (CVC) number on a card.
cvcmandatoryBooleanYesIndicates if the CVC is mandatory for a transaction. The value can be true or false. It is used for a wallet transaction.
dccBooleanYesIndicates if currency conversion is available. The value can be true or false.
enabledBooleanYesShows if the card was enabled.
installmentStringNoThis is no longer used in a transaction.
min-lengthIntegerYesThe minimum length of a card number.
max-lengthIntegerYesThe maximum length of a card number.
payment-typeStringYesThe type of payment. For example, card, wallet, or APM.
preferredBooleanYesShows if a customer has set a card as a preferred one.
processor-typeStringYesThe type of processor used to process payment.
psp-idIntegerYesThe ID of a PSP used for a card.
state-idIntegerYesThe state of a card. For example, enabled or disabled by PSP.
type-idIntegerYesThe type of application used for a transaction. For example, 40 indicates a mobile app purchase and 30 indicates a web purchase.
nameStringYesThe name of a card type. For example, wallet or PSP.

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:

  1. After you receive the response for /mpoint/initialize-payment API, check if it contains the following for Google Pay™ support:
    1. The <card> object with id = 41, in the <wallets> array section
    2. You will get the head tag in the Google Pay™ response use all the content(script) from that tag and add that script your payment page.
    3. The <body> tag contains a Google Pay™ script as well as additional scripts which must be loaded when the page loads.
    4. A JS snippet in <script> element. Make this content available in the resulting web page.

      Note: The JS snippet helps to display the Google Pay™ Button and eventually trigger Google Pay™ payment.

  2. To display the Google Pay™ logo, add the following HTML div node with attribute wallet-id=”41”
    at an appropriate position in the resulting HTML.

<div wallet-id="41">
    <div />
</div>
  1. Add both the body and the head script received in the card element to the head of the HTML page.
  2. After adding the script to the head of HTML page, handle a callback method after the Google Pay™ UI interaction is complete. This callback method captures the card token generated by Google Pay™.

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:

End point[Velocity URL]/mpoint/ authorize-payment
Formattext/xml
AuthenticationHTTP basic access authentication

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.

ParameterTypeMandatoryDescription
Authorize-payment Parameters
accountIntegerNoThe number for a sub-account with which a payment transaction is associated. The account ID is an integer greater than 100000 and account number is an integer smaller than 1000.
The payment transaction is associated with the default
sub-account if merchants do not provide this parameter.
client-idIntegerYesThe unique ID of a merchant.
Transaction Parameters
idIntegerYesThe ID of the transaction.
type-idIntegerYesA unique transaction identification number.
card networkEnumNoA list to identify the card network from which the token was obtained. It takes one of the following values:
  • amex
  • dankort
  • dinersclub
  • jcb
  • maestro
  • mastercard
  • visa
  • visaelectron
  • discover
Card Parameters
currency-idIntegerYesThe country currency code of a currency.
country-idIntegerYesThe CPD-specific country code, which is made available to merchants on request.
tokenStringNoThe base64 encoded cryptogram for a third-party wallet such as Google Pay™.
hmacStringNoThe Message Authentication Code (MAC). It is calculated by creating a sha-512 hash comprising the following input fields in the listed order:
  • clientid
  • account
  • orderid
  • callback-url
  • amount
  • auth-url
  • customer-ref
  • auth-token
  • email
  • mobile
  • [salt]

Note:CPD provides the salt value to merchants.
MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.
Address Parameters
country-idIntegerYesThe CPD-specific country code, which is made available to merchants on request.
full-nameStringYesThe full name of a customer.
streetStringYesThe full address of a customer with street name and street number.
postal-codeStringYesThe postal code of a customer.
cityStringYesThe city in which a customer resides.
stateStringNoThe state in which a customer resides. Customers enter this parameter only if their country of residence is divided onto states
country-idIntegerYesThe CPD-specific country code, which is made available to merchants on request.
Client Information Parameters
languageStringYesThe language that Velocity uses as default when translating the payment pages.
Note: Velocity language codes are based upon the ISO- 639-1 standard.
Refer https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
versionStringYesThe version of an API or application that sends the request.
platformStringYesThe platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
mobile operator-idIntegerYesThe ID of a customer’s mobile network operator. CPD recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.
emailStringNoThe email address of a customer. If a customer provides this parameter, the Email input field on the Send Email Receipt page is automatically populated with this value.

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.

ParameterTypeMandatoryDescription
StatusStringYesDescribes the status code.
CodeIntegerYesStatus code for the authorizing processes.

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:

  1. Extract the content of tags <parsed-challenge>.
  2. Do a form post of all the fields hidden-fields to the url in the action tag using browser.
  3. Follow the instruction to complete authentication.
  4. After the authentication is complete, it is redirected to your Accept or Decline URL.
  5. The Callback notification with authorization status is sent to your Callback URL.

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:

  1. Extract the content of tags <web-method>.
  2. HTML decode the web-method content to get the HTML.
  3. Load the HTML on the browser and follow the instructions to complete the authentication.
  4. After the authentication is complete, it is redirected to your Accept or Decline URL.
  5. The Callback notification with authorization status is sent to your Callback URL.

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.

ParameterTypeRequiredDescription
statusStringYesDescribes the status code.
codeIntegerYesA status code for the authorizing processes.
sub-codeIntegerYesThe granular-level status code which shows the reason for a failed authorization.

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:

CodeDescription
Invalid amountFor example, 0.01.
Missing mandatory request fieldFor example, element 'card': The attribute 'type-id' is required but missing.

The following parameters are sent in the callback:

FieldMandatoryDescription
mpoint-idYesThis is the transaction/@id generated during initialize step.
session-idYesInternal session ID.
orderidYesThis is the transaction/@order-no in the initialize request, like PNR.
statusYesTransaction status code indicates successful or failure.
mobileYesIf present in the transaction requests, same will be returned.
amountYesTransaction amount.
FeeYesDefault is 0.
currencyYesTransaction code.
languageYesIf present in the transaction requests, same will be returned.
operatorYesIf present in the transaction requests, same will be returned.

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.

ScenarioStatus codeDescription
Invalid amount51For example, 0.01.
Missing mandatory request field400For example, element 'card': The attribute 'type-id' is required but missing.

Status Codes

CodeDescription
2000 and 2001Transaction successful.
2010Transaction failed.
4021Session failed; maximum attempts exceeded.
4030Session successfully completed.
4031Session partially completed.
4021Session failed or declined.

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