Method: getTransactions

Retrieves a list of transactions for the given Virtual Card Number. A transactionListContinuationToken will be returned with each call to this API. The same token would be used in subsequent calls to limit the returned transactions to those that have been added or updated since the request represented by the token. If the token is not provided, the response should include all transactions for the maximum period prior to the request.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "BKD0GF23KSD8S23",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "enrollmentRequestId": "G1MQ0YERJ0Q7LPM",
  "transactionListContinuationToken": "xyz1234"
}

An example success response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899950236"
    }
  },
  "result": {
    "success" : {
      "transactions" : [
        {
          "transactionId" : "qazsw56789",
          "virtualCardTransactionTokenLastFour" : "1234",
          "amount": {
            "amountMicros": "10000000",
            "currencyCode": "USD"
          },
          "purchase" : {},
          "token" : {},
          "status" : {
            "approved" : {}
          },
          "merchantInfo" : {
            "merchantName" : "merchant",
            "address": {
              "addressLine": ["123 Fake St"],
              "localityName": "Springfield",
              "administrativeAreaName": "IL"
            },
            "merchantCategoryCode" : "3001",
            "merchantDomainName": "https://www.gap.com"
          },
          "occurredTimestamp": {
            "epochMillis": 1641477744767
          },
          "paymentMethodUrl": "https://www.partnerbank.com/paymentmethod.html?card=MTIzNHNkYQ==",
          "transactionUrl": "https://www.partnerbank.com/transaction.html?txnId=NDU0NjRmYg=="
        }
      ],
      "transactionListContinuationToken":  "xyz1234"
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/virtual-cards-v1/getTransactions

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "enrollmentRequestId": string,
  "transactionListContinuationToken": string
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
enrollmentRequestId

string

REQUIRED: A reference to an earlier enrollment request. Specifically, the identifier set in the requestId of the requestHeader sent in the enrollRequest that registered a card for Virtual Cards.

This is a string that has a maximum length of 100 characters.
transactionListContinuationToken

string

OPTIONAL: A continuation token returned during a previous call to getTransactions. This is used to limit the returned transactions to those that have been added or updated since the request represented by this token.

If this token is not provided, the response should include all transactions for the maximum period prior to 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 (GetTransactionsResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

GetTransactionsResponse

Response for the getTransactions method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (GetTransactionsResult)

REQUIRED: Contains the result of the request.

GetTransactionsResult

Details corresponding to the result.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (GetTransactionsSuccessResult)
  },
  "unknownEnrollment": {
    object (Empty)
  },
  "unknownTransactionListContinuationToken": {
    object (Empty)
  },
  "transactionDataDisabled": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: Contains the possible result types. Exactly one must be set. result can be only one of the following:
success

object (GetTransactionsSuccessResult)

The request to getTransactions was successful.
unknownEnrollment

object (Empty)

Declined because the given enrollmentRequestId is not recognized.

Use this result instead of an ErrorResponse with invalidIdentifier.
unknownTransactionListContinuationToken

object (Empty)

Declined because the given transactionListContinuationToken is not recognized.

Use this result instead of an ErrorResponse with invalidIdentifier.
transactionDataDisabled

object (Empty)

Declined because the user has opted out of sharing transaction data.

GetTransactionsSuccessResult

Details about the success result.

JSON representation 
{
  "transactions": [
    {
      object (Transaction)
    }
  ],
  "transactionListContinuationToken": string
}
Fields
transactions[]

object (Transaction)

REQUIRED: A list of transactions for this virtual card number.
transactionListContinuationToken

string

REQUIRED: A continuation token used to limit the returned transactions of future calls to those that have been added or updated since this request, which is represented by this token.

Transaction

Details about a transaction.

JSON representation 
{
  "transactionId": string,
  "amount": {
    object (Amount)
  },
  "status": {
    object (Status)
  },
  "merchantInfo": {
    object (MerchantInfo)
  },
  "occurredTimestamp": {
    object (Timestamp)
  },
  "lastUpdatedTimestamp": {
    object (Timestamp)
  },
  "paymentMethodUrl": string,
  "transactionUrl": string,

  // Union field virtual_card_transaction_last_four can be only one of the
  // following:
  "virtualCardTransactionCardNumberLastFour": string,
  "virtualCardTransactionTokenLastFour": string
  // End of list of possible types for union field
  // virtual_card_transaction_last_four.

  // Union field type can be only one of the following:
  "purchase": {
    object (Empty)
  },
  "refund": {
    object (Empty)
  }
  // End of list of possible types for union field type.

  // Union field category can be only one of the following:
  "token": {
    object (Empty)
  },
  "card": {
    object (Empty)
  }
  // End of list of possible types for union field category.
}
Fields
transactionId

string

REQUIRED: The unique ID of this transaction. Uniqueness is within the scope of a particular enrollment.
amount

object (Amount)

REQUIRED: The absolute value of the amount of the transaction.
status

object (Status)

REQUIRED: Status of the transaction.
merchantInfo

object (MerchantInfo)

REQUIRED: Merchant details for the transaction.
occurredTimestamp

object (Timestamp)

REQUIRED: Timestamp (in UTC) of when this transaction occurred.
lastUpdatedTimestamp

object (Timestamp)

OPTIONAL: Timestamp (in UTC) of when this transaction was last updated.
paymentMethodUrl

string

OPTIONAL: Partner-hosted card detail page URL for this payment method which is used in this particular transaction, so that user can check the payment method info. It can also be a deeplink. The URL's domain has to be the partner's domain and stable. Any potential parameters (e.g. token/card identifiers) have to be opaque to Google.
transactionUrl

string

OPTIONAL: Partner-hosted transaction page URL for this particular transaction, so that user can check the transaction details. It can also be a deeplink. The URL's domain has to be the partner's domain and stable. Any potential parameters (e.g. transaction ID) have to be opaque to Google.
Union field virtual_card_transaction_last_four. REQUIRED: The last four digits of the card or the token used for the transaction. virtual_card_transaction_last_four can be only one of the following:
virtualCardTransactionCardNumberLastFour

string

The last four digits of the card used to make the transaction.
virtualCardTransactionTokenLastFour

string

The last four digits of the token used to make the transaction.
Union field type. REQUIRED: Indicates the type of the transaction. type can be only one of the following:
purchase

object (Empty)

This transaction is a purchase.
refund

object (Empty)

This transaction is a refund.
Union field category. REQUIRED: Indicates the category of the transaction. category can be only one of the following:
token

object (Empty)

This is a token based transaction.
card

object (Empty)

This is a card based transaction.

Amount

Associates an amount in micros with a currency code.

JSON representation 
{
  "amountMicros": string,
  "currencyCode": string
}
Fields
amountMicros

string (Int64Value format)

REQUIRED: An amount in micros.
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code

Status

Status of the transaction.

JSON representation 
{

  // Union field status can be only one of the following:
  "pending": {
    object (Empty)
  },
  "approved": {
    object (Empty)
  },
  "declined": {
    object (Empty)
  },
  "cleared": {
    object (Empty)
  },
  "refunded": {
    object (Empty)
  }
  // End of list of possible types for union field status.
}
Fields
Union field status. REQUIRED: Indicates the status of the transaction. status can be only one of the following:
pending

object (Empty)

This transaction is in a pending state.
approved

object (Empty)

This transaction is in an approved state.
declined

object (Empty)

This transaction is in a declined state.
cleared

object (Empty)

This transaction is in a cleared state. Also known as settled state.
refunded

object (Empty)

This transaction is in a refunded state. Also known as reversal state.

MerchantInfo

Merchant details for the transaction.

JSON representation 
{
  "merchantName": string,
  "address": {
    object (Address)
  },
  "merchantCategoryCode": string,

  // Union field merchant_platform can be only one of the following:
  "appPackageName": string,
  "merchantDomainName": string
  // End of list of possible types for union field merchant_platform.
}
Fields
merchantName

string

REQUIRED: The merchant name for this transaction.
address

object (Address)

REQUIRED: The address of the merchant used to make the purchase.
merchantCategoryCode

string

OPTIONAL: This is the ISO 18245 merchant category code (MCC) identifying the type of goods/services being purchased by the user.
Union field merchant_platform. OPTIONAL: The platform of the merchant where this transaction happened. Only one may be set. merchant_platform can be only one of the following:
appPackageName

string

The merchant's app package name where the transaction happened.
merchantDomainName

string

The merchant's domain from the web URL where the transaction happened.

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.