Google Pay Integration Guide

1. Introduction

Google Pay™ is the fast, simple way that allows you to make card payments without entering card details for each payment. The card data is safely stored by Google. This payment method is available for all devices (mobile phones and computers), regardless of the operating system and web browser.

2. Connection via Portmone.com page

Preconditions

You should sign an agreement with Portmone.com.
You need to agree with Google Pay Terms of Service.

Description

With this connection method, you do not need to perform additional integrations. The Google Pay button will be displayed on Portmone.com payment page. You can manage payment methods and the order in which the payment instruments (including Google Pay) are displayed using JSON-request (see section 3.2 of documentation) or contacting the cooperation manager.

An example of payment page

3. Connection with Google Pay API

Preconditions

You should register with Google Pay API.
Your website should use HTTPS and support TLS protocol.
To integrate your website or mobile application with the Google Pay, proceed according to the following instructions:

• API documentation:

a) for mobile application

b) for website

• Brand guidelines

a) for mobile application

b) for website

How it works?

Google Pay Flow

You request the encrypted payment data from your application.
Google Pay returns the encrypted data after buyer authentication.
You send the encrypted payment data to your server.
You send an JSON-request to Portmone.com containing the encrypted data.
We send you the payment response
You inform the buyer of the outcome

How to integrate the Google Pay method?

Step 1. Use Google Pay API to get PaymentData.

Settings parameters:

a. allowPaymentMethods : CARD

b. tokenizationSpecification = { "type": "PAYMENT_GATEWAY"}

allowedCardNetworks = ['MASTERCARD', 'VISA'];

allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

c. gateway = portmonecom

d. gatewayMerchantId - A unique identifier of the online shop. Assigned to each partner individually when connected to the Portmone.com system.

An example of dataset returned by Google Pay:

        {
           "apiVersionMinor":0,
           "apiVersion":2,
           "paymentMethodData":{
              "description":"Mastercard •••• 5179",
              "tokenizationData":{
                 "type":"PAYMENT_GATEWAY",
                 "token":{"signature":"MEYCIQC+IHxUu9Wwra2Vu6tBa2wJPCMT3pWtN1VphLGYtNVLLwIhAOkdbNje//eLrXVc+n6LOlc4PqxWOUcqwrmki/CNA1ur","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhRrvGB0kZ1248MEJAPwX0YfrQInhyyRM7nyGFjQuzGSViZG3QC9NMvXR9Zd6uVcVzAz+6K/+NEGIWbX8zbk6A\\u003d\\u003d\",\"keyExpiration\":\"1571208568000\"}","signatures":["MEUCIQCR6vIEiyHB8qmlho4/tLd7W8CIGrZDJlCI48CBHeFPvQIgLZJIe4cZv6pYtYYa56QCI/vvg1GqXTP3bTBjO49r5mI\u003d"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"k85CGUMmd5PaGmQlHFqHc0HrDZmjM1yG82rFB/p31ZyUleN5nihzjOZif/BKXwg3XA2oLXqBSSWcAdfZwXxCEOqvAQE+kpTC7qVO4wTPip6RruraT6vO9M9FtIf0kcqzYSAN7pl1SUA5jC9rHrqucPoh0/FSspup78SWBt8TnmVKC9O3sQhIZ3SMoGOG4mdjtIrgCwWH2cbrxUH0dHAqOe5ANGOY/mII4nTEp7xaKu41hK/kFE15zVyqgPJXP9bPxzMVk/ozEZSfhSzVTS+9stjkU/kT5EibKB3O1bbxyybKcGQ5vxBOtNOBKKd/NuqNmN2eEK3UbSKb1M3gv45gT9cCeEvlzO7Wg0N100vUBp9RPDN9TH4tj4w578sWFKfTi6FsSrZB27SGWcU0EaKHO9buo94mRBY5yqffF3bKg5mAMPzjDhyHSujqWKAs9C5fBzMEuEr2z7A23kfLqBceH5uS9LJMiZ/yVKCwfpY9u2XyCjKdp7I\\u003d\",\"ephemeralPublicKey\":\"BAMDAtfgcPNuzItrwGLigGj3rtxmyHhZLwx1B4RJZ2oo11jpFf3SA6a3utryCMmlCEcqLfLn6WDH2ArrNBGn+Ew\\u003d\",\"tag\":\"T/qhZ/XY5/3Fe4QBKafm6NqS6EzwVeiKXhRlp8NeWrA\\u003d\"}"}
              },
              "type":"CARD",
              "info":{
                 "cardNetwork":"MASTERCARD",
                 "cardDetails":"5179"
              }
           }
        }

The data obtained from token should be send to the API Portmone.com using gPayToken request parameter.

Important: The cryptogram obtained from Google Pay must be used only once within a single transaction. Reusing the same cryptogram may result in the payment being declined by the acquiring bank. A new cryptogram must be obtained from Google Pay for each new transaction.

Method: GPay

URL: https://www.portmone.com.ua/r3/api/gateway.

Request parameters:

Parameter	Description	Required
login	The Online Store login to access account management	Yes
password	The Online Store password	Yes
gPayToken	Token received from the Google Pay system	Yes
payeeId	A unique identifier of the Online Store. Assigned to each Partner individually when connected to the Portmone.com system	Yes
billAmount	Amount of the payment. The decimal separator is the dot symbol. For example: "10.21"	Yes
description	Payment description (comment to the order / payment details)	No
shopOrderNumber	Number of paid order (bill) in the Online Store system	No
emailRecipient	E-mail address of the client	No
preauthFlag	Payment pre-authorization flag (value "Y" indicates that this payment is carried out using the pre-authorization procedure, value "N" is a regular payment without pre-authorization)	No
billCurrency	Currency of the payment. Possible values: UAH (default value), USD, EUR, GBP, KZT	No
shop_site_id	Payment channel in the Portmone system	No
threeDs	Section of parameters used to specify the merchant URL (`termUrl` or `appUrl`) to which the client will be redirected after successfully passing the 3D Secure check	No
termUrl	Set "Y" or not use this parameter	No
appUrl	An appUrl of the merchant (when integrating mobile application with Google Pay)	No
clientIp	The value of the IP address of the payer	No

An example of request:

        {
            "method":"GPay",
            "params": {
                "data":{
                "login":"wdishop",
                    "password":"wdi451",
                    "gPayToken":{"signature":"MEUCIQD+9/PnFvB+Lo6d/eHpgqQrMvmRDZdW1AcjQKavHrcPmQIgeVjR1hXqH7hkCn+VZqx/kjdofMIYbyL15Xp52mR9+2s\u003d","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBOHyOhwWk6SK5nqhFBBI1hSvWHAaOO0Ukbrl56zx7fPNttFFKs2U10f6EWbdhULrv4QT4qMNbyVAq8ig1jdsYA\\u003d\\u003d\",\"keyExpiration\":\"1570945959000\"}","signatures":["MEYCIQCe6t42U5OemtGGdYC6npBNbVxe1HbTF8pUkSD7mO+CWAIhAI/0M/XQuW6i8reT0LCNHKoNfgWYwOWHBoj2wpZdgKHh"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"U9ChAIukmQ85TdZKAU/26mJUwUt3cVpJmx/JtFi350F/KiRNiIEGi1CmkgVe+ohzikkKLo37Ty3YQjyjVHNTHmF3AyNVTIJCL7qYybt+aFNI1XFlpv3ArWU+fH8Bi190tl7lLyyeNjWx8L402spsLpuUe9OLLjazIq0Vfjw3wRZ2B2+ybUrnoz5Iydapn8B7c/QqR7w53n6svIK58q7eL159Ano0GyfLpUOLLQ949MhP1ze***UzapUGtMd0k0c/4Nnkfs2TnN6ETEtP8y9J29hYKGVOCo79rRSN2xLsYXGNawIiPc6082HWB82JyuW2bfWAL1R0W+2iql2dBWY\\u003d\",\"ephemeralPublicKey\":\"BPYYpVT5INyXSwoNbP/HuGkjQnfnUwUPMH2bCp6Od3EoihnegFZObjP0IVvDA5YfNlLDJjHutBDj30GW5Fei8xw\\u003d\",\"tag\":\"qt4FcCGO4rp969CBBTPJ0nhAeQeR+rOM0FmXk8DdGLQ\\u003d\"}"},
                    "payeeId":"1185",
                    "billAmount":"10.21",
                    "description":"test payment",
                    "shopOrderNumber":"123456",
                    "attribute1":"1",
                    "attribute2":"2",
                    "attribute3":"3",
                    "attribute4":"4",
                    "emailRecipient":"[email protected]",
                    "billCurrency":"UAH",
                    "preauthFlag":"N",
                    "shop_site_id" : "",
                    "threeDs":{
                        "termUrl":"Y",
                        "appUrl":"https://portmone2.com/r3/ecommerce/test/master-test-from"
                    },
                "clientIp": "127.0.0.7"
                }
            },
            "id": "1"
        }

Response parameters:

Parameter	Description
status	The result of payment. Possible values: - PAYED – successful payment, - REJECTED – rejected, - CREATED – order created, but not paid
errorCode	Error code. If the parameter value is "0", this means that the payment was successful or additional verification is required (see the value of the `isNeed3Ds` parameter). If the parameter value is greater than 0 or empty, an error has occurred
error	Error description. See Error codes table
shopBillId	A unique identifier (ID) assigned to each transaction (payment document) in the Portmone.com system
billAmount	The transaction amount sent in the request
billNumber	Number of an order (bill) in the Online Store system. Maximum length is 120 symbols
attribute1	Service field. Filled at company’s discretion
attribute2	Service field. Filled at company’s discretion
attribute3	Service field. Filled at company’s discretion
attribute4	Service field. Filled at company’s discretion
cardMask	Payer’s card mask or token mask
actionMPI	The card issuing bank page URL to which client should be redirected to confirm payment with 3D Secure
pareq	Parameter which should be sent to `actionMPI` for 3D Secure check
authCode	Bank authorization code
description	Comment to the order / description of payment details. Maximum length is 250 symbols
lang	Errore message languge. Depends on the localization of the endpoint you requested*
md	Parameter which should be sent to `actionMPI` for 3D Secure check
isNeed3DS	3DS-authorization flag ("Y" - 3D Secure check is required, "N" - no additional actions required)
token	Token value for subsequent payments. For payment methods GPay and APay token is not generated
billCurrency	Currency of the payment
transactionId	Transaction ID in the acquiring bank system
termUrl	URL of the merchant site to which the issuing bank returns a response message after passing 3D Secure. The value is generated by the Portmone system
successUrl	appUrl of the merchant site to which the issuing bank returns a response message after passing 3D Secure (if this value was passed in the `appUrl` parameter of the payment request)
pdfUrl	Link to save payment receipt. Provided to the client if `status=PAYED`
shop_site_id	Payment channel in the Portmone system

Note: * – to receive localized error texts, you should send a request to the appropriate endpoint:

https://www.portmone.com.ua/r3/api/gateway – default is Ukrainian https://www.portmone.com.ua/r3/uk/api/gateway – for messages in Ukrainian https://www.portmone.com.ua/r3/en/api/gateway – for messages in English

An example of successful response:

        {
            "result": {
                "status": "PAYED",
                "errorCode": "0",
                "error": "",
                "shopBillId": "550298815",
                "billAmount": "1.01",
                "billNumber": "SHP-00000002",
                "attribute1": "",
                "attribute2": "",
                "attribute3": "",
                "attribute4": "",
                "cardMask": "535560******3735",
                "actionMPI": "",
                "pareq": "",
                "authCode": "67037Z",
                "description": "test payment",
                "lang": "uk",
                "md": "",
                "isNeed3DS": "N",
                "token": "",
                "billCurrency": "UAH",
                "transactionId": "927500948048",
                "pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35357a20f10b49519794e81b48b20d0402cd2b7654553048021cb230400befdf94bacfbb12bd77983adae9422fbcc51cf0987a171403f08b33b2d119249845bad4e457",
                "shop_site_id" : ""
            },
            "id": "1"
        }

An example of failure:

        {
            "result": {
                "status": "REJECTED",
                "errorCode": "5",
                "error": "Transactions has exceeded the limit by your bank",
                "shopBillId": "5530964511",
                "billAmount": "1",
                "billNumber": "P55309624511",
                "attribute1": "A",
                "attribute2": "",
                "attribute3": "",
                "attribute4": "",
                "cardMask": "535560******3735",
                "actionMPI": "",
                "pareq": "",
                "authCode": "",
                "description": "test payment",
                "lang": "en",
                "md": "",
                "isNeed3DS": "N",
                "token": "",
                "billCurrency": "UAH",
                "transactionId": "928199458716",
                "pdfUrl": "",
                "shop_site_id" : ""
            },
            "id": "1"
        }

An example of response if 3D Secure check is required:

        {
            "result": {
                "status": "CREATED",
                "errorCode": "0",
                "error": "",
                "shopBillId": "663526924",
                "billAmount": "1.2",
                "billNumber": "123456.14052020.05",
                "attribute1": "1",
                "attribute2": "2",
                "attribute3": "3",
                "attribute4": "4",
                "cardMask": "516874******5179",
                "actionMPI": "https://acs.privatbank.ua/pPaReqMC.jsp",
                "pareq": "eJxVUcluwjAQ/RWUY6XiJZtBE6MUuh0CKYVDj1FiQSqy4IQCf99xCNDKGmne7H4PJqdiN/hRusmrMrDYkFoDVaZVlpebwFqvXh6FNZGw2mqlZp8qPWglIVJNk2zUIM8CK06Was/cEXWY8LjjuB4Xtuc7jNr4RkJ49ohbEuIQ6yT0myQuGnIgV4gjdbpNylZCku6f3ufSdYTnCiA9hELp95n0GHN8HxsvEMqkUDJeLFfRYv48nC6ih9c4/ALSxSGtDmWrz1JQB8gVwEHv5LZt62ZMSF3ptqhKNUyrAojJALmfEh+M1+CkU57JaBYe0c5oLPpen+ZneoxWH2hRAMRUQJa0SnLKKXW5O2DO2PXHZncXh6QwJ+DXOcV/XQDUZkfYZ0zibwCQb41ynOVIYOqGQJ1qvBorkIqbD+R+8PTNMJm2SJIRxmM2E6yjs4uZATmSwTll3QQDgJgu0itFepXR+6f+L1ndtBw=",
                "authCode": "",
                "description": "test payment",
                "lang": "en",
                "md": "194203287",
                "isNeed3DS": "Y",
                "token": "",
                "billCurrency": "UAH",
                "transactionId": "",
                "termUrl": "https://www.portmone.com.ua/r3/pg/confirmapigateway/3332633904a34c326a772f1256a70958bdaa4cc092a3fa86bdd5712dc033654d2582a3e4668f52230428/?shopBillId=303977a031fa486ee5e571aa119b89ba9eacd8&3ds=Y&py=303523031e7bb72dc8c426146af248",
                "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-from",
                "pdfUrl": ""
            },
            "id": "1"
        }

To proceed with 3D Secure verification procedure client should be redirected to the issuing bank page (action). To do so merchant should send POST request including PaReq and MD parameters and merchant URL to return after 3D Secure (TermUrl).

Request parameters to call the bank page:

Parameter	Description
action	The `actionMPI` value received in Portmone response
PaReq	The `pareq` value received in Portmone response
MD	The `md` value received in Portmone response
TermUrl	URL of the merchant site to which the issuing bank returns a response message after passing 3D Secure. If payment is made from the application - app url

During the 3-D Secure procedure, there are two possible options for processing the bank's response:

Processing on the Portmone side
If the TermUrl parameter is not passed during the actionMPI call, the response (PaRes, MD) is sent directly to the Portmone system. Portmone independently completes the 3-D Secure processing.
Processing on the merchant side
If the TermUrl parameter is passed during the actionMPI call, the bank returns the result (PaRes, MD) to the merchant's URL. In this case, the merchant must receive the data and manually call the confirmMpi method to finalize the payment.

Example of HTML-form to call the bank page:

        <form id="TheForm" action="https://acs.privatbank.ua/pPaReqMC.jsp" method="POST"
            name="TheForm">
            <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDY5O6u1wW1oxrqPbiA0KtfegjwY
                1iBHTBFvv1nUWs7SabzJnrmTMwaYv94FPpOq/KscWG1BqoMqvWebkZW++rp/vAmkhYbbVSszeVnbSSE
                Km6TjdqkK/HVpIu1ZF5nsMDfK7g3Oc2FUwI6nmccSE45ZaEJMQ8Cf0kiYOGNpArxJY626ZlIyHNjg/z
                hfTcgHsBkB5CofR8Jjljru9j4QVCmRZKJvFyFcWLx+E0ju6ek/ADSOeHrDqVjT7LgLpArgBOei+3TXO
                oR4QcKt0UVamGWVUAMREgNyrJyVg1dmrztYxm4Rf+Nl6F39EuaxdTyqJZRKPd6xiIyYB12ihpUyaoY/
                sDZo+YO3JxdueHtDAUcHXbwb0uAA5mRthHTOCvA1Bvjec4SxFQXOGKQLUHZI0ZKMWvDeRGePpilMwaF
                MlxHN/2fY+KTs7OZxrkKIaNZLsOBgAxVaS/FOmvjNa/6/8AWHOz+w=="/>
            <input type="hidden" name="MD" value="166765657"/>
            <input type="hidden" name="TermUrl" value="https://portmone2.com/r3/ecommerce/test/"/>
        </form>

Afrer entering a code at the issuing bank page the client returns to the merchant's server address (specified as TermUrl at the request). The response message from the bank contains parameters with MD and PaRes values which should be sent to the Portmone for obtaining authorization results.

Request parameters for 3D Secure confirmation:

Parameter	Description
MD	The `MD` value received from the bank to your URL
PaRes	The `PaRes` value received from the bank to your URL
shopBillId	A unique identifier of transaction (payment document) in the Portmone.com system which was received in previous requests

An example of request to the Portmone for 3D Secure confirmation:

{
    "method": "confirmMpi",
    "params": {
        "data": {
            "MD": "166765657",
            "PaRes": "eJzVWFeP47iy/iuLvY/GrrJsLTwNUNGSLcmKlvSmZOVgBSv8+it3T88O+s4eHNyXgyPAMFmsKhZZ4SN5NNMujlkjDscufjvKcd/7SfxbFn37/err8QMhCIw8bB9OkeSeRGEKoSiYIEiEpCgSJn9/O16BHvcfEq8WhmF7dL8nYOqwDT7jrs+a+g35E/4TPUKf3W2iLkz9eng7+uGDFpU3Aj+QxOEIfe8eq7gT2TcSQfD9fhP86B6hv",
            "shopBillId": "476986520"
        }
    },
    "id": "1"
}

The response from the Portmone.com will contain the result of payment.

Step 2. Check the integration checklist.

Step 3. Send to GPay mobile application package file (.apk) or link to site with payment page for verification.

Appendix 1. Response processing diagram

Response processing diagram

Appendix 2. Error codes

Код	Опис	Повідомлення про помилку (en)	Повідомлення про помилку (uk)	Рекомендовані дії
1	Declined by bank	Transaction declined by bank	Операція відхилена банком	Клієнту необхідно звернутись до свого банку. Може повторити оплату
2	Transaction is prohibited by acquiring bank	Transaction is prohibited by acquiring bank	Операція відхилена банком-еквайером	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
3	Transaction is prohibited by issuing bank	Transaction is prohibited by issuing bank	Операція відхилена вашим банком	Клієнту необхідно звернутись до свого банку. Може повторити оплату
4	Technical/ communication problem	Technical problems. Please try again later	Технічні проблеми. Спробуйте пізніше	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
5	Transaction has exceeded the limit by your bank	Transaction has exceeded the limit by your bank	Операція відхилена банком. Перевищення лімітів	Клієнту необхідно звернутись до свого банку. Може повторити оплату
6	Not sufficient funds	Transaction declined by bank. Insufficient funds	Операція відхилена банком. Недостатньо коштів	Клієнту необхідно звернутись до свого банку. Може повторити оплату
7	Invalid CVV or card expiry date	Transaction declined by bank. Invalid CVV or card expiry date	Операція відхилена банком. Некоректний CVV або термін дії картки	Клієнту необхідно звернутись до свого банку. Може повторити оплату
8	Invalid OTP code	Transaction declined. Invalid OTP code	Операція відхилена. Введено невірний код	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
9	Invalid 3DS data	Transaction declined by bank. Invalid 3DS code	Операція відхилена. Введено невірний код	Клієнту необхідно звернутись до свого банку. Може повторити оплату
10	Duplicate transactions	Transaction declined. Duplicate transactions	Операція відхилена. Повторна транзакція	Клієнт може повторити оплату
11	Format error	Transaction declined. Format error	Операція відхилена. Некоректний формат запиту	Мерчанту необхідно перевірити коректність формату запиту
12	Portmone verification	Additional card verification required	Необхідно пройти додаткову перевірку картки	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
13	System error. Please try again.	System error. Please contact Portmone.com support	Системна помилка. Зверніться до служби підтримки Portmone.com	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
14	Wrong signature	Transaction declined. Authentication failed or invalid request	Операція відхилена. Не пройдена аутентифікація або некоректний запит	Мерчанту необхідно перевірити коректність параметрів запиту
15	Query time exceeded	Transaction declined. Timeout. Contact Portmone.com support	Операція відхилена. Перевищено час очікування. Зверніться до служби підтримки Portmone.com	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
16	Invalid request data	Transaction declined. Invalid request	Операція відхилена. Некоректний запит	Мерчанту необхідно перевірити коректність запиту
17	Transaction has exceeded system limits	Transaction declined. Limit is exceeded. Contact Portmone.com support	Операція відхилена. Перевищено ліміт. Зверніться до служби підтримки Portmone.com	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
18	Fraud	Transaction declined by Portmone.com monitoring system. Please contact support	Операція відхилена моніторинговою системою Portmone.com. Зверніться до служби підтримки	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
19	Order not found	Order not found	Замовлення не знайдено

1. Introduction​

2. Connection via Portmone.com page​

Preconditions​

Description​

3. Connection with Google Pay API​

Preconditions​

How it works?​

How to integrate the Google Pay method?​

Appendix 1. Response processing diagram​

Appendix 2. Error codes​

1. Introduction

2. Connection via Portmone.com page

Preconditions

Description

3. Connection with Google Pay API

Preconditions

How it works?

How to integrate the Google Pay method?

Appendix 1. Response processing diagram

Appendix 2. Error codes