# Reference Number Use Case

## Overview

Tokenized FOP can support reference number use case. A user who wants to pay for goods generates a reference number through the [Payment integrator](https://developers.google.com/standard-payments/reference/glossary#payment_integrator). The user then takes this reference number to a convenience store, kiosk, or bank and pays the reference number.

[Cash FOP](https://developers.google.com/standard-payments/concepts/cash/intro) also supports reference number use case. The major difference between Tokenized FOP and Cash FOP is that, Tokenized FOP requires Association and supports Refunds, Cash FOP doesn't require Association and doesn't support Refunds. This document describes how the integration will work for Reference Number Use Case.

At a high level, integration involves these flows:

1. [Authentication flow](https://developers.google.com/standard-payments/concepts/tokenized_fop/authentication-flow)
2. [Association flow](https://developers.google.com/standard-payments/concepts/tokenized_fop/association-flow)
3. [Purchase flow (Same as Cash FOP)](https://developers.google.com/standard-payments/concepts/cash/intro)
4. [Refund flow](https://developers.google.com/standard-payments/concepts/tokenized_fop/refund-flow)
5. [Remittance flow](https://developers.google.com/standard-payments/concepts/tokenized_fop/remittance-flow)

Purchase flow will be the same as Cash FOP Purchase flow.

## Example of an integration using web redirect authentication.

### Related APIs

#### Authentication flow

API implemented by integrator: [Web Authentication](https://developers.google.com/standard-payments/v1/payment-integrator-hosted-api/client-to-server-api/web-auth-api).

#### Association flow

API implemented by integrator: [associateAccount](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/associateAccount) on [Payment Integrator Hosted Tokenized FOP API](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2).

#### Purchase flow

API implemented by integrator: [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) and [cancelReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber) on [Payment Integrator Hosted Tokenized FOP API](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2).

API implemented by Google: [referenceNumberPaidNotification](https://developers.google.com/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification) on [Google Hosted Tokenized FOP API](https://developers.google.com/standard-payments/google-tokenized-fop-api-v2).

#### Refund flow

API implemented by integrator: [refund](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund) on [Payment Integrator Hosted Tokenized FOP API](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2).

#### Remittance flow

API implemented by integrator: See [Payment Integrator Hosted Remittance API](https://developers.google.com/standard-payments/payment-integrator-remittance-api-v2).

API implemented by Google: See [Google Hosted Remittance API](https://developers.google.com/standard-payments/google-remittance-api-v2).

### How all flows fit together

#### Create Instrument

On Google's UI, a user is redirected to an integrator hosted web page to do [Web Authentication](https://developers.google.com/standard-payments/v1/payment-integrator-hosted-api/client-to-server-api/web-auth-api). After successful authentication, the user is redirected back to Google. And then Google will call [associateAccount](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/associateAccount). The `requestId` in [`authenticationResponse`](https://developers.google.com/standard-payments/v1/authentication-api/authenticationResponse) will be the `authenticationRequestId` of [associateAccount](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/associateAccount) request. After successful association, Google stores `googlePaymentToken`(GPT) and other metadata as an instrument for the user.

##### Create Instrument - Authentication flow

![Web Authentication Flow](https://developers.google.com/standard-payments/shared/assets/flows/tokenized-fop-redirect-authentication-v1/web-auth-flow.png)

##### Create Instrument - Association flow

![Association flow diagram](https://developers.google.com/standard-payments/shared/assets/flows/tokenized-fop-association-v1/High-Level-Association.png)

#### Generate reference number

When the user wants to buy goods/services with the instrument, Google calls [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) with GPT. The `requestId` within the header of the [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be used to identify the transaction for related APIs.

![Cash Generate Reference Number](https://developers.google.com/static/standard-payments/shared/assets/specs/one-time-payment-code-v1/cash-gen-ref-number.png)

#### Pay reference number

After the user pays the reference number offline, integrator will call [referenceNumberPaidNotification](https://developers.google.com/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification). The `requestId` within the header of the [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `generateReferenceNumberRequestId` of [referenceNumberPaidNotification](https://developers.google.com/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification) request.

![Pay reference number flow](https://developers.google.com/static/standard-payments/shared/assets/specs/one-time-payment-code-v1/pay-ref-number.png)

#### Cancel a transaction

If the user decides to cancel the transaction before paying, Google will call [cancelReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber). The `requestId` within the header of the [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `generateReferenceNumberRequestId` of [cancelReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber) request.

#### Refund a transaction

After the reference number is paid, if the user wants the money back, Google will call [refund](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund). The `requestId` within the header of the [generateReferenceNumber](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `transactionId` of [refund](https://developers.google.com/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund) request.

![Refund flow](https://developers.google.com/standard-payments/shared/assets/flows/tokenized-fop-refund-v1/refund-flow.png)

#### Remittance

Based on contract, Google will call [remittanceStatementNotification](https://developers.google.com/standard-payments/payment-integrator-remittance-api-v2/v2/TopLevel/remittanceStatementNotification) to notify integrator when statement is ready. Then, integrator will call [Google Hosted Remittance API](https://developers.google.com/standard-payments/google-remittance-api-v2) to perform reconciliation.