Method: referenceNumberPaymentStatusNotification

RECOMMENDED: Notifies Google of the status of a reference number payment. This method supports Succeeded, Pending, and Declined statuses.

If the endpoint encounters an error while processing the request, the endpoint will return HTTP 4xx or 5xx and the HTTP body will either be of type ErrorResponse or contain a generic error (e.g. a message similar to "There was an error. Please try again later.").

The generic error is used in situations where an ErrorResponse with a clear description could be used to help an attacker understand the payment integrator account identifier of other integrators. In these situations, where either the signing key doesn't match, the payment integrator identifier was not found, or the encryption key was unknown, this method will return a generic error. If the request signature could be verified, additional information regarding the error will be returned in an ErrorResponse.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "req-status-123456",
    "requestTimestamp": "1778748779585"
  },
  "paymentIntegratorAccountId": "paidy-retail-account",
  "referenceNumber": "pay_Hovihg1oLIH35LV",
  "paymentStatusResult": {
    "updateSequenceTimestamp": {
      "epochMillis": "1778748779000"
    },
    "paymentIntegratorTransactionId": "paidy-tx-98765",
    "success": {
      "paidAmount": {
        "amountMicros": "10000000",
        "currencyCode": "JPY"
      },
      "installmentPlanType": "INSTALLMENT_PLAN_3_MONTHS",
      "paymentTimestamp": {
        "epochMillis": "1778748778000"
      }
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1778748780000"
  },
  "result": {
    "success": {
      "googlePaymentTransactionId": "google-tx-123456"
    }
  }
}

HTTP request

POST https://vgw.googleapis.com/gsp/one-time-payment-code-v1/referenceNumberPaymentStatusNotification/:PIAID

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "referenceNumber": string,
  "paymentStatusResult": {
    object (ReferenceNumberPaymentStatus)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
paymentIntegratorAccountId

string

REQUIRED: This is the payment integrator account identifier.
referenceNumber

string

REQUIRED: Reference number that this notification pertains to.

For legacy integrations, it is the referenceNumber of the generateReferenceNumber call for this transaction.

For new integrations, it is the printableString of the generateReferenceNumber call for this transaction. If the generateReferenceNumber call doesn't contain printableString, it falls back to the barcodeContents of the same call.
paymentStatusResult

object (ReferenceNumberPaymentStatus)

REQUIRED: The current status details of the reference number payment.

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.

JSON representation 
{

  // Union field response_type can be only one of the following:
  "response": {
    object (ReferenceNumberPaymentStatusNotificationResponse)
  },
  "errorResponse": {
    object (ErrorResponse)
  }
  // End of list of possible types for union field response_type.
}
Possible response messages
HTTP 200 Status

object (ReferenceNumberPaymentStatusNotificationResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

ReferenceNumberPaymentStatus

The current status of the payment.

JSON representation 
{
  "updateSequenceTimestamp": {
    object (Timestamp)
  },
  "paymentIntegratorTransactionId": string,
  "payerInfo": {
    object (PayerInfo)
  },

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "pendingUserAction": {
    object (Empty)
  },
  "pendingVendorProcessing": {
    object (Empty)
  },
  "insufficientFunds": {
    object (InsufficientFunds)
  },
  "riskDeclined": {
    object (RiskDeclined)
  },
  "userIneligible": {
    object (AccountNotEligible)
  },
  "canceled": {
    object (UserExitedPaymentFlow)
  }
  // End of list of possible types for union field result.

  // Union field end_to_end_network_identifier can be only one of the following:
  "pixEndToEndId": string
  // End of list of possible types for union field end_to_end_network_identifier.
}
Fields
updateSequenceTimestamp

object (Timestamp)

REQUIRED: A timestamp (in UTC) describing when this payment status is effective at the vendor. This can be used for order handling and sequencing.
paymentIntegratorTransactionId

string

OPTIONAL: The vendor's unique identifier for this transaction.
payerInfo

object (PayerInfo)

OPTIONAL: Details about the person making the payment. This may include tax information, bank account details, etc.
Union field result. The status details. result can be only one of the following:
success

object (SuccessDetails)

OPTIONAL: The payment was successful.
pendingUserAction

object (Empty)

OPTIONAL: The payment is pending an action from the user.
pendingVendorProcessing

object (Empty)

OPTIONAL: The payment is currently being processed by the vendor or underlying payment network.
insufficientFunds

object (InsufficientFunds)

OPTIONAL: The payment was declined due to insufficient funds or credit.
riskDeclined

object (RiskDeclined)

OPTIONAL: The payment was declined due to risk assessment by the vendor.
userIneligible

object (AccountNotEligible)

OPTIONAL: The user is not eligible for this payment method or terms.
canceled

object (UserExitedPaymentFlow)

OPTIONAL: The payment was canceled, likely due to a timeout or user action.
Union field end_to_end_network_identifier. OPTIONAL: Identifier specific for a network. end_to_end_network_identifier can be only one of the following:
pixEndToEndId

string

This ID is created by Banco Central do Brasil (BCB) for the Brazilian instant payment ecosystem (Pix). This ID is used to identify the operation on a transaction, either a payment or a refund.

Timestamp

A timestamp object representing a point on the ISO timeline in milliseconds since the Unix epoch.

JSON representation 
{
  "epochMillis": string
}
Fields
epochMillis

string (Int64Value format)

REQUIRED: Milliseconds since the Unix epoch

SuccessDetails

Details for a successful payment.

JSON representation 
{
  "paidAmount": {
    object (Amount)
  },
  "installmentPlanType": enum (InstallmentPlanType),
  "paymentTimestamp": {
    object (Timestamp)
  }
}
Fields
paidAmount

object (Amount)

REQUIRED: The amount paid.
installmentPlanType

enum (InstallmentPlanType)

OPTIONAL: The type of installment plan selected by the user.
paymentTimestamp

object (Timestamp)

REQUIRED: Timestamp of when the user physically paid.

InstallmentPlanType

The type of the installment plan.

Enums
INSTALLMENT_PLAN_TYPE_UNSPECIFIED Do not ever set this default value.
INSTALLMENT_PLAN_NONE A plan with no installments, i.e. paid immediately.
INSTALLMENT_PLAN_3_MONTHS An installment plan paid in 3 installments.
INSTALLMENT_PLAN_6_MONTHS An installment plan paid in 6 installments.
INSTALLMENT_PLAN_9_MONTHS An installment plan paid in 9 installments.
INSTALLMENT_PLAN_12_MONTHS An installment plan paid in 12 installments.
INSTALLMENT_PLAN_18_MONTHS An installment plan paid in 18 installments.
INSTALLMENT_PLAN_24_MONTHS An installment plan paid in 24 installments.
INSTALLMENT_PLAN_36_MONTHS An installment plan paid in 36 installments.

InsufficientFunds

This account does not have sufficient funds to guarantee this capture.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  },
  "currentBalance": {
    object (Amount)
  },
  "remedyMethod": {
    object (RemedyMethod)
  }
}
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.
currentBalance

object (Amount)

OPTIONAL: This is the current available balance for the account. If provided, this value will be included in user-facing messaging.
remedyMethod

object (RemedyMethod)

OPTIONAL: This is the remedy method to be applied for the user to help with the insufficient funds issue.

RawResult

Raw result object.

JSON representation 
{
  "scope": string,
  "rawCode": string
}
Fields
scope

string

OPTIONAL: Scope of the rawCode, can be empty.
rawCode

string

REQUIRED: Raw code from the integrator or subsystems within it.

RemedyMethod

Remedy method for InsufficientFunds.

JSON representation 
{

  // Union field remedy_method can be only one of the following:
  "topUp": {
    object (Empty)
  }
  // End of list of possible types for union field remedy_method.
}
Fields
Union field remedy_method. REQUIRED: Oneof remedy method for InsufficientFunds. remedy_method can be only one of the following:
topUp

object (Empty)

This account does not have sufficient funds to guarantee this transfer. The user should be recommended to top-up.

RiskDeclined

The transaction was declined due to a risk check 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.

AccountNotEligible

User's account is not eligible for this service.

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.

UserExitedPaymentFlow

User canceled the whole payment attempt.

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 rawcode. 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.

ReferenceNumberPaymentStatusNotificationResponse

Response object for the referenceNumberPaymentStatusNotification method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (ReferenceNumberPaymentStatusNotificationResult)

REQUIRED: Result of the call.

ReferenceNumberPaymentStatusNotificationResult

Result of the referenceNumberPaymentStatusNotification method.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (Success)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. The result of the call. result can be only one of the following:
success

object (Success)

OPTIONAL: The notification was successfully received.

Success

Details for a successful notification ACK.

JSON representation 
{
  "googlePaymentTransactionId": string
}
Fields
googlePaymentTransactionId

string

OPTIONAL: A Google-generated identifier for this transaction that is included when the payment integrator requests remittanceStatementDetails.