PayNearMe’s application programming interface (API) enables your software applications to interact with the PayNearMe platform using standard HTTP protocols within a PCI-compliant architecture. It also can be used to define development/partner silos and is typically accompanied by a set of access rights associated with a corresponding API key. An API key is a code used to identify and authenticate an application or user of the API. Each API key defined by PayNearMe is good for one year. These keys identify partners, developers, and/or programs attempting to access PayNearMe’s platform.

This document provides an overview of PayNearMe’s API key rotation policies and provides guidelines on how to manually and programmatically rotate keys.

Why Use API Keys?

API keys are commonly used to control the utilization of the API’s interface and track how it is being used. This is often as a precaution to prevent abuse or malicious use. Common reasons to use API keys include the following:

API keys are used in projects to provide authentication that identifies users and the project
API Keys are tied to the transmission of customer personal information (PII)
API Keys are tied to credit card data transmission (PCI)

PayNearMe’s Key Rotation Policy

Your PayNearMe API key is good for one year, which complies with the PCI DSS standard for online credit card payments. When your API keys are within three months of expiration, PayNearMe’s Account Management team will notify you of the upcoming key expiration and then

Create an agreed-upon plan to implement and validate a new key in the test environment.
Develop a plan to implement the new production key well before the expiration date of the existing API key.
Execute the new API key rotation and validate that the solution is working as expected.

❗️
Security Incidents
In the event of a security incident where a key has been compromised, PayNearMe recommends that you immediately rotate the old key as part of remediation and mitigation efforts.

Merchants, or in some cases the ISV partner on behalf of the merchant (dependent on implementation schema), are responsible for updating their API keys.

👍
Assistance
PayNearMe does not have access to the generated keys for security purposes. Therefore, PayNearMe's staff does not have the ability to update API key. They can, however, assist you in the key rotation process.

Rotating Your API Keys

As part of an API Integration with PayNearMe, organizations need to establish secure communication between both parties. This requirement is satisfied by generating and using organization-specific signatures that are unique to that call.

PayNearMe’s API requires a hash-based message authentication code (HMAC) signature for all calls and callbacks. This authentication method protects the integrity of request messages and helps to prevent malicious attacks. 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.

To successfully generate a signature and a request, you’ll need active API keys for the corresponding version of the API you’re using. API keys can be generated manually or programmatically via API call.

Generating API Keys Manually

To view your currently defined API keys (if applicable):

Log in to the 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.
Once you’ve logged into your account, navigate to the Developer tab at the top of the page.
In the menu on the left hand-side, select API Documentation > API Keys & Signatures.
The Business Portal displays a list of available API keys and provides you with the ability to create new API 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 will see one or more keys assigned to your organization in a table.

This table includes the following data about each key:

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. To create a new API key pair, complete the following steps:

Enter a name for the new key (that makes sense to your organization) in the Nickname field.
Enter an email address (use the email address used to log into the Business Portal) in the Email field.
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.
Push the Create button. A confirmation message displays.

❗️
Reminder!
Keep a copy of the key pair in a safe location and do not share your secret key with anyone. The secret value will not be available after you move from this screen. If you lose your secret key, you will need to create a new key and revoke the previous one.

🚧
Key Pair Versions
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).

Generating API Keys Programmatically

You can simplify the process of creating and managing API key pairs by using version 3 of PayNearMe’s 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.

📘
Partner Implementations
Partners who manage keys for their merchants must manually create/rotate their version 3 key pair before programmatically creating keys for merchants.

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 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
`email`	The email that will be associated with this key pair.	string
`nickname`	A short description of the key pair.	string
`api_key_version`	`3.0` NOTE: Keys for other API versions (i.e., `1.8` or `2.0`) can be created in version `3.0` using the HMAC signature. When using these later version keys to make calls however, you will need to create your signature using the MD5 algorithm (e.g., `Digest::MD5.hexdigest(string_to_sign + secret_key).downcase`). As a best practice, PayNearMe strongly recommends that clients transition to the version `3.0` API so that call signatures can be hashed using the more secure, up-to-date SHA256 algorithm. Your PayNearMe Technical Account Manager can help you manage this transition.	string
`timestamp`	The Unix Epoch time of the call.	string
`version`	`3.0`

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

Create an API Key

Request

curl -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": "[Kevinnewkey@paynearme.com](mailto:Kevinnewkey@paynearme.com)",  
  "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, contact 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 ( Developer> 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.

📘
Revoking Keys
Once a key is revoked, it cannot 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, complete the following steps:

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 next to the key you want to revoke. The Business Portal displays the key pair with a status of revoked.

Revoking a Key Programmatically

To revoke a key pair via the API, use the following required parameters in the /revoke_api_key HTTPS POST call.

Parameter	Description	Type
`signature`	The HMAC signature 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

Revoke an API Key

Request

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": "Kevinnewkey@paynearme.com",  
   "expiration_date": "2022-02-02",  
   "active": false,  
   "version": "3.0",  
   "status": "ok"
}

Retrieving a List of API Keys

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

The /list_api_keys call requires the following parameters.

Parameter	Description	Type
`signature`	The HMAC signature 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

List All API Keys for a Site

Request

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": "kevinapikey@paynearme.com", 
         "expiration_date": "2022-02-02", 
         "active": true, 
         "version": "3.0"  
      }
   ]
}

Who do I contact when I have questions?

If you need further assistance, contact the PayNearMe Support Team.