Acquiring via Google Pay™

Protocol Description

API allows the Partner to accommodate payments from debit and credit cards performed by users on websites or in apps via Google Pay™

The solution is implemented in concordance with methods used by Google Pay:

if you provide Google Pay as a payment method to your customers, you must use the official Google Pay logo and button assets in compliance with Google Pay Android brand guidelines and Google Pay web brand guidelines, without modifications to the Google Pay asset colors, proportions, or appearance.

You must also adhere to Google Pay and Wallet API's Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.

Payments interaction diagram

Payments interaction diagram description:

1) Partner's Shop provides payment method to end User;
2) User selects GooglePay as a payment method;
3) Partner's Shop transfers payment method information to System (see «Payment request» segment);
4) System returns payment form to Partner's Shop for further display (see «Payment request» segment);
5) Partner's Shop displays payment form to end User. This can be done by either by redirecting the User to payment form URL, or by opening payment form in WebView;
6) User chooses source of funds (card, account) for payment;
7) System requests payment token from chosen payment system (GooglePay);
8) Payment system returns payment token to System;
9) System debits funds from User account;
10) System sends payment result callback to (success/failure, see «Callback example» segment).

Optional:
10.1) Partner's Shop requests transaction status from System (see «Payment status request» segment).

11) Partner's Shop redirects User to url_success or url_fail depending on transaction result.

Available request methods

The following requests are used for information exchange between Partner and System:

Request directionRequest descriptionURL
Partner -> SystemPayment request, POST/acquiring-v2/googlepay/pay
Partner -> SystemPayment status request, POST/acquiring-v2/{Service_ID}/check
Partner -> SystemPayment confirmation request (only available for two-stage payments), POST/acquiring-v2/{Service_ID}/confirm
Partner -> SystemHold cancellation request (only available for two-stage payments), POST/acquiring-v2/{Service_ID}/unhold
Partner -> SystemRefund requestContact technical support to issue refunds
Partner -> SystemTransaction registry request, GETRequest description provided below

Where is the value of :

  • For Stage environment - https://int.gwp.digital

  • For Production environment - https://gwp.digital

{Service_ID} – Partner identifier within System. Provided after onboarding.

Every request must contain a header (HTTP header) Content-Type with the value application/x-www-form-urlencoded.

The system checks the request from the point of view of security and correctness of the request. If the security check fails, the System returns HTTP Status 400 to the request, in case of a request validation error, HTTP Status 401 or 403.

Payment request

to initiate a payment you should send the following request:

POST /acquiring-v2/googlepay/pay

Request parameters:

ParameterRequiredTypeDescriptionExample
orderidYesStringUnique transaction identifier within Partner's system123456789
amountYesDecimalTransaction amount1.01
dtYesStringRequest date and time in yyyyMMddHHmmss format2024070123301
url_successYesStringURL for User redirect after successful paymenthttps://google.com/success
url_failYesStringURL for User redirect after unsuccessful paymenthttps://google.com/fail
callback_urlNoStringCustom callback URLhttps://some.partner.system/callback
controlYesStringControl signature. SHA256-hash ( orderid + amount + dt + SecretKey), where «+» - concatenation sign36a02d89974fd0efa9d7bc8036d8983c
requestNoStringRequest type. Available values: check, pay, get-status-
receiver_fioNoStringUser's full name. String, only latin characters and spaces are allowedTestio Testi
currencyNoStringPayment currency, ISO 4217 Alpha 3EUR
payer_countryNoStringUser's country of residence, ISO 3166-1-Alpha 2PL
payer_commisNoDecimalUser's payment fee (if applicable)1.50
detailsofpaymentNoStringPayment description/detailsSome descpription
client_ipNoStringUser's IP address. Format: IPv4 / IPv691.19.8.17
emailNoStringUser's e-mail address[email protected]
merchant_siteNoStringPartner Shop website, where payment takes placehttps://123abc.org

Some optional parameters need to be passed in addition depending on the specific configuration. For a list of mandatory parameters for your account, please contact technical support.

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401.

If request parameter value is set to check or get-status – response will contain current transaction status. If request parameter value is set to pay, any other value or empty value – response will contain a payment link.

Example of a payment request

POST {{url_system}}/acquiring-v2/{paymentSystem}/pay

HEADERS

Content-Type: application/x-www-form-urlencoded

BODY

"orderid": "123456789"
"amount": "300.00"
"dt": "20240701123301"
"control": "b66f2f573e59015a5fae686aaef6207d97698ef79efe09f1aac9a6160710f108"
"merchant_site": "https://123abc.org"

Where the control value is generated using SecretKey = Qwerty123

Signature generation string: 123456789300.0020240701123301Qwerty123

System responds in XML format, UTF-8 encoding (Content-type: application/xml):

Successful response example:

<response>
         <result>OK</result>
         <txnid>20004410</txnid>
         <url>https://{{url_system}}/user/url/Z2Rlc1A2aU85OVQ0N3NtajdIK2VqLzdQMGtONEp0MXpzQ1czUHh0h4Nm9YaHQ3ZVBIQjNCSHJHNjNHpMTQ</url>
</response>

Unsuccessful response example:

<response>
         <errorCode>1</errorCode>
         <txnid>20004410</txnid>
         <description>Something went wrong, please try again or contact support</description>
         <paymentStatus>PAY_FAIL</paymentStatus>
</response>

In case of a repeat request with request=pay or absent request parameter System will form a following response:

<response>
         <errorCode>9712</errorCode>
         <description>Operation 123456789 already exists</description>
         <paymentStatus>DUPLICATE TRANSACTION</paymentStatus>
</response>

A list of the main possible errors and their description:

errorCodepaymentStatusdescpription
9712DUPLICATE TRANSACTIONOperation %s already exists
9713INVALID PROVIDERUnable to determine provider
9714PROCESSING ERROR

Temporary error, please try again later

Payment amount is less than allowed!

Payment amount is more than allowed!

9908ORDER NOT FOUNDOperation %s not found

Parameters desctiption

  • «Result=OK» - Successful transaction initiatization, «errorCode» = error code in case of a failed initialization.
  • «txnid» - Unique request identifier within System (Required for «Result=OK»).
  • «url» - Payment form URL for User to be redirected to (Required for «Result=OK»).

Callback

After User follows the redirect URL and confirms payment, System sends a callback request containing transaction status to Partner, while User gets redirected to one of the URL's provided by Partner in the initial request – url_success or url_fail depending on payment result.

Callback example:

POST {{partner_url_for_notification}}

BODY
id=20476210&&result=1&cmd=status&control=a5fd50af2baae1298d8e89fde3fcbed25e7e3080a9bdbfd38b8938ad7cab52bb

Callback parameters:

ParameterRequiredTypeDescription
idYesStringUnique transaction ID in Partner's system
resultYesIntegerResult code:

0 – Successful operation

1 - Error

2 – Awaiting User input
cmdYesStringstatus for one-stage payments;

cancel or confirm for two-stage payments
controlYesStringControl signature, SHA256-hash ( id + result + SecretKey).

where "+" is the concatenation sign, secret_key is the secret key to the Partner's account.

Expected callback response:

In response to HTTP-request Partner forms a response in XML format, UTF-8 encoding (Content-type: text/plain or application/xml).

<response>
         <result>0</result>
         <description>success</description>
</response>
ParameterRequiredTypeDescription
resultYesIntegerRequest processing result code. Can hold following values:

0 – Request successfully accepted by Partner;

1 – Temporary request processing error (request should be resent later), callback request will be retried;

2 – Permanent request processing error (for example, incorrect request parameters), callback request will not be retried.
descriptionNoStringRequest result processing description

Payment status request

POST /acquiring/{Service_ID}/check

, where {Service_ID} – Partner's ID in System.

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401, in case of not found operation - HTTP Status 404

Request parameters:

ParameterRequiredTypeDescriptionExample
orderidYesStringUnique transaction identifier within Partner's system123456789
dtYesStringRequest date and time in yyyyMMddHHmmss format20240701233011
controlYesStringControl signature. SHA256-hash (orderid + dt + SecretKey)**, where «+» - concatenation sign.a2cfa5ff904616bbb670ed0b2e7fcef17ac7754cc0105f251bdfe37ce491dd1f

Example of a payment status request

POST {{url_system}}/acquiring-v2/{Service_ID}/check

HEADERS

Content-Type: application/x-www-form-urlencoded

BODY

"orderid": "123456789"
"dt": "20240701233011"
"control": "a2cfa5ff904616bbb670ed0b2e7fcef17ac7754cc0105f251bdfe37ce491dd1f"

Where the control value is generated using SecretKey = Qwerty123

Signature generation string: 12345678920240701233011Qwerty123

System responds in XML format, UTF-8 encoding (Content-type: application/xml):

Example response for an operation with a successful final status:

<response>
         <txnId>20476210</txnId>
         <paymentStatus>PAY_OK</paymentStatus>
         <paymentStatusDesc>SUCCESS</paymentStatusDesc>
</response>

Example of a response for an operation with an unsuccessful final status:

<response>
         <txnId>20476211</txnId>
         <description>User did not follow the link</description>
         <paymentStatus>PAY_FAIL</paymentStatus>
         <paymentStatusDesc>FAIL</paymentStatusDesc>
</response>

Example of a response for an operation that does not exist in the System:

<response>
         <errorCode>9908</errorCode>
         <description>Operation 123456789 not found</description>
         <paymentStatus>ORDER NOT FOUND</paymentStatus>
</response>

Response parameters>:

ParameterRequiredTypeDescription
paymentStatusYesStringINIT_FAIL – Payment initialization failed

PAY_OK – Successful payment

PAY_FAIL – Failed payment

PROCESSING – Payment is processing

REF_OK – Successful refund

ORDER NOT FOUND – Payment with ordered is not found

MANUAL_OK – Successful payment (status corrected manually)

MANUAL_FAIL – Unsuccessful payment (manually adjusted status)
descriptionYesStringDetailed error description
paymentStatusDescNoStringPayment status description
txnidNoStringUnique transaction ID within System

Payment confirmation request

(Available only when two-stage payments are enabled)

POST {url_system}/acquiring-v2/{Service_ID}/confirm

, where {Service_ID} – Partner's ID in System.

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401, in case of not found operation - HTTP Status 404

Request parameters:

ParameterRequiredTypeDescriptionExample
orderidYesStringUnique transaction identifier within Partner's system123456789
dtYesStringRequest date and time in yyyyMMddHHmmss format20240701233011
controlYesStringControl signature. SHA256-hash (orderid + dt + SecretKey)**, where «+» - concatenation sign.a2cfa5ff904616bbb670ed0b2e7fcef17ac7754cc0105f251bdfe37ce491dd1f

System responds in XML format, UTF-8 encoding (Content-type: application/xml):

<response>
         <paymentStatus>PAY_OK</paymentStatus>
         <paymentStatusDesc>CONFIRMED</paymentStatusDesc>
         <txnId>100001900441</txnId>
</response>

Response parameters:

ParameterRequiredTypeDescription
paymentStatusYesStringINIT_FAIL – Payment initialization failed

PAY_OK – Successful payment

PAY_FAIL – Failed payment

PROCESSING – Payment is processing

REF_OK – Successful refund

ORDER NOT FOUND – Payment with ordered is not found
paymentStatusDescYesStringPayment status description
txnidYesStringUnique transaction ID within System
descriptionYesStringDetailed error description

Hold cancellation request

(Available only when two-stage payments are enabled)

POST {url_system}/acquiring-v2/{Service_ID}/unhold

, where {Service_ID} – Partner's ID in System.

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401, in case of not found operation - HTTP Status 404

Request parameters:

ParameterRequiredTypeDescriptionExample
orderidYesStringUnique transaction identifier within Partner's system123456789
dtYesStringRequest date and time in yyyyMMddHHmmss format20240701233011
controlYesStringControl signature. MD5-hash (orderid + dt + SecretKey)**, where «+» - concatenation sign.a2cfa5ff904616bbb670ed0b2e7fcef17ac7754cc0105f251bdfe37ce491dd1f

System responds in XML format, UTF-8 encoding (Content-type: application/xml):

<response>
         <paymentStatus>PAY_FAIL</paymentStatus>
         <paymentStatusDesc>UNHOLDED</paymentStatusDesc>
         <txnId>100001900441</txnId>
</response>

Response parameters:

ParameterRequiredTypeDescription
paymentStatusYesStringINIT_FAIL – Payment initialization failed

PAY_OK – Successful payment

PAY_FAIL – Failed payment

PROCESSING – Payment is processing

REF_OK – Successful refund

ORDER NOT FOUND – Payment with ordered is not found
paymentStatusDescYesStringPayment status description
txnidYesStringUnique transaction ID within System
descriptionYesStringDetailed error description

Refund request

! Contact technical support to issue refunds

POST {url_system}/acquiring-v2/{Service_ID}/refund

, where {Service_ID} – Partner's ID in System.

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401, in case of not found operation - HTTP Status 404

Request parameters:

ParameterRequiredTypeDescriptionExample
orderidYesStringUnique transaction identifier within Partner's system123456789
dtYesStringRequest date and time in yyyyMMddHHmmss format20240701233011
controlYesStringControl signature. MD5-hash (orderid + dt + SecretKey)**, where «+» - concatenation sign.a2cfa5ff904616bbb670ed0b2e7fcef17ac7754cc0105f251bdfe37ce491dd1f

System responds in XML format, UTF-8 encoding (Content-type: application/xml):

<response>
         <paymentStatus>REF_OK</paymentStatus>
         <paymentStatusDesc>REFUNDED</paymentStatusDesc>
         <txnId>0000000100001900441</txnId>
</response>

Response parameters:

ParameterRequiredTypeDescription
paymentStatusYesStringINIT_FAIL – Payment initialization failed

PAY_OK – Successful payment

PAY_FAIL – Failed payment

PROCESSING – Payment is processing

REF_OK – Successful refund

ORDER NOT FOUND – Payment with ordered is not found
paymentStatusDescYesStringPayment status description
txnidYesStringUnique transaction ID within System
descriptionYesStringDetailed error description

Transaction registry request

GET {url_system}/reestr-v2/{type}?service_id={service_id} &dt_start={dt_start} &dt_end={dt_end} &hash={hash}

System checks incoming request for validity and correctness of control signature. If incoming request is incorrect – System will respond with HTTP Status 400, in case of a validation error - HTTP Status 401, in case of not found operation - HTTP Status 404

Request parameters:

ParameterRequiredTypeDescription
typeYesStringRegistry format. Possible values: json, csv, xml
service_idYesIntegerPartner's identifier within System
dt_startYesStringRegistry period starting date and time. Format: DD.MM.YYYY HH:mm
dt_endYesStringRegistry period ending date and time. Format: DD.MM.YYYY HH:mm
hashYesStringControl signature. SHA256-hash(dt_start + dt_end + SecretKey)**, where «+» - concatenation sign.

System will respond with transaction registry in requested format (type).

Example response in XML format:

<?xml version="1.0" encoding="UTF-8"?>
<operations>
         <operation>
                  <id>350087610</id>
                  <pid>Test_01</pid>
                  <status>PAY_OK</status>
                  <created>2023-10-02 14:05:29</created>
                  <changed>2023-10-02 16:10:03</changed>
                  <amount>1,00</amount>
                  <partner_notified>true</partner_notified>
                  <partnerName>AL/Test Google</partnerName>
                  <partnerFee></partnerFee>
         </operation>
         <operation>
                  <id>350128752</id>
                  <pid>Test_02</pid>
                  <status>PAY_FAIL</status>
                  <created>2023-10-05 09:54:06</created>
                  <changed>2023-10-05 11:55:03</changed>
                  <amount>2,00</amount>
                  <partner_notified>true</partner_notified>
                  <partnerName>AL/Test Google</partnerName>
                  <partnerFee></partnerFee>
         </operation>
</operations>

Example response in CSV format:

id;pid;status;created;changed;amount;partner_notified;partnerName;partnerFee 
"350087610";"Test_01";"PAY_OK";"2023-10-02 14:05:29";"2023-10-02
16:10:03";"1,00";"true";"AL/Test Google";"null"
"350128752";"Test_02";"PAY_FAIL";"2023-10-05 09:54:06";"2023-10-05
11:55:03";"2,00";"true";"AL/Test Google";"null"
"350128767";"Test_03";"INIT_FAIL";"2023-10-05 09:55:26";"2023-10-05
12:00:03";"300,00";"true";"AL/Test Google ";"null"

Example response in JSON format:

[
          {
                  "id": "350087610",
                  "pid": "Test_01",
                  "status": "PAY_OK",
                  "created": "2023-10-02 14:05:29",
                  "changed": "2023-10-02 16:10:03",
                  "amount": "1,00", 
                  "partner_notified": "true", 
                  "partnerName": "AL/Test Google", 
                  "partnerFee": "null"
          },
          {
                  "id": "350128752",
                  "pid": "Test_02", 
                  "status": "PAY_FAIL",
                  "created": "2023-10-05 09:54:06",
                  "changed": "2023-10-05 11:55:03",
                  "amount": "2,00", 
                  "partner_notified": "true", 
                  "partnerName": "AL/Test Google", 
                  "partnerFee": "null"
          },
          {
                  "id": "350128767",
                  "pid": "Test_03", 
                  "status": "INIT_FAIL",
                  "created": "2023-10-05 09:55:26",
                  "changed": "2023-10-05 12:00:03",
                  "amount": "300,00", 
                  "partner_notified": "true", 
                  "partnerName": "AL/Test Google", 
                  "partnerFee": "null"
          }
]

Response parameters:

ParameterRequiredDescription
idStringUnique operation ID in the System
pidStringID of the operation in the Partner's system
statusStringOperation result
createdDate-TimeDate and time when the payment operation was created
changedDate-TimeDate and time of the payment operation
amountDecimalPayment amount
partner_notifiedBoolean

Indicated whether a notification (callback) was sent to the Partner. 

Possible values:

true -yes;
false - no.

parametersStringAdditional payment parameters
partnerNameStringPartner’s name in the System
partnerFeeStringCommission amount for operation

For this request, the System has set a limit on the maximum number of operations in the response (no more than 20,000 transactions). If the limit is exceeded, an error message will follow with the text:

"Too much data was requested. Reduce the date range or DT\_END parameter to 12.03.2024 14: 29"

, where the specified date is the time when 20,000 transactions were created in the request minus 1 minute.

To get a further report, the Partner must add 1 minute to the specified time and use the new time as the dt_start