Surcharge

Terms & Conditions

• The Nets Surcharge service is available in Norway, Finland and Denmark
• ​​Surcharge is not allowed in Sweden​
• ​​​PSPs must only use this API for merchants with an Acquiring agreement with Nets/Nexi Merchant Services​
• The PSP must refer any merchant enquiries related to the Surcharge service to Nets MS Customer Service​
  
• Merchant must have applied separately for the Surcharge service and be on-boarded by Nets MS systems in order for the PSP to facilitate the service​

​​

FAQs

• Is the OAuth2-Host, where we get the Access Token from, the same host as the host we send the rate request for Surcharge?
  
• Yes, it's the same host. In test/pre-prod, the token endpoint is https://api-gateway-pp.nets.eu/token. In production the token endpoint is https://api-gateway.nets.eu/token
• Do we need to access multiple token per connection?
• ​One set of API keys is sufficient and in theory the token can be reused across, BUT token lifetime is only one hour. When the token expires the caller will encounter a HTTP 401 (Unauthorized) status code. We have not identified any mechanism whereby you can prevent the occasional 401, so the recommended solution is:
• All API calls are wrapped to handle HTTP status code 401
• When a 401 is encountered the caller calls the token end-point to receive a new token and the API call is re-tried once
• This will provide stable access whereas other approaches, like trying to get a new token before the old expires, will not work due to token caching at the gateway / token end-point.
  

• Is it possible to use different tokens, like one for each application server?
• ​Token should be kept in memory and refreshed as necessary. See answer to Q2 above. If needed, there can be separate API keys for each server, but this comes with an administrative overhead for the client to maintain it.​
• The OAuth2 credentials for refreshing a /token will not change often?
  

• The client control themselves when they want to use a new key.

  At the moment we do not have a policy and do not enforce periodic key renewal. If this changes in the future affected clients will be notified in advance.

  
  
• ​​​​Can we use multiple tokens provided based same client id/secret at once or only one token need to be used for all calls from us (PSP)?
• ​​​​​​To get a token, the implementation must call the /token endpoint and provide the client id/secret.​The token returned from the end-point typically has a lifetime of 1 hour from when it was initially created, but due to caching and latency it may be anywhere between 0 and the configured max lifetime. As I hinted above, the current configuration has a max lifetime of one hour, but it may change if circumstances require it differently.The implementation of the /token end point may implement caching so that it returns the same token when seeing the same client id/secret within the current token's validity period.This explains why the observed lifetime may be significantly shorter than the configured max. It also means that repeated calls to /token may return the same token.  We do not have fine-grained control over this behavior as it is decided by the implementation of the API Gateway (a COTS product) and may change in future releases.Hence all we can say (and this is sufficient to build an efficient and robust client solution) is: 1) Call the /token endpoint to get a token ​2) Keep using the token until it expires (i.e. when you get a HTTP status code 401 from the API call) then call the /token endpoint again to get a new token.​

  The token can be used in multiple parallel/simultaneous calls (so no need to run API calls in a single thread / synchronized).

  Note: If the PSP wishes to segregate systems on their side, they should use different credentials (client id/secret) for the different systems.
  

• ​Is an /echo or /HealthCheck available for the Surcharge Hub, so we can send diagnostic/ping messages?
• ​​Currently there is no /echo or /healthcheck, but the same can be accomplished by requesting a 'real' Surcharge look-up (provide your PSPID, a MID and a PAN).
  E.g.:
  
• Using a dummy value for the BIN will give http status code '400', but with ISO8583 code '58' "Surcharge not available"
• Using a real value for the PAN and the MID will give http status code '200' and whole Surcharge amount etc. in the response
  
• ​Both authentication methods (clientid + secret or OAuth2) available ?
• ​It's the same - we use the OAuth2 "Client Credentials" flow
  
• ​What is standard token lifetime ?
• ​1 hour – can be adjusted.
  Note that a robust implementation must be able to renegotiate a new token whenever it receives a HTTP 401 'Unauthorized' code from the API.
  Because of token caching, getting a new token before the old token expires will not produce a robust solution.
  
• ​Do you also support additional security like TLS on REST API?
• ​Yes, the API is protected by TLS (1-way, using a server certificate)
  
• Is X-RequestID - UUID 4 is compatible for this API?
• ​It will be possible to send those additional requests, but they will not be used on Nets' side
  
• Any additional changes in ISO8583 auth & clearing message?
• ​​Yes, the following TAGids should be put in ISO field 47 both in Authorization request and on Financial transactions:
  
• - "Surcharge amount" should be put in TAGid '3i'
• - "PSPid" should be put in TAGid 'CJ'
  


​