- HTTP request
- Request body
- Response body
- GetTransactionsResponse
- GetTransactionsResult
- GetTransactionsSuccessResult
- Transaction
- Amount
- Status
- MerchantInfo
- Address
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 ( |
Fields | |
---|---|
requestHeader |
REQUIRED: Common header for all requests. |
enrollmentRequestId |
REQUIRED: A reference to an earlier enrollment request. Specifically, the identifier set in the This is a string that has a maximum length of 100 characters. |
transactionListContinuationToken |
OPTIONAL: A continuation token returned during a previous call to 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 |
|
HTTP 4XX / 5XX Status |
|
GetTransactionsResponse
Response for the getTransactions
method.
JSON representation |
---|
{ "responseHeader": { object ( |
Fields | |
---|---|
responseHeader |
REQUIRED: Common header for all responses. |
result |
REQUIRED: Contains the result of the request. |
GetTransactionsResult
Details corresponding to the result.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field result . REQUIRED: Contains the possible result types. Exactly one must be set. result can be only one of the following: |
|
success |
The request to |
unknownEnrollment |
Declined because the given Use this result instead of an |
unknownTransactionListContinuationToken |
Declined because the given Use this result instead of an |
transactionDataDisabled |
Declined because the user has opted out of sharing transaction data. |
GetTransactionsSuccessResult
Details about the success result.
JSON representation |
---|
{
"transactions": [
{
object ( |
Fields | |
---|---|
transactions[] |
REQUIRED: A list of transactions for this virtual card number. |
transactionListContinuationToken |
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 ( |
Fields | |
---|---|
transactionId |
REQUIRED: The unique ID of this transaction. Uniqueness is within the scope of a particular enrollment. |
amount |
REQUIRED: The absolute value of the amount of the transaction. |
status |
REQUIRED: Status of the transaction. |
merchantInfo |
REQUIRED: Merchant details for the transaction. |
occurredTimestamp |
REQUIRED: Timestamp (in UTC) of when this transaction occurred. |
lastUpdatedTimestamp |
OPTIONAL: Timestamp (in UTC) of when this transaction was last updated. |
paymentMethodUrl |
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 |
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 |
The last four digits of the card used to make the transaction. |
virtualCardTransactionTokenLastFour |
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 |
This transaction is a purchase. |
refund |
This transaction is a refund. |
Union field category . REQUIRED: Indicates the category of the transaction. category can be only one of the following: |
|
token |
This is a token based transaction. |
card |
This is a card based transaction. |
Amount
Associates an amount in micros with a currency code.
JSON representation |
---|
{ "amountMicros": string, "currencyCode": string } |
Fields | |
---|---|
amountMicros |
REQUIRED: An amount in micros. |
currencyCode |
REQUIRED: ISO 4217 3-letter currency code |
Status
Status of the transaction.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field status . REQUIRED: Indicates the status of the transaction. status can be only one of the following: |
|
pending |
This transaction is in a pending state. |
approved |
This transaction is in an approved state. |
declined |
This transaction is in a declined state. |
cleared |
This transaction is in a cleared state. Also known as settled state. |
refunded |
This transaction is in a refunded state. Also known as reversal state. |
MerchantInfo
Merchant details for the transaction.
JSON representation |
---|
{ "merchantName": string, "address": { object ( |
Fields | |
---|---|
merchantName |
REQUIRED: The merchant name for this transaction. |
address |
REQUIRED: The address of the merchant used to make the purchase. |
merchantCategoryCode |
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 |
The merchant's app package name where the transaction happened. |
merchantDomainName |
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[] |
OPTIONAL: This holds unstructured Address text. |
localityName |
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 |
OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture." |
postalCodeNumber |
OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ". |
countryCode |
OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2. |