Inquire Interfaces

The inquire interfaces are used in cases, where the merchant wishes to inquire information about certain datasets within Saferpay, like transactions, or an alias. This can be useful in cases, where data has been lost, or was otherwise unavailable to certain systems, that need it.

This chapter will cover their implementation and more.

However, the inquiry interfaces have some restrictions, that have to be considered when using them:

Rules, limitations and requirements

1. Use the standard means first: The inquire interfaces are not meant to replace other API functions, like for example Payment Page Assert, Transaction Authorize, or Alias AssertInsert. When implementing the Payment Page, Transaction Interface, or Secure Card Data flows, you should always use the standard means first, and the inquire interfaces only if those cannot be executed anymore, e.g. due to the token being expired.

2. No polling: In general, but in this case specifically, do not use polling to continuously ask for data.

3. Only successful datasets: As of now, the inquire interfaces only work with successful datasets. Things like failed transactions or alias registrations are not returned.

4. Possible Update delay: The result of a Transaction/Inquire request does not display the current status in real time because the requested data may be updated with a few minutes delay.

Saferpay reserves the right to restrict or deny access to the inquire interface, due to excessive use of the interface, or violation of these rules.

Transaction Inquire

Transaction Inquire is used to gather information about successful transactions. It basically returns the same information you would get via Transaction Authorize, or Payment Page Assert.

Examples

Request

{
 "RequestHeader": {
   "SpecVersion": "[CURRENT SPEC_VERSION]",
   "CustomerId": "[YOUR CUSTOMERID]",
   "RequestId": "f7ca9af6c203c055ec50b6dcc2a40831",
   "RetryIndicator": 0,
   "ClientInfo": {
     "ShopInfo": "My Shop",
     "OsInfo": "Windows Server 2016"
   }
 },
 "TransactionReference": {
   "TransactionId": "fn7O7nAIQWKMSAbIdnC3A26SMUpA"
 }
}

Response

{
 "ResponseHeader": {
   "SpecVersion": "[CURRENT SPEC_VERSION]",
   "RequestId": "f7ca9af6c203c055ec50b6dcc2a40831"
 },
 "Transaction": {
   "Type": "PAYMENT",
   "Status": "CAPTURED",
   "Id": "fn7O7nAIQWKMSAbIdnC3A26SMUpA",
   "CaptureId": "fn7O7nAIQWKMSAbIdnC3A26SMUpA",
   "Date": "2019-05-17T12:44:14.097+02:00",
   "Amount": {
     "Value": "245",
     "CurrencyCode": "EUR"
   },
   "OrderId": "0",
   "AcquirerName": "VISA Saferpay Test",
   "AcquirerReference": "84050331349",
   "SixTransactionReference": "0:0:3:fn7O7nAIQWKMSAbIdnC3A26SMUpA",
   "ApprovalCode": "586216"
 },
 "PaymentMeans": {
   "Brand": {
     "PaymentMethod": "VISA",
     "Name": "VISA"
   },
   "DisplayText": "xxxx xxxx xxxx 0004",
   "Card": {
     "MaskedNumber": "xxxxxxxxxxxx0004",
     "ExpYear": 2019,
     "ExpMonth": 5,
     "HolderName": "Yamada Taro",
     "CountryCode": "JP"
   }
 },
 "Payer": {
   "IpAddress": "178.15.222.100",
   "IpLocation": "DE"
 },
 "Liability": {
   "LiabilityShift": true,
   "LiableEntity": "ThreeDs",
   "ThreeDs": {
     "Authenticated": true,
     "LiabilityShift": true,
     "Xid": "HVQOUwEUJnYaBAM7BCQDNAofGgg="
   }
 },
 "Dcc": {
   "PayerAmount": {
     "Value": "352",
     "CurrencyCode": "JPY"
   }
 }
}

Example of a Transaction Inquire response for a failed transaction:

As mentioned before, the Transaction Inquire Interface only works with successful transactions. Therefore you'll get the following response, if a transaction was either not completed by the payer, or was not successful.

{
 "ResponseHeader": {
   "SpecVersion": "[CURRENT SPEC_VERSION]",
   "RequestId": "fbe3bb5ba9984ce74dcd54089b0cc95a"
 },
 "Behavior": "ABORT",
 "ErrorName": "TRANSACTION_NOT_FOUND",
 "ErrorMessage": "Transaction not found"
}

Alias Inquire

Alias Inquire is used to gather Information about a previously created Alias, using Secure Card Data, like the brand, card number, expiration etc.

Request

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "AliasId": "alias35nfd9mkzfw0x57iwx"
}

Response

{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Alias": {
    "Id": "alias35nfd9mkzfw0x57iwx",
    "Lifetime": 1000
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "VISA",
      "Name": "VISA Saferpay Test"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2098,
      "ExpMonth": 7,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH",
      "TokenPan":{
        "MaskedNumber": "900234xxxxxx0987",
        "ExpYear": 2099,
        "ExpMonth": 9,
      }
    }
  }
}