API Key Rotation - Manual Process and API Procedure

Overview

As part of an API Integration with PayNearMe, organizations need to establish secure communication between both parties. This requirement is satisfied by generating an organization-specific signature that can be used for secure communication.  

As a best practice, organizations should change their API Keys yearly to comply with PCI DSS requirements. This document will guide you through the process of changing your key (key rotation).

 

Technical Information

All PayNearMe API calls and callbacks must include a hash-based message authentication code (HMAC) signature. This authentication method protects the integrity of request messages and helps to prevent malicious attacks like cross-site scripting and brute-force attacks.

The HMAC signature values are calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.

NOTE: Our processes have changed to increase organizational security. PayNearMe no longer has access to merchant secret keys. 

Creating API Keys Manually

To create a new secret API key:

1. Login to the new PayNearMe Business Portal with an activated account. If you are asked to activate your account, complete the activation process before attempting to update your secret key. 

2. To manage keys, you must have Admin permissions enabled. Permission definitions listed here. If you do not have Admin permissions, a user with access to change permissions can enable this for you. 

3. Once you’ve logged in your account, navigate to Developer tab at the top of the page 

4. In the menu on the left hand-side, select API Documentation

5. Select API Keys & Signatures

 

Developer Tab

API Documentation Selection

The business portal displays a list of available API keys and provides you with the ability to createnewAPI key values.  Each key identifier and secret key pair are unique to your organization, and are used to sign and verify all API calls between your system and PayNearMe. 

Once you navigate to the Key Listing/Creation page, you may see one or more keys assigned to your organization.

 

This table includes the following: 

• Site/Key Identifier

• API Version of the key

• If the key is being used for Callbacks

• Status

• Expiration dates

Below the listing of currently available keys is a form where you can generate a new API key pair.  

NOTE: For security, PayNearMe strongly recommends that you do not share the secret keys.

IMPORTANT: When creating keys, you will only be able to view the secret key upon initial creation. If you lose your key you will need to create a new key and revoke the previous one.

Each key pair is tied to an API version. As you transition from an older API version to the latest, you will need to create a new key. Once the transition is complete, you can revoke the older key(s).

To create a new API

1. Enter a name for the new key (that makes sense to your organization) in the Nickname field.

2. Enter an email address (use the email address used to log into the Business Portal) in the Email field.

3. Select the appropriate API version from the API Version Number dropdown. NOTE: If you are in the process of upgrading, you might want to change the API number to a later version. If you are only rotating your current keys, just match the API key version listed in the current key list.

4. Push the Create button. A confirmation message displays.

 

IMPORTANT:  Keep a copy of the key pair in a safe location. The secret value will not be available after you move from this screen. If you lose this value, the key generation process will have to be repeated.  

NOTE: PayNearMe does not have access to the generated keys for security purposes.

Creating API Keys Programmatically

Merchants can simplify the process of creating and managing API key pairs by using the version 3 API. Always remember to create new keys before revoking the old keys. If you’re unsure what keys need to be revoked, you can perform a lookup that lists all the keys currently defined for your site.

To create a key pair via API call, use the following required parameters in the /create_api_key HTTPS POST call: 

Parameter	Description	Type
signature	The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.	string
site_identifier	The merchant’s unique Site ID.	string
api_version_number	3.0	string
email	The email that will be associated with this key pair.	string
nickname	A short description of the key pair.	string
timestamp	The Unix Epoch time of the call.	string
version	The version of the API you’re using. This version must match the version associated with your API key pair.	string

 The API can pass back both XML and JSON responses. Consult your PayNearMe Technical Account Manager (TAM) to set your language preference. 

REQUEST - Create an API Keycurl -X POST https://api.paynearme-sandbox.com/json-api/create_api_key -L -G \  -d api_version_number=3.0 \  -d email=Kevin%2Bnewkey%40paynearme.com \  -d nickname=new3.0key \  -d site_identifier=S6404173951 \  -d version=3.0 \  -d timestamp=1612313471 \  -d signature=12a7346cbe8e85455e4b4e73532aac1b4900b100162b43d8f0f439f5da65ba49

RESPONSE

{

  "key_id": "K3313795323",

  "nickname": "new3.0key",

  "email": "[e-mail]",

  "expiration_date": "2022-02-02",

  "active": true,

  "version": "3.0",

  "status": "ok",

  "secret": "97cabcc384094d109fcf34345"

}

What Can I Do with the New Key Pair?

The PayNearMe solution allows for up to 5 active keys. Creating a new key will not affect your current implementation. After generating the key, your merchant organization will need to determine when to start using the new key values.

Once you’ve generated your new key pair (i.e., key_id and secret key), you will need to update your organization’s existing implementation to use these new values. These values are required when submitting calls to the PayNearMe API (e.g., /create_order, /find_order, /make_payment, etc). Typically, these values are parameters in your organization's implementation of your management system. If you are unfamiliar where these new values are stored, please contact your loan management software solution or your PayNearMe Merchant Support representative.

After deciding when to use the new key sets, your organization will need to update the new key to be used for callbacks. Only one key at a time can be used with callbacks; therefore, new keys should only be selected when your organization is ready for migration.

To update a key to be used for callbacks, navigate to the listing of currently available keys (API Documentation > API Keys & Signatures) and select the Use for Callbacks radio button.

When Can I Remove Old Keys?

Old keys should be removed after they have expired AND the new keys have been validated and are working as expected. As an organization, you can maintain up to 5 different key pairs in your environment.  

IMPORTANT: Once a key is revoked, it can not be used again in the future. Only revoke the key pairs that are not in use.

Revoking a Key Manually

To revoke a key from the Merchant Business Portal, navigate to the API Keys & Signatures page (Developer > API Documentation > API Keys & Signatures). Scroll down the list of keys. Active key pairs will display a Revoke button.

Click the Revoke button. The Business Portal displays the key pair with a status of revoked.

 

Revoking a Key via API

To revoke a key pair programmatically, use the following required parameters in the /revoke_api_key HTTPS POST call:

Parameter	Description	Type
signature	The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.	string
site_identifier	The merchant’s unique Site ID.	string
key_id	The Key Identifier of the key pair.	string
timestamp	The Unix Epoch time of the call.	string
version	The version of the API you’re using. This version must match the version associated with your API key pair.	string

REQUEST - Revoke an API Key 

curl -X POST https://api.paynearme-sandbox.com/json-api/revoke_api_key -L -G \  -d key_id=K3313795323 \    -d site_identifier=S6404173951 \  -d version=3.0 \  -d timestamp=1612313926 \  -d signature=a07ed0147cd79ccf9f6379ee28bf8c0e05e47ab34555c9feffb4c96e03b70632

RESPONSE

{  "key_id": "K3313795323",  "nickname": "new3.0key",  "email": "[e-mail]",  "expiration_date": "2022-02-02",  "active": false,  "version": "3.0",  "status": "ok"}

If you do not know the key_id of the expired key pair you want to revoke, use the /list_api_keys call to lookup all the keys associated with your merchant site.

The /list_api_keys call requires the following parameters:

Parameter	Description	Type

Parameter	Description	Type
signature	The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request’s payload through the SHA256 message digest algorithm.	string
site_identifier	The merchant’s unique Site ID.	string
timestamp	The Unix Epoch time of the call.	string
version	The version of the API you’re using. This version must match the version associated with your API key pair.	string

REQUEST - List API Keys

curl -X POST https://api.paynearme-sandbox.com/json-api/list_api_keys -L -G \  -d site_identifier=S6404173951 \  -d version=3.0 \  -d timestamp=1612313233 \  -d signature=1fee3f7834360ca2bed46efef6e4ceb5ee5563d3f54fc9cc3fDe88c0807137c5

RESPONSE

{  "status": "ok",  "api_keys": [  { "key_id": "K4168172551", "nickname": "Default", "email": null, "expiration_date": "2021-05-08", "active": true, "version": "2.0"  },  { "key_id": "K9763085673", "nickname": "test key 3.0", "email": "[e-mail]", "expiration_date": "2022-02-02", "active": true, "version": "3.0"  }]}

Who do I contact when I have questions?

PNM Support Team