Google Pay Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose

This document is written for merchants who want to enable customers to use Google Pay to pay for in-app purchases. This document provides an overview of integrating the Google API and describes how to request the Cybersource API to process an authorization.

This document describes the Google Pay service and the Cybersource API. You must request the Google API to receive the customer’s encrypted payment data before requesting the Cybersource API to process the transaction.

Conventions

The following special statements are used in this document:

An Important
statement contains information essential to successfully completing a task or learning a concept.

Customer Support

For support information about any service, visit the Support Center:

http://support.visaacceptance.com

Recent Revisions to This Document

24.03

This revision contains only editorial changes and no technical updates.

24.02

Corrected URL to setting up Sandbox Account.

24.01

Fixed typo in Javascript sample. See Formatting Payment Blobs.

23.02

Updated the Google Pay authorizations required fields list. See Required Fields for a Google Pay Authorization.

Added follow-on transaction support to the Google Pay authorization section. See Google Pay Authorizations.

23.01

This revision contains only editorial changes and no technical updates.

Introduction

You can use the Cybersource platform to process and manage Google Pay transactions.

Google Pay Overview

Google Pay is a simple, secure in-app mobile and Web payment solution. You can choose Cybersource to process Google Pay transactions through all e-commerce channels.

You can simplify your payment processing by allowing Cybersource to decrypt the payment data for you during processing.

This method integrates simply and enables you to process transactions without seeing the payment network token and transaction data.

Using the Google API, request the customer’s encrypted payment data.

Using the Cybersource API, construct and submit the authorization request, and include the encrypted payment data from the Google Pay callback.

Cybersource decrypts the encrypted payment data to create the payment network token and processes the authorization request.

Payment Network Tokens

Authorizations with payment network tokens enable you to securely request a payment transaction with a payment network token instead of a customer’s primary account number (PAN).

The payment network token is included in the customer’s encrypted payment data, which is returned by the payment processor.

For information about authorizations with payment network tokens, see the Authorizations with Payment Network Tokens Guide.

Prerequisite Requirements

Before using Google Pay, you must have:

A Cybersource merchant evaluation account.

To register, go to: https://developer.cybersource.com/hello-world/sandbox.html

A merchant evaluation account with a supported processor. See Supported Processors.

A Google developer account.

Google Pay APIs embedded into your application or website. For details about integrating Google Pay, see the Google Pay API documentation.

Supported Processors

Processor	Card Types	Optional Features
`GPN`	American Express Mastercard Visa	None

How Google Pay Works

The following figure describes the Google Pay workflow:

The customer chooses the Google Pay button. Using the Google API, your system initiates the Google Pay request identifying Cybersource as your payment gateway, passing your Cybersource merchant ID as the gateway merchant ID.

The customer confirms the payment. The Google API contacts Google Pay services to retrieve the consumer’s payment parameters.

If the customer’s selected payment credentials are tokenized, or you are tokenizing new payment credentials, the Google Pay service contacts the appropriate payment network to retrieve the appropriate cryptogram.

The payment network returns the appropriate token and cryptogram to the Google Pay service.

Google creates encrypted payment data using the gateway-specific key that is supplied in the Wallet request and includes it in the Google API response.

The Google Pay callback returns the encrypted payment data.

Your system prepares the Google Pay response information for submission to the Cybersource service.

Cybersource sends the authorization request to the acquirer.

The acquirer processes the request from Cybersource and creates the payment network authorization request.

The payment network processes the request from the acquirer and creates the issuer authorization request.

The issuer processes the request from the payment network. The issuer looks up the payment information and returns an approved or declined authorization message to the payment network.

The payment network returns the authorization response to the acquirer.

The acquirer returns the authorization response to Cybersource.

Cybersource returns the authorization response to your system.

Your system returns the authorization response to the payment application.

The payment application displays the confirmation or decline message to the customer.

The acquirer submits the settlement request to the issuer for funds.

The issuer supplies the funds to the acquirer for the authorized transactions.

Additional Services

These additional services can be used with Google Pay.

Follow-on Services

After the authorization is requested, you can request follow-on services to complete the transaction. For more information on these services, see Follow-on Services.

Authorized Reversal: An authorized reversal is a follow-on service that uses the request ID returned from the previous authorization. An authorization reversal releases the hold that the authorization placed on the customer’s credit card funds. Use this service to reverse an unnecessary or undesired authorization.
Capture: A capture is a follow-on service that uses the request ID returned from the previous authorization. The request ID links the capture to the authorization. This service transfers funds from the customer’s account to your bank and usually takes two to four days to complete.
Sale: A sale is a bundled authorization and capture. Request the authorization and capture services at the same time. Cybersource processes the capture immediately.

Follow-on Transactions

After the payment transaction is complete, additional follow-on transactions can be made as Merchant-Initiated Transactions (MITs).

For more information on how to process MITs, see

Merchant-Initiated Transactions

.

MITs include:

Delayed Authorizations

Incremental Transactions

Installment Payments

No-Show Transactions

Reauthorizations

Recurring Transactions

Resubmissions

Unscheduled Transactions

Formatting Encrypted Payment Data

This section shows you how to format encrypted payment data using these procedures:

Configuring Google Pay

Formatting Payment Blobs

Configuring Google Pay

You must provide your Cybersource merchant ID to Google in order to ensure proper encryption of the Google Pay payload and authenticity of the request.

For a Google Pay tutorial, see Google Pay for Payments.

Set the gateway and gateway merchant ID to the appropriate indicators. The following code examples show how to configure the

PaymentMethodTokenizationParameters

object using Cybersource as the gateway.

Example: Java Code

.setPaymentMethodTokenizationType(WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
     .addParameter("gateway", "")
     .addParameter("gatewayMerchantId", "[yourCybersourceMID]")

Example: JavaScript Code

tokenizationType: 'PAYMENT_GATEWAY',
     parameters: {
     gateway: 'cybersource',
          gatewayMerchantId: '[yourCybersourceMID]'

Formatting Payment Blobs

This section is only applicable if you are using the Cybersource decryption method.

To prepare the Google Pay payload for submission to Cybersource, you must extract the token data element from the Google Pay payload and encode the token data element using Base64.

These samples can be used to Base64-encode payment responses:

JavaScript

let token = paymentData.paymentMethodData.tokenizationData.token;
console.log(token);
var enc=window.btoa(token);

Android with Java

This sample uses the Android Studio Base64 utility.

public static <outputString> encodeToString (byte[] <inputToken>, int DEFAULT)

Apple iPhone with Swift 3

This sample requires the Foundation utility.

extension String {
     func base64Encoded() -> <outputString>
          if let data = self.dat(using:.utf8) {
               return data.base64EncodedString()
          }
          return nil
}

Examples of Google Pay Responses

Decrypted Google Pay Response

{"signature":"MEUCIQDhTxhHqwY8pXB9hpYxaSK5jFgsqpG2E1rX77QXssK8tAIgUBvYYAI/
bnBS8T/Tfxnm2AF981Mv5y0pHyGexM5dMJk\u003d","protocolVersion":"ECv1","
signedMessage":"{\"encryptedMessage\":\"
odyUGGA7B+blletYcJbS43AQUFQJpWEFCN4UuUExQ5LX0\/
XcLwKElXcB95nMnmPO9lM2KGp13FYsL768ccCzAjBGLYF+
fugcJTcvkrUhcNSyXr7hwf12BEsrweqJM6I7Vs5lfrPAukRJeLDQG4FxmTLW49QyP8vIZC+
tz2c+Z3zozzI5oB9jE8fA2dolFa13Cu6gXqdKH\/
IHRh7UniLUuTy+0G5FQV2pwST2uBSNNkZhb8WYJDHbxBjz0UebVP+
ObmT5cc8AKU5dgHRdfr4GKpEZ4EBzB90 BPxLqYHpopriJ6lbFgFVsQQ6\/
8HBqQ7ImIMH5y7G8p8qAFkWnB78ZcL0Fh5BjXojkxGoFp2gjAsrhhttHAFbe3WQBuPkwJu09\/
6\/MyJpCSrpMHFouF\/dj0SYjQ+xI097lCHZec7jQrAhISLWZ9DZkuMvGKPWpu0CKn2XqTXQ=\
",\"ephemeralPublicKey\":\
"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnn4yjy0N6xlXO8\/8j7\/
4jvmLJCYAqgXLwP1FhjuTgIM9oCtPijZfI9so2QEOs2ZnVp3D0dl3JYIDVe+396KkAQ==\
",\"tag\":\"DRp cc+YQ33RNgsTcxztnJbMJnirbU5DW3dStjfhFiwc=\"}"}

Base64-Encoded Google Pay Response

eyJzaWduYXR1cmUiOiJNRVVDSVFEaFR4aEhxd1k4cFhCOWhwWXhhU0s1akZnc3FwRzJ
FMXJYNzdRWHNzSzh0QUlnVUJ2WVlBSS9ibkJTOFQvVGZ4bm0yQUY5ODFNdjV5MHBIeU
dleE01ZE1Ka1x1MDAzZCIsInByb3RvY29sVmVyc2lvbiI6IkVDdjEiLCJzaWduZWRNZ
XNzYWdlIjoie1wiZW5jcnlwdGVkTWVzc2FnZVwiOlwib2R5VUdHQTdCK2JsbGV0WWNK
YlM0M0FRVUZRSnBXRUZDTjRVdVVFeFE1TFgwXC9YY0x3S0VsWGNCOTVuTW5tUE85bE0
yS0dwMTNGWXNMNzY4Y2NDekFqQkdMWUYrZnVnY0pUY3ZrclVoY05TeVhyN2h3ZjEyQk
VzcndlcUpNNkk3VnM1bGZyUEF1a1JKZUxEUUc0RnhtVExXNDlReVA4dklaQyt0ejJjK
1ozem96ekk1b0I5akU4ZkEyZG9sRmExM0N1NmdYcWRLSFwvSUhSaDdVbmlMVXVUeSsw
RzVGUVYycHdTVDJ1QlNOTmtaaGI4V1lKREhieEJqejBVZWJWUCtPYm1UNWNjOEFLVTV
kZ0hSZGZyNEdLcEVaNEVCekI5MEJQeExxWUhwb3ByaUo2bGJGZ0ZWc1FRNlwvOEhCcV
E3SW1JTUg1eTdHOHA4cUFGa1duQjc4WmNMMEZoNUJqWG9qa3hHb0ZwMmdqQXNyaGh0d
EhBRmJlM1dRQnVQa3dKdTA5XC82XC9NeUpwQ1NycE1IRm91RlwvZGowU1lqUSt4STA5
N2xDSFplYzdqUXJBaElTTFdaOURaa3VNdkdLUFdwdTBDS24yWHFUWFE9XCIsXCJlcGh
lbWVyYWxQdWJsaWNLZXlcIjpcIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUW
NEUWdBRW5uNHlqeTBONnhsWE84XC84ajdcLzRqdm1MSkNZQXFnWEx3UDFGaGp1VGdJT
TlvQ3RQaWpaZkk5c28yUUVPczJablZwM0QwZGwzSllJRFZlKzM5NktrQVE9PVwiLFwi
dGFnXCI6XCJEUnBjYytZUTMzUk5nc1RjeHp0bkpiTUpuaXJiVTVEVzNkU3RqZmhGaXd
jPVwifSJ9

Google Pay Authorizations

This section shows you how to make a successful authorization request.

After you send the request, check the response messages to make sure that the request was successful.

A value of

ACCEPT

for the

decision

field indicates success.

For information about response codes, see

Reason Codes for the Simple Order API

.

Follow-on Transactions

After the initial transaction is complete, additional follow-on transactions can be made as Merchant-Initiated Transactions (MITs).

For more information on how to process MITs, see

Merchant-Initiated Transactions

.

Endpoint

Set the

ccAuthService_run

field to

true

.

Send the request to

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

.

Required Fields for a Google Pay Authorization

Include these required fields to request a successful authorization.

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
ccAuthService_run: Set this field value to
true
.
encryptedPayment_data: Set this field value to the string value generated from the full wallet response.
merchantID
merchantReferenceCode
paymentSolution: Set this field value to
012
.
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Related Information

API Field Reference for the Simple Order API

Simple Order Example: Google Pay Authorization

Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.121">
     <merchantID>demomerchant</merchantID>
     <merchantReferenceCode>demorefnum</merchantReferenceCode> 
     <billTo>
          <firstName>James</firstName>
          <lastName>Smith</lastName>
          <street1>1295 Charleston Road</street1> 
          <city>Test City</city>
          <state>CA</state>
          <postalCode>99999</postalCode>
          <country>US</country>
          <email>demo@example.com</email>
     </billTo>
     <purchaseTotals>
          <currency>USD</currency>
          <grandTotalAmount>5.00</grandTotalAmount>
     </purchaseTotals>
     <encryptedPayment>
          <data>ABCDEFabcdefABCDEFabcdef0987654321234567</data> 
     </encryptedPayment>
     <ccAuthService run="true"/>
    <paymentSolution>012</paymentSolution>
</requestMessage>

Response for a Successful Request

<replyMessage>
     <merchantReferenceCode>demorefnum</merchantReferenceCode>
     <requestID>4465840340765000001541</requestID>
     <decision>ACCEPT</decision>
     <reasonCode>100</reasonCode>
     <requestToken>Ahj/7wSR5C/4Icd2fdAKakGLadfg5535r/ghx3Z90AoBj3u</requestToken> 
     <purchaseTotals>
          <currency>USD</currency>
     </purchaseTotals>
     <ccAuthReply>
          <reasonCode>100</reasonCode>
          <amount>5.00</amount>
          <authorizationCode>888888</authorizationCode>
          <avsCode>X</avsCode>
          <avsCodeRaw>I1</avsCodeRaw>
          <authorizedDateTime>2015-11-03T20:53:54Z</authorizedDateTime> 
          <processorResponse>100</processorResponse>
          <reconciliationID>11267051CGJSMQDC</reconciliationID>
     </ccAuthReply> 
     <token>
          <prefix>294672</prefix>
          <suffix>4397</suffix>
          <expirationMonth>08</expirationMonth>
          <expirationYear>2021</expirationYear>
     </token>
</replyMessage>

Follow-on Services

This section provides information about and procedures for requesting these follow-on services:

Authorization Reversal:
A follow-on service that uses the request ID returned from the previous authorization. An authorization reversal releases the hold that the authorization placed on the customer’s credit card funds. Use this service to reverse an unnecessary or undesired authorization.

Capture:
A follow-on service that uses the request ID returned from the previous authorization. The request ID links the capture to the authorization. This service transfers funds from the customer’s account to your bank and usually takes two to four days to complete.

Sale:
A sale is a bundled authorization and capture. Request the authorization and capture services at the same time. Cybersource processes the capture immediately.

Captures

This section provides the information you need in order to capture an authorized transaction.

Endpoint

Set the

ccCaptureService_run

field to

true

.

Send the request to

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

.

Required Fields for Capturing an Authorization

Use these required fields for capturing an authorization.

ccCaptureService_authRequestID
ccCaptureService_run
merchantID
merchantReferenceCode: Set the value to
merchant_ref_number
value used in corresponding authorization request.
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Simple Order Example: Capturing an Authorization

Request

ccCaptureService_authRequestID=6629978499572480812782
ccCaptureService_run=true
merchantID=npr_paymentech
merchantReferenceCode=TC42703-1
purchaseTotals_grandTotalAmount=100.00

Response to a Successful Request

ccCaptureReply_amount=100.00
ccCaptureReply_requestDateTime=2022-09-12T173947Z
decision=ACCEPT
merchantReferenceCode=TC42703-1
purchaseTotals_currency=USD
requestID=6630043878211258349460

Sales

This section provides the information you need in order to process a sale transactions.

A sale combines an authorization and a capture into a single transaction.

Endpoint

Set the

ccAuthService_run

field to

true

, and the

ccCaptureService_run

field to

true

.

Send the request to

https://ics2ws.ic3.com/commerce/1.x/transactionProcessor

.

Required Fields for Processing a Sale

Use these required fields for processing a sale.

billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_cardType
card_expirationMonth
card_expirationYear
ccAuthService_commerceIndicator
ccAuthService_run: Set the value to
true
.
ccCaptureService_run: Set the value to
true
.
merchantID
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Related Information

API field reference guide for the Simple Order API

Simple Order Example: Processing a Sale

Request

ccAuthService_run=true
ccCaptureService_run=true
merchantID=Napa Valley Vacations
merchantReferenceCode=482046C3A7E94F5
billTo_firstName=John
billTo_lastName=Doe
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_postalCode=94043
billTo_country=US
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD
card_expirationMonth=12
card_expirationYear=2031
card_accountNumber=4111111111111111
card_cardType=001

Response to a Successful Request

requestID=0305782650000167905080
decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5
purchaseTotals_currency=USD
ccAuthReply_reconciliationID=ABCDE12345FGHIJ67890
ccAuthReply_cardCategory=F^
ccAuthReply_cardGroup=0
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_accountBalance=50.05
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_processorResponse=A
ccAuthReply_paymentNetworkTransactionID=3312345
ccCaptureReply_amount=49.95
ccCaptureReply_reasonCode=100
ccCaptureReply_reconciliationID=1094820975023470

Follow-on Transactions

After the payment transaction is complete, additional follow-on transactions can be made as Merchant-Initiated Transactions (MITs).

For more information on how to process MITs, see

Merchant-Initiated Transactions

.

MITs include:

Delayed Authorizations

Incremental Transactions

Installment Payments

No-Show Transactions

Reauthorizations

Recurring Transactions

Resubmissions

Unscheduled Transactions

Google Pay Developer Guide

Audience and Purpose

Conventions

Related Documentation

Customer Support

Recent Revisions to This Document

24.03

24.02

24.01

23.02

23.01

Introduction

Google Pay Overview

Payment Network Tokens

Prerequisite Requirements

Supported Processors

How Google Pay Works

Additional Services

Follow-on Services

Follow-on Transactions

Formatting Encrypted Payment Data

Configuring Google Pay

Formatting Payment Blobs

Examples of Google Pay Responses

Google Pay Authorizations

Follow-on Transactions

Endpoint

Required Fields for a Google Pay Authorization

Related Information

Simple Order Example: Google Pay Authorization

Follow-on Services

Captures

Endpoint

Required Fields for Capturing an Authorization

Simple Order Example: Capturing an Authorization

Sales

Endpoint

Required Fields for Processing a Sale

Related Information

Simple Order Example: Processing a Sale

Follow-on Transactions