Method: generateReferenceNumber

  • Generates a reference number and registers payment information like description, timestamp, and amount with the integrator.

  • The paymentIntegratorAccountId and referenceNumber uniquely identify the transaction for later use.

  • amount is expressed in micro currency units (micros), for example, $2 is represented as 2000000.

  • The response can include a displayable reference number in various formats like printable string or barcode.

  • Error responses are of type ErrorResponse with relevant HTTP status codes.

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/refundable-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)

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