iPay Google Pay API Documentation – Internet acquiring iPay.ua

1. General information
2. Integration
- 2.1 Connect via iPay page
- 2.2 Direct integration via Google Pay API
3. Payment processing

3.1 Configuration
3.2 Sandbox
3.3 General structure of the request
3.4 List of requests
3.5 System errors
3.6 Bank error groups

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

2.2.1 Web integration

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

2.2.2 Android integration

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

2.2.3 Configuration

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

3.4.2 PaymentCreate

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
recurrent	bool	Recurrent payment (true or false). Used for the first request to receive in response recurrent_token if payment supports recurrent
recurrent_token	string	Recurrent payment token
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)
response.transactions	array	Array of transactions
response.transactions[].trn_id	integer	Transaction ID
response.transactions[].smch_id	integer	Submerchant ID
response.transactions[].invoice	integer	Invoice
response.transactions[].amount	integer	Amount (with commission)
For successful payments (post_status = 5), the following fields returns additionally
response.recurrent_token	string	Recurrent payment token, returns if payment supports recurrent
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",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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": "АТ «Ощадбанк»",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

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)
response.transactions	array	Array of transactions
response.transactions[].trn_id	integer	Transaction ID
response.transactions[].smch_id	integer	Submerchant ID
response.transactions[].invoice	integer	Invoice
response.transactions[].amount	integer	Amount (with commission)
For successful payments (post_status = 5), the following fields returns additionally
response.recurrent_token	string	Recurrent payment token, returns if payment supports recurrent
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",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

3.4.4 PaymentSale

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)
response.transactions	array	Array of transactions
response.transactions[].trn_id	integer	Transaction ID
response.transactions[].smch_id	integer	Submerchant ID
response.transactions[].invoice	integer	Invoice
response.transactions[].amount	integer	Amount (with commission)
For successful payments (post_status = 5), the following fields returns additionally
response.recurrent_token	string	Recurrent payment token, returns if payment supports recurrent
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",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

3.4.5 PaymentCancel

Request body structure (one transaction)

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

Request example (one transaction)

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

Request body structure (multi transactions)

Field	Type	Description
Required fields
pmt_id	integer	iPay payment ID
Optional fields
transactions	array	Array of transactions
transactions[].trn_id	integer	Transaction ID
transactions[].amount	integer	Refund amount, in coins

Request example (multi transactions)

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": 1234567,
            "transactions": [
                {
                  "trn_id": 6636,
                  "amount": 50
                },
                {
                  "trn_id": 6638,
                  "amount": 30
                }
            ]
        }
    }
}

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.transactions	array	Array of transactions
response.transactions[].trn_id	integer	Transaction ID
response.transactions[].smch_id	integer	Submerchant ID
response.transactions[].invoice	integer	Invoice
response.transactions[].amount	integer	Amount (with commission)

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": "АТ «Ощадбанк»",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

3.4.6 GetPaymentStatus

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)
response.transactions	array	Array of transactions
response.transactions[].trn_id	integer	Transaction ID
response.transactions[].smch_id	integer	Submerchant ID
response.transactions[].invoice	integer	Invoice
response.transactions[].amount	integer	Amount (with commission)
For successful payments (post_status = 5), the following fields returns additionally
response.recurrent_token	string	Recurrent payment token, returns if payment supports recurrent
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",
        "transactions": [
            {
                "trn_id": 1234567,
                "smch_id": 5410,
                "invoice": 100,
                "amount": 100
            }
        ]
    }
}

3.4.7 GetPaymentInvoice

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)
66	The operation was rejected due to the need to pass 3DSecure verification. It is recommended to resend the request, but with a parameter pmt_info.force_security_rate=3D
67	The operation was rejected due to the fact that this card is from a foreign bank and is prohibited for operation. It is recommended to make a new payment with a different payment card.