Вот несколько важных вариантов использования, а также рекомендации и API, необходимые для реализации вашего денежного ФОП.
Случаи использования
API ссылочного номера можно использовать по-разному. В этом руководстве будут рассмотрены два варианта использования и описана их реализация.
- Наличные — пользователь платит наличными в физическом месте.
- ВАН — Пользователь переводит деньги на номер виртуального счета.
Наличные
Пользователь может купить что-то у Google, заплатив за это наличными в физическом месте, например в магазине. Чтобы идентифицировать транзакцию, пользователь сгенерирует ссылочный номер, который нужно будет взять с собой в магазин для оплаты. Кроме того, Google покажет пользователю инструкции о том, как совершить покупку. В идеале, как только пользователь завершает покупку, интегратор уведомляет Google, чтобы Google мог доставить продукт.
Ваше контактное лицо в Google попросит образец типичных платежных инструкций. Вы будете работать со своим контактом в Google, чтобы оптимизировать и уточнить обмен сообщениями.
Пользовательский опыт, который Google хочет обеспечить, заключается в том, что заказ клиента доставляется, когда он покидает магазин. Google ожидает, что ReferenceNumberPaidNotification будет получен в Google в течение трех минут с момента оплаты клиентом ссылочного номера. После отправки ReferenceNumberPaidNotification транзакция не может быть отменена интегратором.
ВАН
Пользователь может оплатить товар со своего банковского счета. Google запросит у интегратора номер виртуального счета, предоставив номер и инструкции пользователю. Затем пользователь скопирует номер и введет его в свое банковское приложение в дополнение к сумме для перевода.
Интегратору необходимо убедиться, что переведенная сумма соответствует сумме запроса referenceNumberGeneration, а затем уведомить Google о том, что ссылочный номер оплачен.
Как только Google получит ReferenceNumberPaidNotification , Google доставит продукт, и интегратор не сможет отменить транзакцию.
Отправка сообщений между вашими серверами и серверами Google
При отправке сообщений между вашими серверами и серверами Google или наоборот делайте это в соответствии с этими рекомендациями.
Входящий запрос — DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Исходящий ответ — Base64UrlEncode(EncryptWithGooglePublicKey(request))
Запрос Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Ответ Google — DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Вот библиотека PGP и пример на языке Java, показывающий обработку запросов и ответов.
Следуйте идемпотентному поведению
Идемпотентность означает, что вам не следует пытаться повторно обработать любой запрос (например, платеж), который уже был успешно обработан. Вместо этого следует сообщить ответ об успешной обработке.
Почему это важно
Google может повторить некоторые запросы, чтобы убедиться, что состояние на нашей стороне совпадает с состоянием на стороне поставщика. Ваша система не должна думать, что это еще одна транзакция. Поэтому идемпотентность очень важна. Это означает, что интегратор не должен повторно обрабатывать то, что уже было успешно обработано. В таком случае вместо этого следует отправить предыдущий ответ.
Как реализовать идемпотентность
Если Google отправит повторную попытку, идентификатор запроса будет тот же, и контент будет таким же, но метка времени будет другой. Ответьте тем же ответом, который вы отправили ранее. Если ваш первый ответ был 200 (Успех), Google будет ожидать тот же ответ с другой меткой времени.
Если ваш предыдущий ответ был ошибкой (400 или 500 и т. д.), вам следует обработать этот запрос как новый, проверив его еще раз. Это полезно, если ваш сервер был отключен в первый раз, и повторная попытка дает запросу еще один шанс на успешную обработку.
Чтобы узнать больше, смотрите это подробное руководство .
Используйте идентификатор учетной записи платежного интегратора (PIAID)
Для интеграции с Google может потребоваться интеграция с различными подразделениями Google. Например, Google Play — это один объект, другой — YouTube, а третий — Google Ads. Для представления каждой из этих конфигураций будут задействованы разные учетные записи торговцев.
Для сопоставления каждого объекта в Google с каждым аккаунтом продавца Google предоставляет идентификаторы аккаунтов интегратора платежей (PIAID). Пример API-интерфейса FOP для наличных см. в разделеgenerReferenceNumber. Вот пример, в котором используется это сопоставление.
Для сопоставления каждого объекта в Google с каждым аккаунтом продавца Google предоставляет идентификаторы аккаунтов интегратора платежей (PIAID). Пример использования API-интерфейса Cash FOP см. в разделеgenerReferenceNumber . Вот пример, в котором используется это сопоставление.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Обратите внимание на выделенную часть. Здесь необходимы два значения: paymentIntegratorAccountId предоставленный вашим контактным лицом в Google, и ваш торговый счет.
Интегратор также может иметь разные учетные записи в зависимости от каждой обслуживаемой страны. Это может быть связано с различными налоговыми законами и другими различиями в разных странах. В этом случае для каждой страны может быть создан другой PIAID.
API для интеграции
Следующие API обрабатывают создание ссылочного номера и уведомление о платеже.
Следующие API обрабатывают денежные переводы и расчеты.
- Уведомление о денежном переводе
- Выписка о денежном переводеДетали
- AcceptRemittanceStatement /AcceptRemittanceStatement с изменениями
Вам потребуется интегрировать все вышеперечисленные API, чтобы генерировать ссылочные номера и рассчитываться с Google.
Создать ссылочный номер
Google вызывает GenerateReferenceNumber, когда вы инициируете покупку. Мы ожидаем, что вы ответите и укажете ссылочный номер, идентифицирующий транзакцию или счет. Ожидаемая задержка составляет < 3 секунд.
Для операций с наличными ссылочный номер может иметь длину до 12 символов.
URL-адрес: POST https://[your basepath]/v1/generateReferenceNumber
Запрос JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"requestTimestamp": "1561678470395"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"transactionDescription": "Google Play - Tester",
"currencyCode": "USD",
"amount": "10000000"
}
Ответ в формате JSON
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Пример Java
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Отменить ссылочный номер
Google может принять решение аннулировать ссылочный номер и запретить пользователю платить за него. Примером использования является акция, срок действия которой истек. После успешного ответа на этот запрос вы должны убедиться, что ссылочный номер не может быть оплачен.
Если пользователь уже инициировал процесс оплаты, например, поиск ссылочного номера в точке продажи, ваш сервер должен ответить ответом HTTP 423 и ErrorResponse в теле запроса со статусом USER_ACTION_IN_PROGRESS.
URL-адрес: POST https://[your basepath]/v1/cancelReferenceNumber
Запрос JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "51e00f16-36ba-4490-b228-0a670d202206",
"requestTimestamp": "1561678947926"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Ответ в формате JSON
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
После того как платеж принят и транзакция завершена, вашему сервису необходимо уведомить Google о завершении транзакции и доставить продукт пользователю. Как только Google получит это уведомление, Google ожидает, что транзакция будет завершена и не подлежит резервированию.
URL-адрес конечной точки referenceNumberPaidNotification :
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Запрос JSON
{
"requestHeader": {
"requestTimestamp": "1561748625577",
"requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
}
},
"paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
"paymentLocation": {
"brandName": "TestMart",
"locationId": "1234"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"paymentTimestamp": "1561748625577"
}
Ответ в формате JSON
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Осуществить денежные переводы
После того как вы интегрировали API для вашего конкретного ФОП, вы готовы к денежным переводам. Денежные переводы работают одинаково во всех ФОПах.
remittanceStatementNotification
Через два дня после транзакции Google отправит уведомление о денежном переводе , содержащее сводку транзакций, зарегистрированных Google в этот день. Пример уведомления через два дня после транзакции выглядит следующим образом:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Запрос JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-statement-abc",
"requestTimestamp": "1502632800000"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"remittanceStatementSummary": {
"statementDate": "1502607600000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502521199000",
},
"dateDue": "1503212400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
}
}
Обратите внимание на сопоставление totalDueByIntegrator . В этой строке вы можете увидеть чистую сумму задолженности Интегратора (в микронах ). Кроме того, в этом сообщении отображаются дата и тип валюты, а расчетный период представляет собой 00:00:00.000 и 23:59:59.999 самого раннего и последнего дня транзакции соответственно.
Сверка ( remittanceStatementDetails )
Для сверки интегратор вызовет remittanceStatementDetails , чтобы получить список событий, включенных в remittanceStatementNotification.
Google отвечает на запрос remittanceStatementDetails списком событий с разбивкой на страницы. remittanceStatementDetails следует вызывать несколько раз, если общее количество транзакций превышает 1000. Запросы не обязательно выполнять последовательно, их можно распараллелить.
URL-адрес запроса
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Пример тела запроса
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Вот короткий фрагмент более крупного ответа, описывающего два события захвата (транзакции).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Дополнительную информацию см. в remittanceStatementDetails .
acceptRemittanceStatement и acceptRemittanceStatementWithModifications
Интеграторам следует сравнить эти события с событиями, которые они зарегистрировали. Если какие-либо транзакции не совпадают или транзакции отсутствуют, обратитесь в Google для дальнейшего расследования. Если все транзакции совпадают и комиссия за обработку не включает налоги, вызовите метод acceptRemittanceStatement . Если налоги включены, вызовите acceptRemittanceStatementWithModifications .
Метод acceptRemittanceStatement используется при отсутствии налогов на сборы.
Если необходимо включить налог, вызовите acceptRemittanceStatementWithModifications и определите ставку налога. Если ваша налоговая ставка изменится, убедитесь, что она обновлена. После успешного acceptRemittanceStatement инициируйте банковский перевод на счет Google.
URL-адрес запроса для acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Пример тела запроса
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Пример ответа
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
URL-адрес запроса для acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Пример тела запроса
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Пример ответа
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}