Method: cancelReferenceNumber

  • This API cancels a previously generated reference number, preventing future payments using it.

  • The request body requires the payment integrator account ID and the reference number to be cancelled.

  • A successful cancellation results in a "SUCCESS" response, while other results indicate issues like the reference number being already paid or pending a transaction.

  • Integrators should expect a referenceNumberPaidNotification call if the reference number was already paid before cancellation.

  • Error responses with specific HTTP status codes and error codes are provided for various failure scenarios.

Cancels a reference number by invalidating it in the integrators system and preventing future payments.

Only a reference number that was previously created by calling generateReferenceNumber is subject to cancellation.

An example requests looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502223797000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "referenceNumber": "aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA"
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1502223798000"
  },
  "result": "SUCCESS"
}

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "referenceNumber": string
}
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.
referenceNumber

string

REQUIRED: The reference number that should be cancelled.

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 (CancelReferenceNumberResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

CancelReferenceNumberResponse

Response object for the cancel reference number method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

enum (CancelReferenceNumberResultCode)

REQUIRED: The result of this call

CancelReferenceNumberResultCode

Result codes for cancel reference number

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS Reference number successfully cancelled.
REFERENCE_NUMBER_ALREADY_PAID Reference number has already been paid. Google should expect a call to referenceNumberPaidNotification for this reference number soon.
REFERENCE_NUMBER_PENDING_TRANSACTION

DEPRECATED Indicates the reference number has been entered into a kiosk but has not been paid yet, reference number is pending transaction completion