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

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"
}

Inquire and Multipart Captures

As of now, the Inquire Interface does not return information on individual Captures, like Multipart Captures. However, it will report the currently captured amount of the main transaction.

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

DCC Inquire

This function can currently only be used, if you are fully PCI certified, due to it requiring the plain text card details. DO NOT USE DCC INQUIRY, IF YOU ARE NOT CERTIFIED!

Transaction DCCInquiry is used to inquire information about the availability of Dynamic Currency Convertion and details, on a specific card.

This enables integrators to build their own DCC selection-page for a more integrated solution.

The request will return all necessary information about DCC in the response, like the general availability, the card holders base currency, if diverting from the merchants requested currency and more. However the most important value is the DccToken, which contains the reference for this particular inquiry. That token is then later used to actually perform a transaction with DCC.

First Tab

{
  "RequestHeader": {
    "SpecVersion": "[current Spec-Version]",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request identifier]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "CardNumber": "1234123412341234",
  "Amount": {
    "Value": "100",
    "CurrencyCode": "EUR"
  }
}

Second Tab

Once received, this information can be used to show a selection screen to the payer, where they can either select to have their bank do the conversion, by selecting the merchants currency, or by selecting the conversion through Saferpay.

Once selected, the merchant then has to submit the DccToken and the selected currency through the Authorize Direct request, inside the DCC container, to perform the actual payment.