Issuer API for accessing merchant inquiry data

URLs

Authorization server Base URL - Production

https://api-gateway2.nets.eu/

Authorization server Base URL - Sandbox

https://api-gateway-pp.nets.eu/

Authentication

Before you can use Account Updater service, you must go through on-boarding process.

You will receive two keys, one set for Sandbox and another set for Production access, which are the pairs of unique identifier called "Client ID" and "Client Secret". The Client Secret should not be shared with anyone. The two keys will be needed to authenticate your application to the respective environments. The key for the sandbox environment is used for a test transaction, and that of the production environment for a live transaction.

You need access tokens to invoke Account Updater service's resources. Access tokens are passed in the HTTP header when invoking the API. The Authorization server provides a Token Endpoint that you can use to generate or renew your access token. The response of the Token Endpoint is a JSON message. You extract the token for the JSON and pass it with an HTTP Authorization header to access the API.

In case of theft or a security violation, you can revoke an access token by calling a Revoke Endpoint.

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. Read more at The OAuth 2.0 Authorization Framework, https://tools.ietf.org/html/rfc6749.

Account Updater service currently supports OAuth 2.0 Specification with confidential client type. A Confidential client is capable of maintaining the confidentiality of its credentials provided by an authorization server. OAuth 2.0 defines four roles:

1. Resource owner: An entity capable of granting access to a protected resource.
2. Resource server: The server hosting protected resources, capable of accepting and responding to protected resource requests using access tokens.
3. Client: An application making protected resource requests on behalf of the resource owner and with its authorization.
4. Authorization server: The server issuing access tokens to the client after successfully authenticating the resource owner obtaining authorization.

At a very high-level, it is possible to break the full OAuth flow into two parts.

1. Get a token from the authorization server.
2. Use the token to access the resource server. OAuth 2.0 defines a concept called "authorization grant" which is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token. Account Updater service supports Client Credentials grant type.

Authorization server

Token Endpoint

---

POST /token

---

With the Client Credentials grant type, the client can request an access token using only its credentials when the client is requesting access to the protected resource under its control. Once the client makes this request to the authorization server, it will return an access token to the protected resource. The access token returned to the client for Account Updater service is Bearer type.

The client should request access tokens with the minimal necessary scope and lifetime. The authorization server takes the client identity into account when choosing how to honour the requested scope and lifetime, and may issue an access token with less rights than requested.

Generate access token using Client Credential grant type

1. Obtain a valid client_id and Client_secret.
2. Combine the pair in the format client_id:client_secret and encode the combined string
3. using base64. See Encode to Base64 format, https://www.base64encode.org/
4. Use the following sample curl command to obtain the access token.

  $ curl -k -d "grant_type=client_credentials" \
    -H "Authorization: Basic <Base64 encoded client_id:client_secret>" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
     https://api-gateway2.nets.eu/token

You receive a response similar to the following:

  {
    "token_type":"Bearer",
    "expires_in":2061,
    "access_token":"ca19a540f544777860e44e75f605d927"
  }

Note that, according to OAuth2.0 Authorization Framework, the Client Credential grant type does not allow for the issuing the refresh tokens. See https://tools.ietf.org/html/rfc6749#section-4.4.3

Revoke Endpoint

---

POST /revoke

---

Parameters

• token (required)

  The token to be revoked

• <Base64 encoded client_id:client_secret> (required)

  Combine the pair in the format client_id:client_secret and encode the combined string using base64.

• token_type_hint (optional)

  If you do not specify this parameter, the authentication server will search in both key spaces (access_token and refresh_token) and if it finds a matching token then it will be revoked. Therefore, if this parameter is not specified, it will take longer to revoke the token. However, if you specify this parameter, the authentication server only searches in the respective token space. Hence, it is much faster to revoke the token. For the Client Credentials grant type, you have only the option of access_token.

Example:

  $ curl -X POST \
    https://api-gateway2.nets.eu/revoke \
    -H 'Authorization: Basic <Base64 encoded client_id:client_secret>' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'token=<token_to_be_revoked>&token_type_hint=<access_token_or_refresh_token>'

Responses

• Valid token - HTTP Status 200 - OK

  You receive an empty response with the HTTP status as 200. The following HTTP headers are returned:

  Revokedaccesstoken: a0d210c7a3de7d548e03f1986e9a5c39
  Authorizeduser: admin@carbon.super
  Revokedrefreshtoken: 5e87a8235cd4d066e15c4c989f5ecf94
  Content-Type: text/html
  Pragma: no-cache
  Cache-Control: no-store
  Date: Tue, 23 Aug 2018 19:28:52 GMT
  Transfer-Encoding: chunked
  

• Invalid token - HTTP Status 200 - OK You still receive an empty response with the HTTP status as 200 but only the following HTTP headers are returned:

  Content-Type: text/html
  Pragma: no-cache
  Cache-Control: no-store
  Date: Tue, 23 Aug 2018 19:31:45 GMT
  Transfer-Encoding: chunked
  

  Because the authorization server cannot find the token in any key space, you will not see Revokedaccesstoken or Revokedrefreshtoken in the HTTP headers.

API Specification

Headers and payload

Request data must be in JSON format. The Content-Type header value must be application/json.

Response will be in JSON format. The Accept header value must be application/json.