Reference Number Use Case
Stay organized with collections
Save and categorize content based on your preferences.
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. The user then takes this reference number to a convenience store, kiosk, or bank and pays the reference number.
Cash FOP 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:
- Authentication flow
- Association flow
- Purchase flow (Same as Cash FOP)
- Refund flow
- Remittance flow
Purchase flow will be the same as Cash FOP Purchase flow.
Example of an integration using web redirect authentication.
Authentication flow
API implemented by integrator: Web Authentication.
Association flow
API implemented by integrator: associateAccount on Payment Integrator Hosted Tokenized FOP API.
Purchase flow
API implemented by integrator: generateReferenceNumber and cancelReferenceNumber on Payment Integrator Hosted Tokenized FOP API.
API implemented by Google: referenceNumberPaidNotification on Google Hosted Tokenized FOP API.
Refund flow
API implemented by integrator: refund on Payment Integrator Hosted Tokenized FOP API.
Remittance flow
API implemented by integrator: See Payment Integrator Hosted Remittance API.
API implemented by Google: See Google Hosted Remittance API.
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. After successful authentication, the user is redirected back to Google. And then Google will call associateAccount. The requestId
in authenticationResponse
will be the authenticationRequestId
of associateAccount request. After successful association, Google stores googlePaymentToken
(GPT) and other metadata as an instrument for the user.
Create Instrument - Authentication flow

Create Instrument - Association flow

Generate reference number
When the user wants to buy goods/services with the instrument, Google calls generateReferenceNumber with GPT. The requestId
within the header of the generateReferenceNumber request will be used to identify the transaction for related APIs.

Pay reference number
After the user pays the reference number offline, integrator will call referenceNumberPaidNotification. The requestId
within the header of the generateReferenceNumber request will be the generateReferenceNumberRequestId
of referenceNumberPaidNotification request.

Cancel a transaction
If the user decides to cancel the transaction before paying, Google will call cancelReferenceNumber. The requestId
within the header of the generateReferenceNumber request will be the generateReferenceNumberRequestId
of cancelReferenceNumber request.
Refund a transaction
After the reference number is paid, if the user wants the money back, Google will call refund. The requestId
within the header of the generateReferenceNumber request will be the transactionId
of refund request.

Remittance
Based on contract, Google will call remittanceStatementNotification to notify integrator when statement is ready. Then, integrator will call Google Hosted Remittance API to perform reconciliation.
All rights reserved. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-09-03 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-09-03 UTC."],[[["\u003cp\u003eTokenized First Open Payment (FOP) enables users to generate reference numbers for offline payments at convenience stores, kiosks, or banks, supporting refunds unlike Cash FOP.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves authentication, association, purchase (same as Cash FOP), refund, and remittance flows, with detailed API specifications provided for each.\u003c/p\u003e\n"],["\u003cp\u003eA user is authenticated through a web redirect, then associated with a Google Payment Token (GPT) stored as an instrument for future transactions.\u003c/p\u003e\n"],["\u003cp\u003eGoogle interacts with the integrator's APIs for generating reference numbers, notifying about payments, canceling transactions, processing refunds, and managing remittances.\u003c/p\u003e\n"],["\u003cp\u003eThis system ensures secure and traceable transactions, offering flexibility for both users and integrators in handling offline payments.\u003c/p\u003e\n"]]],["Tokenized FOP allows users to pay using a reference number generated by a payment integrator. This system involves authentication, association, purchase, refund, and remittance flows. Integrators use APIs like `associateAccount`, `generateReferenceNumber`, `cancelReferenceNumber`, and `refund`. Google uses `referenceNumberPaidNotification`. Google redirects users for web authentication, then calls APIs to associate accounts and handle transactions. The `requestId` is used to link transactions across different flows. Unlike Cash FOP, Tokenized FOP requires association and supports refunds.\n"],null,["# Reference Number Use Case\n\nOverview\n--------\n\nTokenized FOP can support reference number use case. A user who wants to pay for goods generates a reference number through the [Payment integrator](/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.\n\n[Cash FOP](/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.\n\nAt a high level, integration involves these flows:\n\n1. [Authentication flow](/standard-payments/concepts/tokenized_fop/authentication-flow)\n2. [Association flow](/standard-payments/concepts/tokenized_fop/association-flow)\n3. [Purchase flow (Same as Cash FOP)](/standard-payments/concepts/cash/intro)\n4. [Refund flow](/standard-payments/concepts/tokenized_fop/refund-flow)\n5. [Remittance flow](/standard-payments/concepts/tokenized_fop/remittance-flow)\n\nPurchase flow will be the same as Cash FOP Purchase flow.\n\nExample of an integration using web redirect authentication.\n------------------------------------------------------------\n\n### Related APIs\n\n#### Authentication flow\n\nAPI implemented by integrator: [Web Authentication](/standard-payments/v1/payment-integrator-hosted-api/client-to-server-api/web-auth-api).\n\n#### Association flow\n\nAPI implemented by integrator: [associateAccount](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/associateAccount) on [Payment Integrator Hosted Tokenized FOP API](/standard-payments/payment-integrator-tokenized-fop-api-v2).\n\n#### Purchase flow\n\nAPI implemented by integrator: [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) and [cancelReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber) on [Payment Integrator Hosted Tokenized FOP API](/standard-payments/payment-integrator-tokenized-fop-api-v2).\n\nAPI implemented by Google: [referenceNumberPaidNotification](/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification) on [Google Hosted Tokenized FOP API](/standard-payments/google-tokenized-fop-api-v2).\n\n#### Refund flow\n\nAPI implemented by integrator: [refund](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund) on [Payment Integrator Hosted Tokenized FOP API](/standard-payments/payment-integrator-tokenized-fop-api-v2).\n\n#### Remittance flow\n\nAPI implemented by integrator: See [Payment Integrator Hosted Remittance API](/standard-payments/payment-integrator-remittance-api-v2).\n\nAPI implemented by Google: See [Google Hosted Remittance API](/standard-payments/google-remittance-api-v2).\n\n### How all flows fit together\n\n#### Create Instrument\n\nOn Google's UI, a user is redirected to an integrator hosted web page to do [Web Authentication](/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](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/associateAccount). The `requestId` in [`authenticationResponse`](/standard-payments/v1/authentication-api/authenticationResponse) will be the `authenticationRequestId` of [associateAccount](/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.\n\n##### Create Instrument - Authentication flow\n\n##### Create Instrument - Association flow\n\n#### Generate reference number\n\nWhen the user wants to buy goods/services with the instrument, Google calls [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) with GPT. The `requestId` within the header of the [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be used to identify the transaction for related APIs.\n\n#### Pay reference number\n\nAfter the user pays the reference number offline, integrator will call [referenceNumberPaidNotification](/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification). The `requestId` within the header of the [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `generateReferenceNumberRequestId` of [referenceNumberPaidNotification](/standard-payments/google-tokenized-fop-api-v2/v2/google-tokenized/referenceNumberPaidNotification) request.\n\n#### Cancel a transaction\n\nIf the user decides to cancel the transaction before paying, Google will call [cancelReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber). The `requestId` within the header of the [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `generateReferenceNumberRequestId` of [cancelReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/cancelReferenceNumber) request.\n\n#### Refund a transaction\n\nAfter the reference number is paid, if the user wants the money back, Google will call [refund](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund). The `requestId` within the header of the [generateReferenceNumber](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/payment-integrator-tokenized/generateReferenceNumber) request will be the `transactionId` of [refund](/standard-payments/payment-integrator-tokenized-fop-api-v2/v2/TopLevel/refund) request.\n\n#### Remittance\n\nBased on contract, Google will call [remittanceStatementNotification](/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](/standard-payments/google-remittance-api-v2) to perform reconciliation."]]