Best Practice
Even if you're not working with OAuth 2.0 and access tokens, please consider these safety suggestions when working with the MobilePay Platform.
Keeping credentials secure is important whether you're developing open source libraries, or in this case, an MobilePay API integration for your product. 
Client ID and Client Secret

As a Developer of MobilePay API's , you'll be working with credentials issued to you from MobilePay, as well as tokens. 

  • Client ID
    • Your Client ID is one piece of information used to identify your application and frequently appears in OAuth negotiation URLs and other contexts. Your Client ID can be shared freely in code and email and cannot be used alone to act on your application's behalf.
  • Client Secret
    • Your Client Secret should be treated delicately. It is how you securely identify your application's rights and identity when exchanging tokens with MobilePay. Do not distribute client secrets in email, distributed native applications, client-side javascript, or public code repositories.
      • If your secret leaks, no use crying over it like spilled milk. Regenerate your secret using the "reset" button.
Best Practice - Tokens 
  • Do not hard-code any tokens into your code, instead use a database to store tokens.
  • Delete the token immediately from production and back-ups, if you no longer have the need for the merchant token
  • Validate TLS certificate chains: the client must validate the TLS certificate chain when making requests to protected resources. Failing to do so may enable DNS hijacking attacks to steal the token and gain unintended access
  • Always use TLS (https): Clients must use TLS (https) or equivalent transport security when making requests with bearer tokens. 
  • Don't store bearer tokens in cookies: implementations that do store bearer tokens in cookies MUST take precautions against cross-site request forgery. 
  • Use a OpenID Connect library that has built-in token management 
  • Ensure that there is no way of exposing the merchant token (or the functionality of that token) to another user by accident. 
  • Be aware of the fact that access can be revoked at any time. Once consent is revoked, the integrator will not be able to use the access token or the refresh token. You will need to get consent again.  
  • Protect all types of tokens and secrets. Keep them secret. Keep them safe. It is your responsibility to keep them secret 
  • Adhere to the principle of least privilege. Applications should never request more than the minimum permissions needed to function properly. 
  • We recommend that after you complete local development, remove localhost and related domains from your configuration list.
  • Do not send us your tokens. 
  • The tokens should never be exposed. 
  • We recommend that you use middleware or one of the existing open source third-party libraries to parse and validate JWTs. At, you can find libraries for various platforms and languages, such as .NET, Python, Java, Ruby, Objective-C, Swift, and PHP.
Refresh token 

  • Focus on having logic, that ensures that when you use access token, then you also check if it is expired. The logic should tell you, for how long the access token is valid, so that you can know, when it is time to refresh the access token,  without making a call to MobilePay service and receiving 401. When it is expired, then you can use refresh_token to get a new valid  access token.
  • The  refresh_token  are subject to strict storage requirements to ensure that they are not leaked.
  • Although  access token can be renewed at any time using refresh_token, they should only be renewed when old ones have expired, or when getting access to a new resource for the first time.

You should only ask for a new token if the access_token has expired or you want to refresh the claims contained in the ID Token. For example, it's a bad practice to call the endpoint to get a new access_token every time you call an API.

Please avoid hitting the rate limits in that will throttle the amount of requests to this endpoint that can be executed using the same token from the same IP.

The long-lived refresh_tokens must never be exposed. If you have any suspicion that they might be, you should contact us at or the merchant in question, so the token can be revoked. 

Refresh_tokens  must be stored securely by an application since they allow a user to remain authenticated essentially forever.

Connecting to the API
With your tokens and the API documentation, you have everything you need to start working on your MobilePay integration.
To be able to use and connect to the API there are few requirements. 
  • Application has to be created in the Developer Portal.
  • x-ibm-client-secret is required in the Authorization  header.
  • x-ibm-client-id is required in the Authorization header.
  • access_token is required in the Authorization header.

The x-ibm-client-id and x-ibm-client-secret are generated after the application is created on the My apps page on the Developer Portal. The x-ibm-client-id and x-ibm-client-secret can be found when clicking the app icon after the app is created. When making requests, the x-ibm-client-id, x-ibm-client-secret, and access_token are sent as headers in each request. Note that both, x-ibm-client-id and x-ibm-client-secret are always sent, in every single request made towards the API.

What's next?

Now that you've gone through the OpenID Connect Flow, let's start looking at testing. Depending on which API product you're integrating, click the links below:

Previous step