- [HTTP request](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#body.HTTP_TEMPLATE)
- [Request body](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#body.request_body)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#body.response_body)
- [UserInfo](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#UserInfo)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#UserInfo.SCHEMA_REPRESENTATION)
- [Empty](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Empty)
- [BrazilUserInfo](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BrazilUserInfo)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BrazilUserInfo.SCHEMA_REPRESENTATION)
- [Address](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Address)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Address.SCHEMA_REPRESENTATION)
- [GenerateReferenceNumberResponse](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#GenerateReferenceNumberResponse)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#GenerateReferenceNumberResponse.SCHEMA_REPRESENTATION)
- [DisplayableReferenceNumber](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#DisplayableReferenceNumber)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#DisplayableReferenceNumber.SCHEMA_REPRESENTATION)
- [BarcodeWithPrintableString](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BarcodeWithPrintableString)
  - [JSON representation](https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BarcodeWithPrintableString.SCHEMA_REPRESENTATION)

Creates a reference number and registers payment information (description, timestamp) with the integrator.

The combination of the `paymentIntegratorAccountId` from the request and the `referenceNumber` from the response form a unique key that identifies the transaction for subsequent operations on this transaction.

The `amount` field is defined in *micro currency units* (micros), which means that $2 would be represented with the digit `2` followed by six digits `0`, resulting in `2000000`.

If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type `https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/ErrorResponse`.

An example request looks like:


    {
      "requestHeader": {
        "protocolVersion": {
          "major": 1,
          "minor": 0,
          "revision": 0
        },
        "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
        "requestTimestamp": "1502220196077"
      },
      "paymentIntegratorAccountId": "InvisiCashUSA_USD",
      "transactionDescription": "Google - Music",
      "userInfo": {
        "noUserInfo": {}
      },
      "currencyCode": "USD",
      "amount": "2000000"
    }

An example response looks like:


    {
      "responseHeader": {
        "responseTimestamp": "1502220197000"
      },
      "displayableReferenceNumber": {
        "barcodeWithPrintableString": {
          "printableString": "1122334455",
          "barcodeContents": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
        }
      }
    }

### HTTP request

`POST https://www.integratorhost.example.com/integrator-base-path/one-time-payment-code-v1/generateReferenceNumber`

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "requestHeader": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/RequestHeader`) }, "paymentIntegratorAccountId": string, "transactionDescription": string, "currencyCode": string, "amount": string, "userInfo": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#UserInfo`) } } ``` |

| Fields ||
|---|---|
| `requestHeader` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/RequestHeader`)`` **REQUIRED**: Common header for all requests. |
| `paymentIntegratorAccountId` | `string` **REQUIRED**: This is the payment integrator account identifier that identifies contractual constraints around this transaction. |
| `transactionDescription` | `string` **REQUIRED** : This is the description of the transaction that can be put on the customer's statement. Localized to the userLocale found in the `requestHeader`. This format can be changed without notice and must never be parsed. |
| `currencyCode` | `string` **REQUIRED**: ISO 4217 3-letter currency code. |
| `amount` | `string (https://developers.google.com/discovery/v1/type-format format)` **REQUIRED** : The amount of the purchase, in [micros](https://developers.google.com/pay/one-time-payment-code-v1/reference/glossary#micros "What are micros?") of the currency unit. |
| `userInfo` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#UserInfo`)`` **REQUIRED**: Information about the user making the request. |

### Response body

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an `ErrorResponse`, consult the `ErrorResponse` object and [HTTP status codes documentation](https://developers.google.com/pay/one-time-payment-code-v1/guides/connectivity/protocol-standards#http_status_codes).

| Possible response messages ||
|---|---|
| HTTP 200 Status | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#GenerateReferenceNumberResponse`)`` |
| HTTP 4XX / 5XX Status | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/ErrorResponse`)`` |
| End of mutually exclusive fields. ||

## UserInfo

Information about the user making the request.

| JSON representation |
|---|
| ``` { // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "noUserInfo": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Empty`) }, "brazilUserInfo": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BrazilUserInfo`) } // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| **REQUIRED**: Information about a user in a specific country/region. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `noUserInfo` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Empty`)`` No user information is provided. |
| `brazilUserInfo` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BrazilUserInfo`)`` Information about a Brazil user. |
| End of mutually exclusive fields. ||

## Empty

This type has no fields.
This object is used for extensibility because booleans and enumerations often need to be extended with extra data. The implementer uses it to determine presence. The enumeration this represents may be extended to contain data in future versions.

The JSON representation for `Empty` is empty JSON object `{}`.

## BrazilUserInfo

Information about a Brazil user.

| JSON representation |
|---|
| ``` { "fullName": string, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "noLegalAddress": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Empty`) }, "legalAddress": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Address`) } // End of mutually exclusive fields. // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "cpf": string, "cnpj": string // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `fullName` | `string` **REQUIRED**: The user's full name. |
| **REQUIRED**: The user's legal address. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `noLegalAddress` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Empty`)`` No legal address is provided. |
| `legalAddress` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#Address`)`` The user's legal address. |
| End of mutually exclusive fields. ||
| **REQUIRED**: Taxpayer Identification Number. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `cpf` | `string` The CPF number (Cadastro de Pessoas Físicas, Portuguese for "Natural Persons Register") is the Brazilian individual taxpayer registry identification. |
| `cnpj` | `string` CNPJ (short for Cadastro Nacional da Pessoa Jurídica in Portuguese, or National Registry of Legal Entities) is an identification number issued to Brazilian companies by the Department of Federal Revenue of Brazil (in Portuguese, Secretaria da Receita Federal). |
| End of mutually exclusive fields. ||

## Address

Structure holding information about a physical address.

| JSON representation |
|---|
| ``` { "addressLine": [ string ], "localityName": string, "administrativeAreaName": string, "postalCodeNumber": string, "countryCode": string } ``` |

| Fields ||
|---|---|
| `addressLine[]` | `string` **OPTIONAL**: This holds unstructured Address text. |
| `localityName` | `string` **OPTIONAL**: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine. Examples: US city, IT comune, UK post town. |
| `administrativeAreaName` | `string` **OPTIONAL**: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture." |
| `postalCodeNumber` | `string` **OPTIONAL**: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ". |
| `countryCode` | `string` **OPTIONAL**: Customer address country code, expected to be ISO-3166-1 Alpha-2. |

## GenerateReferenceNumberResponse

Response object for the generate reference number method.

| JSON representation |
|---|
| ``` { "responseHeader": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/ResponseHeader`) }, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "referenceNumber": string, "displayableReferenceNumber": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#DisplayableReferenceNumber`) } // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `responseHeader` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/ResponseHeader`)`` **REQUIRED**: Common header for all responses. |
| **REQUIRED**: The reference number created by the integrator. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `referenceNumber (deprecated)` | `string` > [!WARNING] > Instead of this field, all new integrations should use displayableReferenceNumber. **DEPRECATED**: Reference number created by the integrator. |
| `displayableReferenceNumber` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#DisplayableReferenceNumber`)`` Reference number created by the integrator. |
| End of mutually exclusive fields. ||

## DisplayableReferenceNumber

This message contains a reference number for a transaction.

| JSON representation |
|---|
| ``` { // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "printableString": string, "barcodeContents": string, "barcodeWithPrintableString": { object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BarcodeWithPrintableString`) } // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| **REQUIRED**: Different display forms of the reference number. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `printableString` | `string` The string value of the reference number. Normally, this string should not contain any whitespace. When displaying this string on UI, Google may insert whitespace for better readability. There is no max length limitation. However, the user/cashier may need to type in this string. The shorter the better. Populate this field if we only need to show the reference number to the users. |
| `barcodeContents` | `string` The contents to encode in a barcode. Google's UIs can represent the reference number in the Code 128 format or QR code format. Other barcode formats can be supported by request. Populate this field if we only need to show a barcode to the users. |
| `barcodeWithPrintableString` | ``object (`https://developers.google.com/pay/one-time-payment-code-v1/payment-integrator-one-time-payment-code-api/generateReferenceNumber#BarcodeWithPrintableString`)`` Populate this field if we need to show both the reference number and a barcode to the users. |
| End of mutually exclusive fields. ||

## BarcodeWithPrintableString

This message contains a printable string and a barcode contents for the reference number.

| JSON representation |
|---|
| ``` { "printableString": string, "barcodeContents": string } ``` |

| Fields ||
|---|---|
| `printableString` | `string` **REQUIRED** The string value of the reference number. Normally, this string should not contain any whitespace. When displaying this string on UI, Google may insert whitespace for better readability. There is no max length limitation. However, the user/cashier may need to type in this string. The shorter the better. |
| `barcodeContents` | `string` **REQUIRED** The contents to encode in a barcode. Google's UIs can represent the reference number in the Code 128 format or QR code format. Other barcode formats can be supported by request. |