Google Pay Integration Guide

1. General information

Google Pay ™ is an instant payment method from Google that allows you to pay with your card easily and quickly, without having to enter payment information for each payment. Card information is stored securely on Google. This method is available for payment on mobile apps on any Android device and when making a payment in Chrome.

2. Integration

2.1 Connect via iPay page

With this method of connection, there is no need for additional integrations. The Google Pay button will be displayed on the iPay page.

2.2 Direct integration via Google Pay API

To connect Google Pay to your website, follow the instructions below:

Documentation: https://developers.google.com/pay/api/web

Branding requirements: https://developers.google.com/pay/api/web/guides/brand-guidelines

To connect Google Pay to your mobile app, follow the instructions below:

Documentation: https://developers.google.com/pay/api/android

Branding requirements: https://developers.google.com/pay/api/android/guides/brand-guidelines

The values of the parameters passed to the PaymentMethod object:

allowedAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
allowedCardNetworks = ['MASTERCARD', 'VISA'];
tokenizationSpecification.type = "PAYMENT_GATEWAY";
tokenizationSpecification.parameters.gateway = "ipayua";
tokenizationSpecification.parameters.gatewayMerchantId = "YOUR_IPAY_MERCHANT_ID".

Client's billing address is not required for iPay Google Pay API requests.

2.2.4 Google Pay Token

In response, Google shall return the PaymentData item, and the field paymentMethodData.tokenizationData.token shall contain a safely encrypted Google Pay Token.

An example of Google Pay Token:

{ 
   "signature":"MEUCIEJrIcKJjJJMcWHpCKnyh8Y9T6yBWw5eGl7sXpK/3/rZAiEApjQc46NPbUKNOuGqov9yZEgpIl5ZHD/Ud0CJDf6HTAo\u003d",
   "intermediateSigningKey":{ 
      "signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4clrDUue7fDXNliISLuov7XE5tPJriFeulNnmRjOwSs+CnfHubUF5nKtUBxxfVjYOEv83IQfVjjFgRH3P00I+A\u003d\u003d\",\"keyExpiration\":\"1566069507000\"}",
      "signatures":[ 
         "MEQCIFpxY0DQODL76+01FZbGlYyiogKpOqZYR728rEV7ebZ0AiB4uQesvvP8N05wB7ICt1vsjfYaV8x9ztG/rMvaDkx0iw\u003d\u003d"
      ]
   },
   "protocolVersion":"ECv2",
   "signedMessage":"{\"encryptedMessage\":\"jooDzaMBCjVrOlf7qelBoHyeMzLcqUdQ09+m8OkSyjqJkdXKDS4mkF9nqlJJyckcW2/bHqSIOng1f4GWntBxsXMvpe6ehWd+9HT3OJ47lGBcs8YDqfJliUljmf5qA9H0MOAdWrKTJffNy9ERkFl8y+kKzloPLJuBWDZvoiM8svfiVEP/OtNuuWWEOIJeEkVOrGkkzk8Q0rdlPl3vLW+uJEXLC2WLQottj3Y46zC74K2mXoAURp8UhlOhnMns+IurumflnpA660EEX/p+eMtB2yzlxMgx61EAwHoWd8kRpJpoWdQo7gTUqgLkzkBSIG33BfGSXDtuPTQwTRrEOPEPsGdGMQ36TcfN4CKP4OOMO7gbXo7SsQ47Xa+44v0lgoxfkpxDq/ucfble3d9DK/4/xu5ROEFPvyBT7GMG3U4yogsPU87HDBzJWoqqxUwx94dtbzr6l5qhXFh9cmbzPJMddEhgnIsA/fdN4VdoYZ4GZ956+94QJYIuZm5PPMhLIcXAzsG19O+9ZqadYcy1mtNNiTEANl/b0YXp2NDP+PQ8yG1PSYh7Onkfig\u003d\u003d\",\"ephemeralPublicKey\":\"BLg164ZqP/aGF9w0o79LD90XEs1oJ+WVflQL2T0CWjyKQmopI76a8KQ7UkF99bnx1ngYUXNSKz7sFht9MnTAXB8\u003d\",\"tag\":\"xdw0JgykkDXzdTGv9dvIjOGcZ9yVXG9TsRun9IwVhuo\u003d\"}"
}
                  
To charge the payment card stored under Google Pay, Google Pay Token value must be encoded with the Base64 function and send to the iPay Google Pay API in PaymentCreate request.

3. Payment processing

3.1 Configuration

In order to interact with the iPay Google Pay API, you need to get a login (merchant ID) and sign key.

URL for requests: https://api-googlepay.ipay.ua

Transmission format: JSON data via HTTP method POST

Encoding: UTF-8

Signature algorithm (sign field in request):
You need to combine the following lines into one: request time (field request.auth.time) and sign key and encrypt it with SHA3-512 algorithm.

3.2 Sandbox

The Google Pay payment method is available also under the Sandbox environment, value of PaymentOptions object's property "environment" must be set to "TEST".

Sandbox payments are emulated without real card charge.

3D Secure is enabled for invoice more than 500 UAH.

3.3 General structure of the request

Field Type Description
request object Request object
request.auth object Authentication object
request.auth.login string Merchant ID
request.auth.time string Request time in Europe/Kiev time zone
Format: YYYY-MM-DD HH:MM:SS
Example: 2017-01-01 00:00:00
request.auth.sign string Request signature
request.action string The name of the request
request.body object The body of the request

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment ",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}
                  

3.4 List of requests

Request body structure

Field Type Description
Required fields
invoice integer Payment amount, in coins
token string GooglePay Token in JSON format encoded with the Base64 function
pmt_desc string Payment description
pmt_info object Payment information provided by the merchant
Optional fields
msisdn string Phone number
guid string Request GUID generated by the merchant

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

Response structure

Field Type Description
response object Response object
response.pmt_id integer iPay payment ID
response.invoice integer Payment amount, in coins
response.amount integer Payment amount (including commission), in coins
response.pmt_status integer Payment status (1 - registered, 4 - unsuccessful, 5 - successful)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        }
    }
}

Response example (3D Secure)

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 1,
        "security_rate": "3D",
        "security_data": {
            "url": "https://example.com/acs",
            "pareq": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO...",
            "md": "CmD2M2QzYmItOBJjZS00YWAjLTlhMTctNjRiOWYzNWQyNTFk"
        },
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        }
    }
}

3.4.2 PaymentVerify3DS

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
pares integer PaRes value received from the bank to your TermUrl
md string MD value received from the bank to your TermUrl
Optional fields
guid string Request GUID generated by the merchant

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentVerify3DS",
        "body": {
            "pmt_id": 1234567,
            "pares": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol...",
            "md": "CmD2M2QzYmItOBJjZS00YWAjLTlhMTctNjRiOWYzNWQyNTFk"
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

Response structure

Field Type Description
response object Response object
response.pmt_id integer iPay payment ID
response.invoice integer Payment amount, in coins
response.amount integer Payment amount (including commission), in coins
response.pmt_status integer Payment status (3 - authorized payment, 4 - unsuccessful, 5 - successful)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        }
    }
}

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
invoice integer The final purchase amount in coins
Optional fields
guid string Request GUID generated by the merchant

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": 1234567,
            "invoice": 100,
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

Response structure

Field Type Description
response object Response object
response.pmt_id integer iPay payment ID
response.invoice integer Payment amount, in coins
response.amount integer Payment amount (including commission), in coins
response.pmt_status integer Payment status (1 - registered, 4 - unsuccessful, 5 - successful)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        }
    }
}

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
Optional fields
guid string Request GUID generated by the merchant

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": 1234567
        }
    }
}

Response structure

Field Type Description
response object Response object
response.pmt_id integer iPay payment ID
response.invoice integer Payment amount, in coins
response.amount integer Payment amount (including commission), in coins
response.pmt_status integer Payment status (1 - registered, 4 - unsuccessful, 5 - successful)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 9,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        }
    }
}

Request body structure

Field Type Description
Required fields
guid string Merchant request GUID that was passed in previous requests

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "StatusRequest",
        "body": {
            "guid": "AD68E7675FE111E79A65005056B960DFF"
        }
    }
}

Response structure

Field Type Description
response array Response body
response[].action string Request name
response[].msisdn string Phone number, 12 digits long (e.g. 380931234567)
response[].response string Response in JSON format
response[].date string Request date

Response example

{
    "response": [
        {
            "action": "PaymentCreate",
            "msisdn": "380931234567",
            "response": "{\"response\":{\"pmt_id\":\"1234567\",\"invoice\":\"20000\",\"amount\":\"20000\",\"pmt_status\":\"5\",\"card_alias\":\"Test\",\"card_mask\":\"111111********11\",\"msisdn\":\"380931234567\",\"bank_response\":{\"bank_id\":\"31\",\"rc\":\"000\",\"action\":\"\",\"error_group\":null}}}",
            "date": "2017-01-01 15:47:27"
        }
    ]
}

3.5 System errors

Response structure

Field Type Description
response object Response object
response.error string The name of the error that occurred

Response example

{
    "response": {
        "error": "invalid request structure"
    }
}
Error Description
overall error General error
invalid request structure Invalid request structure
unknown field {field_name} The request is given a field that is unknown to the system
invalid pan Invalid card PAN
invalid expm Invalid card expiry month
invalid expy Invalid card expiry year
invalid cvv Invalid CVV code
invalid auth Authentication error
invalid auth time Invalid request time
access denied Access denied

3.6 Bank error groups

If status 4 was received on PaymentCreate or PaymentSale request, the "error_group" field of "bank_response" object contains a bank error group.

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        }
    }
}
Bank error group Description
41 Issuer's refusal
42 Not enough money
43 Issuer's limit
50 Invalid CVV
51 Verification error (3D Secure)
52 Connection error
55 Unknown error