The product goal is to securely enable card tokenization and maintain accurate card lifecycle data. First, Verify Card ensures the card is valid and eligible before tokenization is approved. Then, Notify Card V2 keeps your system continuously updated with all card status changes and operations to maintain synchronization with D1.

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 the Ecom Tokenization APIs, your application must complete the on-boarding process.

You will receive two sets of credentials:

• Sandbox credentials (for test transactions)
• Production credentials (for live transactions)

Each set consists of a Client ID and a Client Secret. The Client Secret is confidential and must not be shared.

To invoke this API you must obtain an OAuth 2.0 access token and send it in the HTTP Authorization header as a Bearer token.

Important: The OAuth2 Token/Revoke endpoints are exposed by the Authorization Server (separate host) and are documented here for convenience. They are not part of the Resource Server paths in this OpenAPI document.

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. See: RFC 6749.

This API supports OAuth 2.0 with the confidential client type. A confidential client can keep its credentials secret when interacting with the Authorization Server.

OAuth 2.0 defines four roles:

1. Resource owner: Entity capable of granting access to a protected resource.
2. Resource server: Server hosting protected resources, accepting requests using access tokens.
3. Client: An application requesting protected resources on behalf of the resource owner.
4. Authorization server: The server issuing access tokens to the client after successful authentication/authorization.

At a high level, the flow is:

1. Get an access token from the Authorization Server.
2. Use the access token to call this API (the Resource Server).

OAuth 2.0 uses an "authorization grant" to represent the authorization used to obtain an access token. This API supports the Client Credentials grant type.

Authorization Server

Token Endpoint

POST /token

With the Client Credentials grant type, the client requests an access token using only its own credentials. The access token returned for this API is of type Bearer.

Clients should request the minimal necessary scope and lifetime. The Authorization Server may issue an access token with fewer rights than requested.

Generate an access token (Client Credentials grant):

1. Obtain a valid client_id and client_secret.
2. Combine them as client_id:client_secret and Base64-encode the result.
3. Call the Token Endpoint. Example:

# NOTE: Only use -k in sandbox/test environments if TLS verification cannot be performed.
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

Example response (access token may be opaque, not necessarily a JWT):

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

Note: Per RFC 6749, the Client Credentials grant type does not issue refresh tokens.

Revoke Endpoint

POST /revoke

In case of credential theft or a security incident, revoke an access token using the Revoke Endpoint.

Parameters

• token (required): The token to revoke.
• Basic Authorization header (required): Authorization: Basic <Base64 encoded client_id:client_secret>
• token_type_hint (optional): Use access_token for Client Credentials. If omitted, the server searches multiple token spaces and revocation may take longer.

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"

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

API Specification

Headers and payload

Request headers are case-sensitive. Request data must be sent as JSON message. The Content-Type header value must be application/json. Responses are sent as JSON messages. The Accept header value must be application/json.

Error code

Encrypt sensitive data

JWE requirements

Use JWE compact serialization (a single Base64URL-encoded string). The D1 backend expects the following JWE configuration:

alg: ECDH-ES
enc: A256GCM
kid: key identifier of the recipient public key
EC-curve: P-256

Example payload to Encrypt the following JSON fields:

Recipient EC public key (JWK):

{
  "kty": "EC",
  "kid": "ASDsL-Jx2XOkRnFtqW-QblWY-mDnQW2LgapadFx75tA",
  "crv": "P-256",
  "x": "UbInEqNbZZZ9SJptBwKTKO6qslSyuWvMkVK44Bx_d8U",
  "y": "PUxeHMNVL0VRxOYJrkHcpe6sap7IG-Are0QborZDngI",
}

Clear data (JSON to encrypt):

{
"pan":"1234567891234567",
"exp":"1223"
}

Generate a P-256 key pair

Use OpenSSL to generate a P-256 key pair for JWE encryption and decryption.

Generate a private key for your issuer backend. Protect it in your environment.

openssl ecparam -name prime256v1 -genkey -noout -out issuerId-jwe-priv-key.pem

Generate a public key to provision in the D1 backend.

openssl ec -in issuerId-jwe-priv-key.pem -pubout > issuerId-jwe-pub-key.pem

Keep the private key in your issuer backend to decrypt payloads sent by the D1 backend.

Provide the public key and its kid to the Thales Delivery Team during D1 Onboarding. The D1 backend uses the public key to encrypt sensitive data for your issuer backend.