Tl;dr
A good rule of thumb for the type of token to use:
For receiving money with the PaymentRequest endpoint use a Merchant Token.
For everything else, including creating, but not approving payouts, use a User Token.
For approving payouts a Payout User Token will be automatically created when you complete a multi-factor authentication check on the MoneyMoov portal.
Most calls to the MoneyMoov API require authentication with a JSON Web Token (JWT). The API uses three types of access tokens:
-
User access tokens, which are used for operations where user authorisation is required. Generating a new User access token requires a multi-factor authentication check. User access tokens expire after 1 day, see Refresh Tokens for how to renew them.
-
Merchant access tokens, which are used for creating payment requests, are suitable for use in a configuration file on a web server or in a similar unattended scenario. Merchant access tokens do not expire.
-
Payout User access tokens, which are used for approving payouts and satisfy the Strong Customer Authentication regulatory requirements. This token type is not available for use by 3rd party applications. See Authorizing a Payout.
Both the User and Machine access token are used by placing the token in the HTTP Authorization header, as specified in the OAuth 2.0 Bearer Token Usage specification.
curl https://api-sandbox.nofrixion.com/api/v1/metadata/whoami -H "Authorization: Bearer eyJhbGciOiJSUzI1N...."
An example of checking a JWT access token can be found on the Testing Authentication page.
Getting an Access Token
You can obtain a User or Machine access token by logging into the Sandbox Portal and selecting the API Tokens option. You will also need to specify:
-
The merchant the token is associated with (if the user is associated with multiple merchants).
-
The type of token (merchant or user).
Protecting User Access Tokens
Until it is explicitly revoked or expires, your JWT User Access Token grants access to your MoneyMoov API resources. For clarity, the examples in the documentation show the access tokens in the code. However, in production your tokens should be properly protected and should not be disclosed to untrusted parties or stored in source code repositories. Ideally they should be stored in a password manager, key vault or equivalent.
Refresh Tokens
When generating a User access token you will also shown a refresh token.
Refresh tokens allow a new access token to be generated, ideally when the original access token has expired, as described in the OAuth 2.0 Refresh Access Token section. The MoneyMoov API token refresh method can be used to acquire a new access token without requiring a multi-factor authentication check.
Protecting Refresh Tokens
Refresh tokens can be used to acquire a new access token and should be given the same level of protection as the access token.