About API authentication

The Instant Bank Transfer API uses the industry-standard OAuth 2.0 framework to authenticate and authorize applications to make API calls. Together, the client ID, client secret, and app ID identify the client and which functionalities it can access.

When the authentication and authorization process is complete, the merchant system receives an access token, which needs to be included in the header of every API call.

NOTE

Before you can authenticate, you must obtain a client ID, client secret, and an app ID from the merchant Integration team. You’ll need these credentials to request an access token for the staging environment. After your system integration is complete, you'll receive separate credentials to use in the production environment.

Getting an access token

Request

Access tokens are retrieved via the OAuth Client Credentials flow, which is used for server-to-server authentication. With the client credentials flow, the merchant system must securely store its client ID and client secret, and pass them to the authentication server in exchange for an access token.

In addition to the client ID and client secret, the grant type, which specifies that we're using the client credentials flow, and content type is passed in the header of a request sent to the authentication token URL:

POST https://auth-mint.paramountcommerce.com/oauth2/token

Parameter	Description
grant_type	This is always submitted as client_credentials.
client_id	The client ID assigned by Paramount.
client_secret	The client secret assigned by Paramount.
content-type	For access token requests, this is application/x-www-form-urlencoded.

curl --request POST \
--url "https://auth-mint.paramountcommerce.com/oauth2/token" \
--data "grant_type=client_credentials&client_id=<assigned client ID>&client_secret=<assigned client secret>" \ 
-H "Content-Type: application/x-www-form-urlencoded"

Response

Parameter	Description
access_token	The bearer token retrieved from the authorization server.
expires_in	The time, in seconds, until the token expires.
token_type	This is always Bearer.

{
  "access_token": "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
  "expires_in": "1800",
  "token_type": "Bearer"
}

Using an access token

Instant Bank Transfer uses Bearer authentication, which uses security tokens called bearer tokens. The bearer token is one of the parameters that must be included in the header of each API call.

Headers

All transaction and reporting API calls require the following headers:

Authorization: Bearer token
Content-Type: application/json

Authorization: Bearer eyJraWQiOiJMaEV3SHIzWnhlUzFYcnBNWVh2OG0yVlFua3JYb1wvSzRoclZkWGlRSW1kST0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI2d
Content-Type: application/json