What is an API key?

An API Key is an authentication method that validates a user that is sending data to the Payrix API (including both Merchant and Pro/Referrer users). Anytime a user submits data to Payrix, regardless if they are creating a resource (POST), updating a resource (PUT), or simply querying a resource to pull up information (GET), their API Key must be included in the HEADER of the request in order to validate that the user has the correct permissions to perform the request and to ensure that any data they submit is mapped to the correct entities and resources associated with the user.

For example, when a Pro client is submitting a new Merchant for onboarding to Payrix, the API Key validates their user’s permission to create new Merchants, in addition to communicating to the API how to map the incoming data to ensure the new Merchant is associated with the correct division.

For this reason, a user’s API Key should be kept strictly confidential much as any login and password would be. Someone with access to a user’s API Key has the ability to create changes within the Payrix API on their behalf and gain access to the user’s sensitive data that is stored within Payrix.

Private API Keys vs. Public API Keys

Certain Payrix solutions are integrated in a way that in order to maintain PCI compliance requires a user to share their API Key. For example, when a Merchant is utilizing our integrated payment pages to accept transactions securely on their website, their customer is submitting the payment directly to the Payrix API on the Merchant’s behalf.

Meaning, the sensitive card data submitted by a customer via an integrated payment page on a Merchant’s website is sent directly from the customer’s web browser server to the Payrix API, without passing through the Merchant’s server. Because this data is coming directly from the customer, and not from the Merchant, the payment submission must include an API Key to ensure Payrix maps the incoming transaction data to the correct Merchant.

Therefore, we categorize API Keys into two types:

Private API Keys

Private API Keys are confidential and should not be shared with anyone. This is the API Key Payrix users will include when directly making a create, update, or query request to a resource in the API.

Public API Keys

A user can also generate a Public API Key that is intended to be shared so that others can interact with Payrix directly in certain scenarios. Public API Keys are limited in their scope and access to very specific API resources and actions, and can only be used in the specific scenarios for which they are designed. Thus, Public API Keys are safe to share because they will not grant full access to create, update, or query all of the user’s resources within the API.

In the example of integrated payment pages, the Merchant will generate a Public API Key and embed it in their script to be automatically shared with the customer’s web browser as they pay on the Merchant’s site. This allows the customer to bypass the Merchant’s server and submit sensitive payment data directly to Payrix.

This Public API Key will give the customer’s browser the ability to send a create request (POST) to the /txns resource on the Merchant’s behalf, but will not give them access to any private resources or other request types. When the customer actually submits the payment directly to Payrix, the Public API Key will be included and inform the API which Merchant/user the incoming transaction data is related to.

Public API resources and request types

Currently, these are the API resources and request types that can be accessed with a Public API Key:

Related articles