Authentication

Authentication is based on JWT access tokens. Each API call includes a JWT token, targeting a unique NHP tenant via eTrust Resource Name - ERN - (e.g. ern:product/tenants/1). There are no user level access rights within NH Pay. NHP tenant represents an organization, which is further divided into companies and departments.

If the token is generated by the system for its own use without human interaction, use of the public tenant ERN as user_ern is recommended, e.g. ern:provetcloud/tenants/public.

If a product performs an action as itself instead of one of its tenants, it should use string public as the <tenant-id> in the tenant_ern. All tenant-ids except public are considered private tenants. Using the public tenant may be useful to perform maintenance affecting multiple tenants, for example.

NH PAY API expects to receive the access token in the Authorization HTTP-header. The syntax for the header is Authorization: Bearer <JWT access token>.

The access token must be a JWT signed using a private key of an issuer NH PAY is configured to trust to issue tokens to the tenant’s ERN-namespace. Remember the word Bearer before the token in the header value.

JWT tokens

• RSA keypair (RS256) is used to sign JWT tokens

• The integration must share the public key(s) with NH Pay eTrust Authorizer by exposing a static HTTPS URL jwks_uri

• Keys must be rotated regularly (e.g. every 48 hours)

• New key should be used only after min. of 1 hour has passed since it was published

• If private key has been compromised, keys should be replaced immediately (and NH Pay team notified)

The jwks_uri should provide response following the provided example:

{
   "alg": "RS256",
   "e": "AQAB",
   "kid": "GH730T-sbIt--mXjyjTR58VMSeChrFI_igWaYjEnSk0",
   "kty": "RSA",
   "n": "s7Dj0rB1ryceETwWMEZ7AWzQ1bB4LERm4pFMYsSnkSCeerc_mRHa2SzXiUBUkbpIqBZsF90JhNTwi774nwIl-W7SklTOUD3cLC3PfAXPazO1mE0Yn3gyHbeSXoIm4DPreHen6M2jeVncueORFzn0L82muNOMYLDUtT7o3VT84WkcZgQORHZQJVSB6D4DaBFT-mPUTWoonsITMa7FuSp2mZPEgPxIrZ7z9lLqocDC8bxO-JNC62AY6r0KUfIyR3ZxEj1SjJtnTsTEUsImobrKRrxCItlHkzJPJqBpB7LGfbgeApHmrgZm0k6SqsxHeAQCEcQlnY3_nwLliDtKw_8N-w",
   "use": "sig"
}

When generating the actual tokens, token header must contain following parameters with supported values

Parameter name	Supported values
typ	JWT
alg	RS256
kid	Key id matching a public key published by the issuers, that was used to sign the token

The access token body must contain following claims

Claim	Type	Description
iss	string	Issuer id as registered. Typically formatted https://tpg-app.com.
sub	string	Subject id. This should be equal to the iss string.
aud	string/list	Audience, identifies the microservice that will consume the token. Typically formatted https://tpg-app.com. Expected aud values are documented per microservice.
scope	string	Space delimited list of scopes the access token is issued for. E.g. pay:processPayments.
iat	number	Issued At time as unix timestamp in seconds.
expt	number	Token Expiration Time as unix timestamp in seconds. Token validators may reject tokens if the validity period is too long.
nbf	number	Not Before Time as unix timestamp in seconds.
tenant_ern	string	Full ERN identifying the tenant whose data is to be accessed with the token.E.g. ern:provetcloud/tenants/118
tenant_name	string	Human-readable display name for the tenant
user_ern	string	Full or relative ERN pointing to the authenticated user to whom the token was issued E.g. ern:provetcloud/tenants/users/54 or //users/54

See main.py on generating keys and signing requests.

Scopes

All the Payment Gateway API requests require an access token with at least one of following scopes. Required scope(s) for each route/set of routes to be documented. The scope string must be included in the JWT access token scope claim.

The scopes are currently tenant-wide, and cannot be tied to a company, even if the tenant has multiple companies.

Scope	Description
pay:processPayments	Make payment requests (online or PoS), process payments and refunds. View and delete tokenized cards.
pay:chargeToken	Make charges using payment methods tokenized for a shopper.
pay:manageIntegration	Full access to all tenant settings (payment methods, payout settings, stores, terminals…), transactions, payout and reports
subhub:subscribe	Handle subscriptions with subhub

Registering with NHP

NH Pay must be configured to allow authentication for your product. Contact NH Pay team:

• Provide jwks_uri (which exposes the public key for JWT signs) for your integration

• Establish product name (within NHP integration) and issuer URI for the JWT tokens. NH Pay team will provide you the unique identifiers after verification.

• For limited integration, access needs to be explicilty granted on behalf of the existing integrated product. So specify the product and its tenants (e.g. Provet Cloud id’s)

• Wait for NHP Team to communicate that authentication has been configured.

• Once you have the ok from NH Pay Team (and the provided product name and issuer URI), test the authentication by doing API GET /info/ request

• You use the same authentication to subscribe to Subhub notifications as well