Общие сведения

Refundable One Time Payment Code

Overview

Google Standard Payments supports cash-based FOPs (forms of payment) like convenience store purchases (such as a 7-Eleven). At a high level, a user who wants to pay for goods generates a reference number through the Payment integrator. The user then takes this reference number to a convenience store, kiosk, or bank and pays the reference number.

Note: The Cash FOP is also called the Reference Number FOP.

1) The user adds a payment method

2) Then they choose where to pay

3) Finally, they are given payment instructions

Concepts and terminology

{%, если "стандартные платежи" в динамическом_data.request.path %} {% setvar document_base_path %}/standard-pays{% endsetvar %} {% elif "pay/banking-fop-v2" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/banking-fop-v2{% endsetvar %} {% setvar spec_name %}banking-fop-v2{% endsetvar %} {% elif "pay/card-fop-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/card-fop-v1{% endsetvar %} {% setvar spec_name %}card-fop-v1{% endsetvar %} {% elif "pay/card-management-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/card-management-v1{% endsetvar %} {% setvar spec_name %}card-management-v1{% endsetvar %} {% elif "pay/carriers-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/carriers-v1{% endsetvar %} {% setvar spec_name %}carriers-v1{% endsetvar %} {% elif "pay/carrier-wallets-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/carrier-wallets-v1{% endsetvar %} {% setvar spec_name %}carrier-wallets-v1{% endsetvar %} {% elif "pay/e-wallets-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/e-wallets-v1{% endsetvar %} {% setvar spec_name %}e-wallets-v1{% endsetvar %} {% elif "pay/chargeback-alert-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/chargeback-alert-v1{% endsetvar %} {% setvar spec_name %}chargeback-alert-v1{% endsetvar %} {% elif "pay/golden-fop-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/golden-fop-v1{% endsetvar %} {% setvar spec_name %}golden-fop-v1{% endsetvar %} {% elif "pay/facilitated-transaction-event-v2" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/facilitated-transaction-event-v2{% endsetvar %} {% setvar spec_name %}facilitated-transaction-event-v2{% endsetvar %} {% elif "pay/india-cards-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/india-cards-v1{% endsetvar %} {% setvar spec_name %}india-cards-v1{% endsetvar %} {% elif "pay/issuers/apis/push-provisioning/server" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/issuers/apis/push-provisioning/server {% endsetvar %} {% setvar spec_name %}push-provisioning-v1{% endsetvar %} {% elif "pay/одноразового платежа-код-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/one-time-paying-code-v1{% endsetvar %} {% setvar spec_name %}код-разового платежа-v1{% endsetvar %} {% elif "pay/redirect-fop-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/redirect-fop-v1{% endsetvar %} {% setvar spec_name %}redirect-fop-v1{% endsetvar %} {% elif "pay/redirect-pay-token-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/redirect-pay-token-v1{% endsetvar %} {% setvar spec_name %}redirect-pay-token-v1{% endsetvar %} {% elif "pay/refundable-one-time-paying-code-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/refundable-one-time-paying-code-v1{% endsetvar %} {% setvar spec_name %}возвратный-одноразовый-платеж-код-v1{% endsetvar %} {% elif "pay/refundable-one-time-paying-code-v2" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/refundable-one-time-paying-code-v2{% endsetvar %} {% setvar spec_name %}refundable-одноразовый-код-платежа-v2{% endsetvar %} {% elif "pay/value-on-device-fop-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/value-on-device-fop-v1{% endsetvar %} {% setvar spec_name %}value-on-device-fop-v1{% endsetvar %} {% elif "pay/virtual-cards-v1" в динамическом_data.request.path %} {% setvar document_base_path %}/pay/virtual-cards-v1{% endsetvar %} {% setvar spec_name %}virtual-cards-v1{% endsetvar %} {% конечный %}

Символы и обозначения

Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «СЛЕДУЕТ», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ДОПОЛНИТЕЛЬНО» в этих документах. интерпретироваться, как описано в RFC 2119 .

Временные метки

Все временные метки представлены в миллисекундах с эпохи Unix (1 января 1970 г.) в формате UTC.

Например:

• 23 апреля 2019 г., 20:23:25 GMT = 1556051005000 миллисекунд
• 16 августа 2018 г., 12:28:35 GMT = 1534422515000 миллисекунд.

Суммы

Денежные значения в этом API представлены в формате «микро», который является стандартом Google. Микро — это целочисленный формат с фиксированной точностью. Чтобы представить денежную стоимость в микромах, умножьте стоимость стандартной валюты на 1 000 000.

Например:

• 1,23 доллара США = 1 230 000 микродолларов США
• 0,01 доллара США = 10 000 микродолларов США

Идемпотентность

Все вызовы методов в этом API должны иметь идемпотентное поведение. Google будет время от времени повторять запросы, чтобы гарантировать, что транзакции находятся в одном и том же состоянии с обеих сторон. Интеграторам не следует пытаться повторно обработать уже успешно обработанный запрос. Вместо этого следует сообщить ответ об успешной обработке. Все методы имеют общий RequestHeader , который содержит requestId. Этот requestId является ключом идемпотентности для всех вызовов.

Любой нетерминальный ответ (не HTTP 200-успех) не должен обрабатываться идемпотентно. Таким образом, запрос, который ранее получил 400 (неверный запрос/неудачное предварительное условие), при повторном вызове не должен идемпотентно возвращать 400, его необходимо переоценить. При повторной оценке он может вернуть 400 или быть успешно обработан.

Дополнительную информацию об идемпотентности смотрите в этом подробном руководстве .

Интегратор

Компания, которая использует платежную платформу Google для своего бизнеса. Это может быть внутренний (1P), например Youtube или AdWords. Это также может быть внешний (3P) бизнес, желающий интегрировать свой сервис для работы с экосистемой Google.

ФОП

Форма оплаты. Это более общий инструмент, чем инструмент. Visa, MasterCard и PayPal являются ФОПами.

Инструмент

Конкретный экземпляр формы оплаты конкретным клиентом. Например, кредитная карта пользователя или его учетная запись PayPal. Токенизированный FOP для конкретного клиента также является инструментом, поскольку он представляет собой экземпляр формы платежа для этого клиента, надежно хранящийся в нашей системе.

Токен

Представление в системе Google способа оплаты конкретного пользователя. Поскольку токен содержит всю информацию, необходимую для совершения покупки, он также является инструментом. Сюда может входить такая информация, как номер счета пользователя у своего интегратора.

Key flows

Google uses two key flows to create and pay these reference numbers:

1. Generate Reference Number Flow.
2. Pay Reference Number Flow.

Later, reconciliation and settlement from resulting purchases are handled by the remittance flow.

The diagram below illustrates each of these flows.

Cash FOP overview

The first two flows are described in more detail in the following sections. See the Remittance flow page if you want to know more about that flow.

Generate reference number

The purpose of the generate reference number flow is to create and exchange an identifier (reference number) that both Google and the integrator can use to identify a purchase. The user can then use this reference number at a convenience store, kiosk, or bank to complete the purchase. This identifier is generated by the integrator at Google's request by calling the generateReferenceNumber method. The request for generation of the reference number includes an amount and a transaction description.

The following diagram illustrates how a reference number is generated and sent to the customer with instructions.

Generate reference number flow

Here is a list of the objects and what they represent:

• User: This is the person who wants to pay for something using this form of payment.
• Google UI: This is the interface where the User makes their purchase. It could be through the web or through an app.
• Google Server: The backend server at Google that requests the generation of the reference number and creates payment instructions for the user.
• Payment Integrator Server: The backend server of the Payment Integrator that keeps track of the payment details and generates the reference number.

This flow begins with the user who wants to use this cash form of payment.

1. The User accesses the Google UI which sends sends a request for a reference number.
2. The Google UI sends a message to the Google Server that it needs a reference number (getReferenceNumber).
3. The Google Server asks the Payment Integrator Server to generate a reference number (generateReferenceNumber).
4. The Payment Integrator Server generates and sends the reference number to the Google Server.
5. The Google Server creates payment instructions to go along with the reference number. Then it sends this information to the Google UI.
6. The Google UI sends these instructions and reference number to the User.

Notes on reference numbers

Reference numbers can only be paid once, and they can be cancelled through the cancel reference number flow. Also, reference numbers must be alphanumeric, and it must support multiple display formats.

In addition to displaying the reference number, Google's UIs can optionally represent the reference number in the Code 128 format (a barcode format). Other barcode formats can be supported by request.

Pay Reference Number

The user will use this reference number at a convenience store, kiosk, or bank to identify the purchase the user wants to pay for. The integrator should have the user confirm the purchase being paid by displaying the purchase amount, date, and transaction description prior to paying.

Once the user chooses to pay, they must pay in full, and only pay once. This API does not support over or under payments on a single reference number. Multiple payments to a single reference number is also not supported.

Once the user pays, the integrator must immediately notify Google that this reference number has been paid via the referenceNumberPaidNotification method. By calling this method within seconds of the user physically paying, the integrator allows the user to quickly receive their goods. (This call can be added to a queue if the network is down.)

Once paid, the reference number and amount will be included in the remittance statement sent on T+2 days.

Note: If Google returns an error on referenceNumberPaidNotification, your server should retry the request indefinitely with exponential backoff and you should reach out to your Google point of contact to notify them of the issue.

Here is a sequence diagram that illustrates the payment of a reference number.

Pay reference number flow

The objects in the diagram represent the following:

• User: This is the person who wants to pay for something using this form of payment.
• Convenience Store: The location where the user makes their payment using the reference number and instructions given, such as a convenience store.
• Payment Integrator Server: The backend server of the Payment Integrator that keeps track of the payment details.
• Google Server: The backend server at Google that requests the generation of the reference number and creates payment instructions for the user.

This flow begins with the user who goes to a convenience store in order to make a payment according to the instructions given to them.

1. The User goes to a Convenience Store to make a payment.
2. After the transaction is complete, the convenience store notifies the payment integrator of payment.
3. The Payment Integrator Server sends a success message to the Convenience Store.
4. The Convenience Store conveys that the transaction was a success to the User, and the goods will be delivered to the User soon.
5. The Payment Integrator Server sends a message to Google’s Server that the reference number has been paid (referenceNumberPaidNotification). This step must not block step 4.
6. The Google Server responds with a message of success to the Payment Integrator Server.

Cancel reference number

Reference numbers can be cancelled by Google. If Google cancels a reference number, the cancelReferenceNumber method will be called. Upon successful return of this call, it is invalid to pay that reference number, and the integrator must refuse payment for this number. Upon success of this call, all future calls to the referenceNumberPaidNotification will fail.

If the payment process has already started, for example if the user has entered their reference number into a kiosk but has not yet paid, the integrator should return a HTTP 423 response code with ErrorResponse containing [USER_ACTION_IN_PROGRESS][google.standardpayments.v1.ErrorResponse].

Refund

Paid reference numbers can be refunded by Google using the request ID of the original generateReferenceNumber call (note that refunds will NOT use the reference number). If Google refunds a reference number, the refund method will be called. This method can be called multiple times with amounts totalling less than or equal to the original paid amount.

Next: Remittance flow