Method: generateReferenceNumber

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 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 (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "transactionDescription": string,
  "currencyCode": string,
  "amount": string,
  "userInfo": {
    object (UserInfo)
  }
}
Fields
requestHeader

object (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 (Int64Value format)

REQUIRED: The amount of the purchase, in micros of the currency unit.
userInfo

object (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.

Possible response messages
HTTP 200 Status

object (GenerateReferenceNumberResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

UserInfo

Information about the user making the request.

JSON representation 
{

  // Union field user can be only one of the following:
  "noUserInfo": {
    object (Empty)
  },
  "brazilUserInfo": {
    object (BrazilUserInfo)
  }
  // End of list of possible types for union field user.
}
Fields
Union field user. Information about a user in a specific country/region. user can be only one of the following:
noUserInfo

object (Empty)

No user information is provided.
brazilUserInfo

object (BrazilUserInfo)

Information about a Brazil user.

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

JSON representation 
{
  "fullName": string,

  // Union field userLegalAddress can be only one of the following:
  "noLegalAddress": {
    object (Empty)
  },
  "legalAddress": {
    object (Address)
  }
  // End of list of possible types for union field userLegalAddress.

  // Union field taxId can be only one of the following:
  "cpf": string,
  "cnpj": string
  // End of list of possible types for union field taxId.
}
Fields
fullName

string

REQUIRED: The user's full name.
Union field userLegalAddress. REQUIRED: The user's legal address. userLegalAddress can be only one of the following:
legalAddress

object (Address)

The user's legal address.
Union field taxId. Taxpayer Identification Number. taxId can be only one of the following:
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).

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 (ResponseHeader)
  },

  // Union field result can be only one of the following:
  "referenceNumber": string,
  "displayableReferenceNumber": {
    object (DisplayableReferenceNumber)
  }
  // End of list of possible types for union field result.
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
Union field result. Reference number created by the integrator. result can be only one of the following:
referenceNumber
(deprecated)

string

DEPRECATED: Reference number created by the integrator.
displayableReferenceNumber

object (DisplayableReferenceNumber)

Reference number created by the integrator.

DisplayableReferenceNumber

This message contains a reference number for a transaction.

JSON representation 
{

  // Union field display_form can be only one of the following:
  "printableString": string,
  "barcodeContents": string,
  "barcodeWithPrintableString": {
    object (BarcodeWithPrintableString)
  }
  // End of list of possible types for union field display_form.
}
Fields
Union field display_form. Different display forms of the reference number. display_form can be only one of the following:
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 (BarcodeWithPrintableString)

Populate this field if we need to show both the reference number and a barcode to the users.

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.