Method: generateReferenceNumber

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

The combination of requestId and paymentIntegratorAccountId within the header is the idempotency key and uniquely identifies this transaction. All mutations on this transaction populate the requestId value in their generateReferenceNumberRequestId field or transactionId field.

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": 2
    },
    "requestId": "cmVxdWVzdDE",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "InvisiCashUSA_USD"
  },
  "googlePaymentToken": {
    "issuerId": {
      "value": "invisicash"
    },
    "token": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ"
  },
  "transactionDescription": "Google - Music",
  "amount": {
    "amountMicros": "728000000",
    "currencyCode": "USD"
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481907920760"
    }
  },
  "result": {
    "success": {
      "displayableReferenceNumber": {
        "barcodeWithPrintableString": {
          "printableString": "1122334455",
          "barcodeContents": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
        }
      }
    }
  }
}

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "googlePaymentToken": {
    object (GooglePaymentToken)
  },
  "transactionDescription": string,
  "amount": {
    object (Amount)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
googlePaymentToken

object (GooglePaymentToken)

REQUIRED: This is the token that both companies will use to identify the account for purchases between each other.
transactionDescription

string

REQUIRED: This is the description of the transaction that can be put on the customer's statement. Localized to the user's preferred language. This format can be changed without notice and must never be parsed.
amount

object (Amount)

REQUIRED: The amount of the purchase.

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)

GenerateReferenceNumberResponse

Response object for the generateReferenceNumber method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (GenerateReferenceNumberResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (GenerateReferenceNumberResult)

REQUIRED: Result of this generateReferenceNumber call.

GenerateReferenceNumberResult

Result of this generateReferenceNumber call.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "googlePaymentTokenInvalidatedByUser": {
    object (GooglePaymentTokenInvalidatedByUser)
  },
  "accountClosed": {
    object (AccountClosed)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. Result of this generateReferenceNumber call. result can be only one of the following:
success

object (SuccessDetails)

Reference number is generated.
googlePaymentTokenInvalidatedByUser

object (GooglePaymentTokenInvalidatedByUser)

The account is active, but the GPT has been invalidated by the user on the integrator's side.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
accountClosed

object (AccountClosed)

The user's account held with the integrator has been closed.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.

SuccessDetails

Results are within this message.

JSON representation 
{
  "displayableReferenceNumber": {
    object (DisplayableReferenceNumber)
  }
}
Fields
displayableReferenceNumber

object (DisplayableReferenceNumber)

REQUIRED: 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.

GooglePaymentTokenInvalidatedByUser

The account is active, but the GPT has been invalidated by the user on the integrator's side.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

OPTIONAL: Raw result of this event. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact decline code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned.