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
            }
        }
    }
}
                  

3.4 List of requests

3.4.1 CalculateFee

Request body structure

Field Type Description
Required fields
invoice integer Payment amount, in coins

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "CalculateFee",
        "body": {
            "invoice": 100
        }
    }
}

Response structure

Field Type Description
response object Response object
response.invoice integer Payment amount, in coins
response.amount integer Payment amount (with commission), in coins
response.fee integer Commission amount, in coins

Response example

{
    "response": {
        "invoice":"1000",
        "amount":"1100",
        "fee":"100",
    }
}

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
threeds_info object 3D Secure verification data
threeds_info.notification_url string Callbak URL with 3D Secure verification results
threeds_info.threeds_requestor_url string Payment site URL
threeds_info.browser_language string Language according to IETF BCP 47, for example: "en-US"
threeds_info.browser_screen_height string User screen height (px)
threeds_info.browser_screen_width string User screen width (px)
threeds_info.browser_color_depth string Color depth of the screen
threeds_info.browser_accept_header string HTTP accept header
threeds_info.browser_tz string Time zone offset between Greenwich Mean Time and the user's local time, in minutes, for example: -120 for Europe/Kiev time zone
threeds_info.browser_user_agent string HTTP user-agent
Optional fields
msisdn string Phone number
transactions array Array of transactions
transactions[].invoice integer Invoice
transactions[].smch_id integer Funds recipient ID
transactions[].desc integer Payment desc (in text format up to 100 characters)
transactions[].info object Additional transaction info

Request example (one recipient of funds)

{
    "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
            },
            "threeds_info": {
                "notification_url": "https://www.merchantsite.com/notification",
                "threeds_requestor_url": "https://www.merchantsite.com",
                "browser_color_depth": "24",
                "browser_language": "en-US",
                "browser_screen_height": "1920",
                "browser_screen_width": "1080",
                "browser_tz": "-120",
                "browser_accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
                "browser_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36"
            }
        }
    }
}

Request example (multiple recipients of funds)

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "transactions": [
                {"invoice":50,"smch_id":"5410","desc":"Тестовий платіж","info":{"custom_field_1":"test"}},
                {"invoice":50,"smch_id":"5472","desc":"Тестовий платіж","info":{"custom_field_1":"test"}}
            ]
        }
    }
}

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, 14 - security service failure)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group
response.bank_acquirer_name string Bank acquirer name
response.rrn string RRN (returns for payment status - 3, 5)
response.auth_code string Authorization code (returns for payment status - 3, 5)
For successful payments (post_status = 5), the following fields returns additionally
response.mch_amount array Info about merchant amount
response.mch_amount[].smch_id string Submerchant identifier
response.mch_amount[].amount string Amount

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

Response example (3D Secure)

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 1,
        "security_rate": "3D",
        "security_data": {
            "redirect_url": "https://example.com/acs"
        },
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

3.4.3 PaymentVerify3DS

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
threeds_data string 3D Secure verification result

Request example

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

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.bank_acquirer_name string Bank acquirer name
response.rrn string RRN (returns for payment status - 3, 5)
response.auth_code string Authorization code (returns for payment status - 3, 5)
For successful payments (post_status = 5), the following fields returns additionally
response.mch_amount array Info about merchant amount
response.mch_amount[].smch_id string Submerchant identifier
response.mch_amount[].amount string Amount

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
invoice integer The final purchase amount in coins

Request example

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

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.bank_acquirer_name string Bank acquirer name
response.rrn string RRN (returns for payment status - 3, 5)
response.auth_code string Authorization code (returns for payment status - 3, 5)
For successful payments (post_status = 5), the following fields returns additionally
response.mch_amount array Info about merchant amount
response.mch_amount[].smch_id string Submerchant identifier
response.mch_amount[].amount string Amount

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID
amount integer Refund amount, in coins

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 (4 - unsuccessful, 9 - payment is canceled)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group
response.bank_acquirer_name string Bank acquirer name

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 9,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

Request body structure

Field Type Description
Required one of these fields - pmt_id or ext_id
pmt_id integer iPay payment ID
ext_id integer Merchant payment ID

Приклад запиту

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetPaymentStatus",
        "body": {
            "pmt_id": 1234567
        }
    }
}

Response structure

Field Type Description
response object Response object
response.pmt_id string iPay payment ID
response.invoice string Payment amount, in coins
response.amount string Payment amount (including commission), in coins
response.pmt_status string Payment status (1 - registered, 4 - unsuccessful, 5 - successful, 14 - security service failure)
response.card_mask string Card mask
response.bank_response object Bank response
response.bank_response.error_group integer Bank error group
response.bank_acquirer_name string Bank acquirer name
response.rrn string RRN (returns for payment status - 3, 5)
response.auth_code string Authorization code (returns for payment status - 3, 5)
For successful payments (post_status = 5), the following fields returns additionally
response.mch_amount array Info about merchant amount
response.mch_amount[].smch_id string Submerchant identifier
response.mch_amount[].amount string Amount

Response example

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

Request body structure

Field Type Description
Required fields
pmt_id integer iPay payment ID

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetPaymentInvoice",
        "body": {
            "pmt_id": 1234567
        }
    }
}

Response structure

Field Type Description
response object Response body
response.invoice string Link to invoice

Response example

{
    "response": {
        "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090"
    }
}

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_acquirer_name": "АТ «Ощадбанк»"
    }
}
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
56 Card is expired
57 Invalid card
58 Card limit
60 Verification error (3D Secure)