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:

IMPORTANT

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.

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.

The Cybersource REST API Client installed on your system.

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
`BNP Paribas France`	Cartes Bancaires Mastercard Visa	Recurring Payments

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

IMPORTANT

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 200-level HTTP response code indicates success.

For information about response codes, see

Transaction Response Codes

.

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

Production:

POST https://api.cybersource.com/pts/v2/payments

Test:

POST https://apitest.cybersource.com/pts/v2/payments

Required Fields for a Google Pay Authorization

Include these required fields to request a successful authorization.

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.fluidData.value: Set to the string value generated from the full wallet response.
processingInformation.paymentSolution: Set to
012
.

Related Information

API Field Reference for the REST API

REST Example: Google Pay Authorization

Request

{
  "processingInformation": {
    "paymentSolution": "012"
  },
  "paymentInformation": {
    "fluidData": {
      "value": "ABCDEFabcdefABCDEFabcdef0987654321234567"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "102.21",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Happy Street",
      "locality": "Ann Arbor",
      "administrativeArea": "MI",
      "postalCode": "48104-2201",
      "country": "US",
      "email": "test@cybs.com"
    }
  }
}

Response for a Successful Request

{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/6805343125426255503955/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/6805343125426255503955"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/6805343125426255503955/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "6805343125426255503955",
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "102.21",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "type": "001"
    },
    "card": {
      "type": "001"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "111111"
  },
  "processorInformation": {
    "approvalCode": "888888",
    "networkTransactionId": "123456789619999",
    "transactionId": "123456789619999",
    "responseCode": "100",
    "avs": {
      "code": "X",
      "codeRaw": "I1"
    }
  },
  "reconciliationId": "65301815QFTXZAN6",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2023-04-03T15:05:12Z"
}

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

Production:

POST https://api.cybersource.com/pts/v2/payments/{id}
/captures

Test:

POST https://apitest.cybersource.com/pts/v2/payments/{id}
/captures

The

{id}

is the transaction ID returned in the authorization response.

Required Fields for Capturing an Authorization

Use these required fields for capturing an authorization.

clientReferenceInformation.code: This field value maps from the original authorization, sale, or credit transaction.
clientReferenceInformation.partner.thirdPartyCertificationNumber: Cybersource provides the value for this field.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

REST Example: Capturing an Authorization

Request

{
    "clientReferenceInformation": {
        "code": "ABC123",
        "partner": {
            "thirdPartyCertificationNumber": "123456789012"
        }
    },
    "orderInformation": {
        "amountDetails": {
            "totalAmount": "100.00",
            "currency": "EUR"
    }
}

Response to a Successful Request

{
    "_links": {
        "void": {
            "method": "POST",
            "href": "/pts/v2/captures/6662994431376681303954/voids"
        },
        "self": {
            "method": "GET",
            "href": "/pts/v2/captures/6662994431376681303954"
        }
    },
    "clientReferenceInformation": {
        "code": "1666299443215"
    },
    "id": "6662994431376681303954",
    "orderInformation": {
        "amountDetails": {
            "totalAmount": "100.00",
            "currency": "EUR"
        }
    },
    "reconciliationId": "66535942B9CGT52U",
    "status": "PENDING",
    "submitTimeUtc": "2022-10-20T20:57:23Z"
}

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

Production:

POST https://api.cybersource.com/pts/v2/payments

Test:

POST https://apitest.cybersource.com/pts/v2/payments

Required Fields for Processing a Sale

Use these required fields for processing a sale.

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
processingInformation.capture: Set the value to
true
.

Related Information

API field reference guide for the REST API

REST Example: Processing a Sale

Request

{
  "processingInformation": {
    "capture": true
  },
  "orderInformation" : {
    "billTo" : {
    "country" : "US",
    "lastName" : "VDP",
    "address1" : "201 S. Division St.",
    "postalCode" : "48104-2201",
    "locality" : "Ann Arbor",
    "administrativeArea" : "MI",
    "firstName" : "RTS",
    "email" : "test@cybs.com"
  },
    "amountDetails" : {
      "totalAmount" : "100.00",
      "currency" : "usd"
     }
   },
  "paymentInformation" : {
    "card" : {
      "expirationYear" : "2031",
      "number" : "4111111111111111",
      "expirationMonth" : "12",
      "type" : "001
    }
  }
}

Response to a Successful Request

Most processors do not return all of the fields that are shown in this example.

{
  "_links" : {
    "void" : {
      "method" : "POST",
      "href" : "/pts/v2/payments/6485004068966546103093/voids"
    },
    "self" : {
      "method" : "GET",
      "href" : "/pts/v2/payments/6485004068966546103093"
    }
  },
  "clientReferenceInformation" : {
    "code" : "RTS-Auth"
  },
  "id" : "6485004068966546103093",
  "orderInformation" : {
    "amountDetails" : {
      "totalAmount" : "100.00",
      "authorizedAmount" : "100.00",
      "currency" : "usd"
    }
  },
  "paymentAccountInformation" : {
    "card" : {
      "type" : "001"
    }
  },
  "paymentInformation" : {
    "tokenizedCard" : {
      "type" : "001"
    },
    "card" : {
      "type" : "001"
    }
  },
  "processorInformation" : {
    "systemTraceAuditNumber" : "841109",
    "approvalCode" : "831000",
    "merchantAdvice" : {
      "code" : "01",
      "codeRaw" : "M001"
    },
    "responseDetails" : "ABC",
    "networkTransactionId" : "016153570198200",
    "retrievalReferenceNumber" : "208720841109",
    "consumerAuthenticationResponse" : {
      "code" : "2",
      "codeRaw" : "2"
    },
    "transactionId" : "016153570198200",
    "responseCode" : "00",
    "avs" : {
      "code" : "Y",
      "codeRaw" : "Y"
    }
  },
  "reconciliationId" : "6485004068966546103093",
  "status" : "AUTHORIZED",
  "submitTimeUtc" : "2022-03-28T20:46:47Z"
}

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

REST Example: Google Pay Authorization

Follow-on Services

Captures

Endpoint

Required Fields for Capturing an Authorization

REST Example: Capturing an Authorization

Sales

Endpoint

Required Fields for Processing a Sale

Related Information

REST Example: Processing a Sale

Follow-on Transactions