Query

 

Description

The Query call can be used to request information related to the transaction from Netaxept. Netaxept then returns detailed information concerning the transaction, such as the status of the transaction and the payment method used. The Query call can be used for example in the following cases:

  • If the payment method used by the customer is not known after the Register call and the Terminal phase, use the Query call to find out the payment method and then take the further action based on that.
  • If you receive an error, use the Query call to get the full information available to do the correct error handling and allowing a better response to the customer.
  • If you are unsure about the status of the transaction, use the Query call to check that the transaction has the correct status and the payment has succeeded. Despite of the successfully captured transaction, it is recommended to run the Query call before sending goods to the customer to verify that the money has actually been captured. This is due to the response times Netaxept from time to time see from third-party payment methods, such as direct bank payments.
  • If you have implemented Recurring payments or Easy payment, run the Query call on the initial transaction to find out the value of the "panHash" parameter that needs to be stored on the customer profile for future purchases.

The input data is organized into a QueryRequest, and the output data is formatted as a QueryResponse. Example of the REST Query call and the corresponding response can be found in the "Sample code" section.

 

API call

REST

Please note that Server Name Indication (SNI) is required when connecting to Netaxept test environment URL https://test.epayment.nets.eu

Web Services

Query (string merchantId, string token, QueryRequest  request) -> QueryResponse

 

Input parameters

Available input parameters in the QueryRequest are listed below. Please see proper validation rules at the "Validation" section.

Authentication

Merchant ID

REST: MerchantId

WebServices: merchantId

Required

Validation: Numeric

MaxLength: 8

Merchant ID is a unique ID generated by Nets for identifying each merchant in Netaxept. You need to send this ID to Netaxept along all API calls. Test accounts may have a maximum length of 8 digits, while production accounts has a maximum length of 6 digits.

 

Token

REST: Token

WebServices: token

Required

Validation: Reference

MaxLength: 32

Token is the shared secret between the merchant and Netaxept. It is used to authenticate the merchant, and is provided to you by Netaxept.

QueryRequest

Transaction ID

REST: TransactionId

WebServices: TransactionId

Required

Validation: Reference

MaxLength: 32

Transaction ID is a unique ID identifying each transaction within the Merchant ID in Netaxept at any point. Transaction ID used in the Query call needs to match the Transaction ID used with the Register call.

 

Output parameters     

PaymentInfo

The PaymentInfo class inherits from the QueryResponse class.

Merchant ID

REST: MerchantId

WebServices: MerchantId

Required

Validation: Reference

MaxLength: 32

The merchant ID is echoed from the Query call.

 

Transaction ID

REST: TransactionId

WebServices: TransactionId

Required

Validation: Reference

MaxLength: 32

The transaction ID is echoed from the Query call.

 

Child transaction ID

REST: ChildTransactionid

WebServices: ChildTransactionid

Optional

Validation: Reference

MaxLength: N/A

Child transaction ID is a unique ID identifying the remaining part of the gift card transaction that has been paid with another payment method.

 

Query finished

REST: QueryFinished

WebServices: QueryFinished

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the Query operation was finished. This timestamp is generated on the Netaxept server.

OrderInformation

Order number

REST: OrderNumber

WebServices: OrderNumber

Required

Validation: Reference

MaxLength: 32

A transaction identifier defined by the merchant. Nets recommends to generate each transaction a unique order number but if wanted the same order number can be used several times.

 

Amount

REST: Amount

WebServices: Amount

Required

Validation: Numeric

MaxLength: 10

The transaction amount described as the lowest monetary unit for the given currency without punctuation marks and excluding any fees. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999".

 

Currency

REST: Currency

WebServices: Currency

Required

Validation: Alpha

MaxLength: 3

The currency code for the transaction amount, following ISO 4217. For example "NOK", "SEK", "DKK", "EUR" and "USD".

 

Order description

REST: OrderDescription

WebServices: OrderDescription

Optional

Validation: Custom

MaxLength: 1500

Free-format textual description determined by the merchant for the transaction. This can be HTML-formatted. If you are using Netaxept hosted payment window, this description will appear in the payment window for the customer. Unlike the other fields, the order description will not cause the call to fail if it exceeds its maximum amount, rather the field will be truncated to its maximum amount.

 

Delivery date

REST: DeliveryDate

WebServices: DeliveryDate

Optional

Validation: Numeric

MaxLength: 8

Date when Netaxept automatically executes the Process (Capture) call for the transaction, on the format YYYYMMDD. When using this parameter, the merchant runs the Process (Auth) after the Register call as normal but the Process (Capture) will the taken care of by Netaxept.

 

Fee

REST: Fee

WebServices: Fee

Required

Validation: Numeric

MaxLength: 10

An additional charge determined by the merchant for the transaction, described as the lowest monetary unit without punctuation marks. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999". The fee will be added to the original amount.

 

Timestamp

REST: Timestamp

WebServices: Timestamp

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the operation in question was finished. This timestamp is generated on the Netaxept server.

 

Total

REST: Total

WebServices: Total

Required

Validation: Numeric

MaxLength: 10

The sum of transaction amount + fee described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999".

 

Rounding amount

REST: RoundingAmount

WebServices: RoundingAmount

N/A

Validation: Numeric

MaxLength: 10

Rounding amount defined by the merchant for the transaction, described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999".

AuthenticationInformation

ECI

REST: ECI

WebServices: ECI

Optional

Validation: Numeric

MaxLength: 2

The authentication result that is returned if the transaction has been authenticated by 3D Secure authentication services:

  • 05 or 02 = Card enrolled, authenticated OK.
  • 06 or 01 = Authentication attempted, but the payment card was not enrolled for the authentication service.
  • 07 or 00 = The merchant was not registered for the authentication service.

 

Authenticated with

REST: AuthenticatedWith

WebServices: AuthenticatedWith

Optional

Validation: Printable

MaxLength: Custom

Identifies which external authentication protocol, if any, has been used for the transaction. This field is set only for card transactions and currently can be only "3-D Secure".

 

Authenticated status

REST: AuthenticatedStatus

WebServices: AuthenticatedStatus

Optional

Validation: Printable

MaxLength: Custom

The status of the 3D Secure authentication. The valid values are:

  • Y = Authentication Successful. Customer was successfully authenticated. All data needed for clearing, including the Cardholder Authentication Verification Value, is included in the message.
  • N = Cardholder not enrolled in 3-D Secure. Does not influence settlement guarantee.
  • U = Authentication Could Not Be Performed. Authentication could not be completed, due to technical or other problem, as indicated in PARes.IReq.Transaction Status TX.status.
  • A = Attempts Processing. Performed authentication could not be completed, but a proof of authentication attempt (CAVV) was generated.

Summary

Authorization id

REST: AuthorizationId

WebServices: AuthorizationId

Optional

Validation: Custom

MaxLength: 64

An ID given to an authorized transaction by the Issuer.

 

Authorized

REST: Authorized

WebServices: Authorized

Required

Validation: Boolean

MaxLength: Custom

Whether or not this transaction has been authorized. The value is set to "true" or "false". Transaction is flagged as authorized if it has been processed with AUTH or SALE call.

 

Annulled

REST: Annulled

WebServices: Annulled

Required

Validation: Boolean

MaxLength: Custom

Whether or not the authorization of this transaction has been cancelled. The value is set to "true" or "false".

 

Annuled

REST: Annuled

WebServices: Annuled

Required

Validation: Boolean

MaxLength: Custom

Whether or not the authorization of this transaction has been cancelled. The value is set to "true" or "false". This parameter will contain the same value as Summary.Annulled.

 

Amount captured

REST: AmountCaptured

WebServices: AmountCaptured

Required

Validation: Numeric

MaxLength: 10

The amount which has been captured on this transaction, described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999". Check this parameter to confirm the payment is made.

 

Amount credited

REST: AmountCredited

WebServices: AmountCredited

Required

Validation: Numeric

MaxLength: 10

The amount which has been credited on this transaction, described as the lowest monetary unit for the given currency without punctuation marks. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999".

CustomerInformation

Email

REST: Email

WebServices: Email

Optional

Validation: Custom

MaxLength: 128

The customer's email address. Returned if the merchant has sent it to Netaxept along the Register call.

 

Phone number

REST: PhoneNumber

WebServices: PhoneNumber

Optional

Validation: Custom

MaxLength: 64

The customer's phone number. Returned if the merchant has sent it to Netaxept along the Register call. The phone number should be given on the format of +[country code][phone number], for example: +4712345678, +469876543, +35850123456.

 

IP address

REST: IP

WebServices: IP

Optional

Validation: Custom

MaxLength: 15

The IP address of the customer's browser connection.

 

Customer number

REST: CustomerNumber

WebServices: CustomerNumber

Optional

Validation: Custom

MaxLength: 64

The customer's ID that can be used to identify the customer or the customer group. The same customer number can be used several times. Returned if the merchant has sent it to Netaxept along the Register call.

 

First name

REST: FirstName

WebServices: FirstName

Optional

Validation: Custom

MaxLength: 128

Customer's first name. Returned if the merchant has sent it to Netaxept along the Register call.

 

Last name

REST: LastName

WebServices: LastName

Optional

Validation: Custom

MaxLength: 128

Customer's last name. Returned if the merchant has sent it to Netaxept along the Register call.

 

Address 1

REST: Address1

WebServices: Address1

Optional

Validation: Custom

MaxLength: 64

Customer's address. Returned if the merchant has sent it to Netaxept along the Register call.

 

Address 2

REST: Address2

WebServices: Address2

Optional

Validation: Custom

MaxLength: 64

Customer's secondary address. Returned if the merchant has sent it to Netaxept along the Register call.

 

Post code

REST: Postcode

WebServices: Postcode

Optional

Validation: Custom

MaxLength: 16

Customer's postal code. Returned if the merchant has sent it to Netaxept along the Register call.

 

Town

REST: Town

WebServices: Town

Optional

Validation: Custom

MaxLength: 64

Customer's city. Returned if the merchant has sent it to Netaxept along the Register call.

 

Country

REST: Country

WebServices: Country

Optional

Validation: N/A

MaxLength: N/A

Customer's country, following ISO 3166-1 Alpha 2 code. For example: "NO", "SE", "DK", "FI". Returned if the merchant has sent it to Netaxept along the Register call.

 

Social security number

REST: SocialSecurityNumber

WebServices: SocialSecurityNumber

Optional

Validation: Custom

MaxLength: 32

Customer's social security number. Returned if the merchant has sent it to Netaxept along the Register call. Mandatory for certain payment methods.

 

Customer's company name

REST: CompanyName

WebServices: CompanyName

Optional

Validation: Custom

MaxLength: 128

The customer's company name. Returned if the merchant has sent it to Netaxept along the Register call.

 

Company registration number

REST: CompanyRegistrationNumber

WebServices: CompanyRegistrationNumber

Optional

Validation: N/A

MaxLength: N/A

The business ID of the customer's company. Returned if the merchant has sent it to Netaxept along the Register call.

CardInformation

Masked PAN

REST: MaskedPAN

WebServices: MaskedPAN

Optional

Validation: Custom

MaxLength: 19

The card number used for this transaction, masked with asterisks.

 

Issuer

REST: Issuer

WebServices: Issuer

Optional

Validation: Alpha

MaxLength: 32

Indicates which payment method was used for this transaction. This parameter will contain the same value as CardInformation.PaymentMethod.

 

Expiry date

REST: ExpiryDate

WebServices: ExpiryDate

Optional

Validation: Numeric

MaxLength: 4

The expiry date for the card used for this transaction, on the format YYMM.

 

Pan Hash

REST: PanHash

WebServices: PanHash

Optional

Validation: Base64

MaxLength: N/A

The token value identifying the card transaction. It is independent of the PAN and is not considered as a hash value.

If recurringType was specified, i.e. recurringType=R (Recurring payment) or recurringType=S (Easy payment), and no panHash was supplied, this is the panHash generated by the payment / card registration and should be used for the later transaction.

It is the merchant's responsibility to store tokens in a secure way and restrict access to data on a need to know basis. The merchant undertakes not to store tokens on a frontend system exposed to the internet or directly on mobile devices.

 

Issuer country

REST: IssuerCountry

WebServices: IssuerCountry

Optional

Validation: Alpha

MaxLength: 2

Country where the payment card used for the transaction was issued, formatted following ISO 3166-1 Alpha 2 code. For example: "NO", "SE", "DK", "FI".

 

Issuer ID

REST: IssuerId

WebServices: IssuerId

Optional

Validation: Numeric

MaxLength: 4

An identifier for the payment method being used. May be either positive or negative.

 

Payment method

REST: PaymentMethod

WebServices: PaymentMethod

Optional

Validation: Alpha

MaxLength: 32

Indicates which payment method was used for this transaction.

Please see the valid payment methods at the Register call page, in the "Payment Method Action List" => "PaymentMethod" parameter.

For wallet based transactions, this parameter shows information about the underlying card whereas the name of the wallet used for the payment can be found in the "Wallet" section.

History

This section documents the History that is an array of TransactionLogLine(s).

Operation

REST: Operation

WebServices: TransactionLogLine.Operation

Required

Validation: Alpha

MaxLength: 16

Specifies which operation was performed for the transaction. Valid operations are:

  • REGISTER
  • AUTH
  • ACCOUNT VERIFICATION
  • SALE
  • CAPTURE
  • CREDIT
  • ANNUL

Read more about the different operations at the "Flow outline" section.

In some cases Netaxept returns "SETUP" in this field. For example, when the merchant has created a payment link via Link payment or done call centre transaction via Netaxept Admin.

 

Amount

REST: Amount

WebServices: TransactionLogLine.Amount

Optional

Validation: Numeric

MaxLength: 10

The amount of this part of the transaction / operation described as the lowest monetary unit for the given currency without punctuation marks and excluding any fees. For example: 100,00 NOK is noted as "10000" and 9.99 USD is noted as "999".

 

Description

REST: Description

WebServices: TransactionLogLine.Description

Optional

Validation: Alpha

MaxLength: 4000

Free-format textual description of this part of the transaction / operation determined by the merchant and displayed to the merchant in Netaxept Admin. The field can show also an IP address and/or a username that has been used for the transaction.

Please note that this is different than OrderDescription parameter and hereby is not shown to the end-customer to the payment window.

 

Batch number

REST: BatchNumber

WebServices: TransactionLogLine.BatchNumber

Optional

Validation: Numeric

MaxLength: 3

Specifies which settlement batch this operation belongs to. Is present if the financial operation is done to the transaction is question.

 

Date and time

REST: DateTime

WebServices: TransactionLogLine.DateTime

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the operation in question was finished. This timestamp is generated on the Netaxept server.

 

Transaction reference number

REST: TransactionReconRef

WebServices: TransactionLogLine.TransactionReconRef

Optional

Validation: Reference

MaxLength: 32

The transaction reconciliation reference is a reference number allocated to the transaction by the merchant. The transaction reference number will be returned to the merchant with the settlement if the chosen acquirer supports the return of the transaction-specific reference number. The transaction reference number can also be seen in the merchant's bank statement when direct bank payments are in question. Read more about transaction reference numbers >

In this parameter you will find the transaction reference number used for this part of the transaction. It can be sent to Netaxept along the Register call when it will serve as a default reference for the transaction. Alternatively, it can be sent in along the Process call.

Error

This section will contain the latest / newest element from the ErrorLog, and can be used for a comparison instead of running through the whole ErrorLog each time.

Operation

REST: Operation

WebServices: Operation

Required

Validation: Alpha

MaxLength: 16

Specifies which financial operation was tried to perform for the transaction when the error occured. Valid operations are:

  • REGISTER
  • AUTH
  • ACCOUNT VERIFICATION
  • SALE
  • CAPTURE
  • CREDIT
  • ANNUL
  • QUERY

Read more about the different operations at the "Flow outline" section.

 

Response code

REST: ResponseCode

WebServices: ResponseCode

Required

Validation: AlphaNumeric

MaxLength: 4

The response code for this part of the transaction. Only failed operations are entered into the error log, so this parameter will never contain the string "OK". Read more about response codes >

 

Response text

REST: ResponseText

WebServices: ResponseText

Required

Validation: Custom

MaxLength: Custom

The response text / message explains the error code and gives a more detailed description of the error helping the merchant to find out why the transaction failed. Read more about response messages >

 

Response source

REST: ResponseSource

WebServices: ResponseSource

Required

Validation: AlphaNumeric

MaxLength: 16

The source is a textual description of which part of the system generated the error code. The error codes are divided into groups according to the source. Read more about error sources >

 

Date and time

REST: DateTime

WebServices: DateTime

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the operation in question was finished. This timestamp is generated on the Netaxept server.

ErrorLog

This section documents the history of all the errors occurred for the transaction in the format of ErrorLog that is an array of PaymentError(s).

Operation

REST: Operation

WebServices: PaymentError.Operation

Required

Validation: Alpha

MaxLength: 16

Specifies which financial operation was tried to perform for the transaction when the error occured. Valid operations are:

  • REGISTER
  • AUTH
  • ACCOUNT VERIFICATION
  • SALE
  • CAPTURE
  • CREDIT
  • ANNUL
  • QUERY

Read more about the different operations at the "Flow outline" section.

 

Response code

REST: ResponseCode

WebServices: PaymentError.ResponseCode

Required

Validation: AlphaNumeric

MaxLength: 4

The response code for this part of the transaction. Only failed operations are entered into the error log, so this parameter will never contain the string "OK". Read more about response codes >

 

Response text

REST: ResponseText

WebServices: PaymentError.ResponseText

Required

Validation: Custom

MaxLength: Custom

The response text / message explains the error code and gives a more detailed description of the error helping the merchant to find out why the transaction failed. Read more about response messages >

 

Response source

REST: ResponseSource

WebServices: PaymentError.ResponseSource

Required

Validation: AlphaNumeric

MaxLength: 16

The source is a textual description of which part of the system generated the error code. The error codes are divided into groups according to the source. Read more about error sources >

 

Date and time

REST: DateTime

WebServices: PaymentError.DateTime

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the operation in question was finished. This timestamp is generated on the Netaxept server.

Recurring

This section is present if the transaction should or already has subsequent withdrawals on it (that is, Easy paymen or Recurring payments).

Type

REST: Type

WebServices: Type

Required

Validation: N/A

MaxLength: N/A

Indicates which recurring type is registered for this transaction. Valid values are:

  • Recurring (Init)
  • Recurring (Pull)
  • Store (Init)
  • Store (Pull)

"Recurring" refers to recurringType=R (Recurring payment) and "Store" refers to recurringType=S (Easy payment). In addition, "Init" means the first transaction where the data have been stored for recurring transactions whereas "Pull" means the later transaction where panHash connected to the initial transaction is used.

 

Frequency

REST: Frequency

WebServices: Frequency

Optional (present if Type = "R")

Validation: Numeric

MaxLength: 4

Indicates how often the merchant is allowed to make withdrawals based on the recurring agreement, in days. A recurring frequency of "1" will allow the merchant to make subsequent transactions on the card every day.

Minimum frequency is 0 day, meaning no limitation on the number of transactions per day. Maximum is 365 days.

 

Expiry date

REST: ExpiryDate

WebServices: ExpiryDate

Optional (present if Type = “R”)

Validation: Numeric

MaxLength: 8

Date when the recurring agreement made between the merchant and the customer expires. The date is described on the format YYYYMMDD.

 

Pan Hash

REST: PanHash

WebServices: PanHash

Required

Validation: Base64

MaxLength: N/A

The token value identifying the transaction. It is independent of the PAN and is not considered as a hash value. If recurringType was specified, i.e. recurringType=R (Recurring payment) or recurringType=S (Easy payment), and no panHash was supplied, this is the panHash generated by the payment / card registration and should be used for the later transaction.

 

Pan Hash secret

REST: panhashSecret

WebServices: PanHashSecret

Optional

Validation: Base64

MaxLength: 20

A secret token linked to their panHash parameters by the means of adding an extra layer of protection to their panHash parameters.

 

Use 3D-Secure 

REST: Use3DS

WebServices: Use3DS

Optional

Validation: Boolean

MaxLength: 5

Customer has been forwarded to perform 3D Secure authentication in a situation when recurringUse3DS=true, recurringType=S, panHash parameter is specified for the subsequent transaction and serviceType = B or M. Otherwise subsequent payments with stored cards are non-3DS authenticated.

SecurityInformation

Customer IP country

REST: CustomerIPCountry

WebServices: CustomerIPCountry

Required

Validation: Alpha

MaxLength: 2

Country of the IP address of the customer's browser connection, following ISO 3166-1 Alpha 2 code. For example: "NO", "SE", "DK", "FI".

 

IP country matches issuing country

REST: IPCountryMatchesIssuingCountry

WebServices: IPCountryMatchesIssuingCountry

Required

Validation: Boolean

MaxLength: Custom 

Whether or not the country of the customer's IP address matches the country of the card Issuer. The value is set to "true" or "false".

TerminalInformation

Browser

REST: Browser

WebServices: Browser

Required

Validation: N/A

MaxLength: N/A

Customer's browser information.

 

Customer entered

REST: CustomerEntered

WebServices: CustomerEntered

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the customer has visited in the payment window. This timestamp is generated on the Netaxept server.

 

Customer redirected

REST: CustomerRedirected

WebServices: CustomerRedirected

Required

Validation: Timestamp

MaxLength: N/A

A timestamp indicating when the customer has been redirected or has been attempted to redirect from the payment window to the URL specified by the merchant. This timestamp is generated on the Netaxept server. Check this parameter to verify when Netaxept redirected the customer or tried to redirect.

Wallet

This section is present if wallet based payment method was used for the payment.

Issuer

REST: Issuer

WebServices: Issuer

Required

Validation: Alpha

MaxLength: N/A

Tells the name of the wallet based payment method being used. The actual payment card used for the payment can be found in CardInformation.PaymentMethod.

AvtaleGiroInformation

AvtaleGiro status

REST: AvtaleGiroStatus

WebServices: AvtaleGiro.AvtaleGiroStatus

Required

Validation: Custom

MaxLength: Custom

If AvtaleGiro data was sent on the current transaction, an AvtaleGiro status is required to give the status of the signing of the AvtaleGiro agreement. Valid values are:

  • Ok = The signing of the AvtaleGiro agreement was OK.
  • Cancel = The signing of the AvtaleGiro agreement was cancelled by the customer.
  • Error = Something went wrong when signing the AvtaleGiro agreement.

DnBNorDirectPaymentInformation

The credited account

REST:

WebServices: DnBNorDirectPaymentInformation.ToAccount

Optional

Validation: N/A

MaxLength: N/A

Indicates which account is credited if the transaction succeeded.

 

KID

REST:

WebServices: DnBNorDirectPaymentInformation.KID

Optional

Validation: N/A

MaxLength: N/A

An ID identifying the customer and/or transaction.

 

Message

REST:

WebServices: DnBNorDirectPaymentInformation.Message

Optional

Validation: N/A

MaxLength: N/A

An ID identifying the customer.

 

Bank reference

REST:

WebServices: DnBNorDirectPaymentInformation.BankRef

Optional

Validation: N/A

MaxLength: N/A

 

 

From account

REST:

WebServices: DnBNorDirectPaymentInformation.FromAccount

Optional

Validation: N/A

MaxLength: N/A

 

 

Exceptions and response codes

If something goes wrong when communicating between your system and Netaxept or in the middle of the payment process, Netaxept declines the transaction and returns an exception. All exceptions are wrapped in the outer Exception tag, with an Error tag inside. The type (xsi:type) of the Error tag indicates which exception it is. In most cases, the exception includes the error code indicating the error, as well as an error message explaining the code. The Query call can throw the following exceptions. Read more about exceptions > and response codes >

  • AuthenticationException
  • QueryException