API Key Management

Overview

Managing your API keys is the crucial aspect of maintaining the security and functionality of your PayConex™ integration.

The guides in this section cover the two primary methods for managing your API keys:

• Using the PayConex™ UI
• Using the PayConex™ API

Before diving into those topics, it is a good idea to take a look at the following section and the related scope definitions.

Introducing API Keys

Understanding the structure of an API key is crucial for effective API Key Management. Below is a breakdown of the JSON object that represents an API key, with explanations for each property. First, let's see how an API key is created. For the rest of the operations, refer to Using the PayConex™ API.

Creating an API Key

It is important to note that there are two ways to create an API key via the V4 API: using the basic authorization of another API key or via PayConex™ Portal. The basic one is simply another key with the permission scope pcx:api_key:* to start with.

POST /api/v4/accounts/{accountId}/api-keys

{
  "methods": [ "HMAC", "BASIC" ],
  "accounts": [
    "220614965201",
    "123456789012"
  ],
  "scopes": [
    "pcx:api_key:*",
    "pcx:iframe:*",
    "pcx:iframe:instance:*",
    "pcx:payments:*"
  ],
  "label": "API-Key-Test"
}

*Required Scopes: pcx:api_key:*, pcx:api_key:create, pcx:iframe:*, pcx:payments:*, pcx:iframe:instance:*

🚧

Important

Keep in mind that in order to create another key using the basic headers of an API key, it is necessary that the initial API key includes all of the scopes that the new API is defining.

For example, this is the key we are using to create another key.

JSON

{
  "id": "api_ff00c6379993428f9a82a3d3c61f5a18",
  "secret": "c20652647cec474a86effcd8dd6b1c4b",
  "label": "API-Key-Test1",
  "methods": [
    "HMAC",
    "BASIC"
  ],
  "scopes": [
   "pcx:api_key:*",
    "pcx:devices:*",
    "pcx:webhooks:*"
   ],
  "accountId": "220614965201",
  "createdAt": "2025-01-21T13:32:45.000000Z",
  "updatedAt": "2025-01-21T13:41:11.000000Z",
  "enabled": true
  }

Now, if we try to create another key with the following scopes.

JSON

{
"methods": [ "HMAC", "BASIC" ],
"scopes": [
   "pcx:payments:capture",
   "pcx:payments:refund"
   ],
   "label": "API-Key-Test1"
  }

JSON

{
"message": "API Key does not have permission to add scope pcx:payments:capture (and 1 more error)",
"errorCode": 40001,
  "errorType": "invalid_request",
  "source": "scopes.0",
  "value": "pcx:payments:capture",
  "traceId": "7135a36f-5869-40fe-826b-099425ac525a",
  "details": [
   {
     "source": "scopes.0",
      "value": "pcx:payments:capture",
      "message": "API Key does not have permission to add scope pcx:payments:capture"
    },
    {
      "source": "scopes.1",
      "value": "pcx:payments:refund",
      "message": "API Key does not have permission to add scope pcx:payments:refund"
    }
   ]
   }

After we modify the API key above to contain the necessary scopes, another API key will be successfully created. For more, see Using the PayConex™ API: Editing an API Key.

Response

{
  "id": "api_99d97b************eabafc2044005b",
  "secret": "c79de0415************ffa5a201b0e",
  "label": "API-Key-Test",
  "methods": [
    "HMAC",
	"BASIC"
  ],
  "accounts": [
    "220614965201",
    "123456789012"
  ],
  "scopes": [
    "pcx:api_key:*",
	"pcx:iframe:*",
	"pcx:iframe:instance:*",
	"pcx:payments:*"
  ],
  "accountId": "220614982061",
  "createdAt": "2023-12-20T20:36:49.000000Z",
  "updatedAt": "2023-12-20T20:36:49.000000Z",
  "enabled": true
}

Property Breakdown

Scope Definitions

A PayConex™ API key can have multiple permissions that, when selected, enable access to various features and functions provided by PayConex™. For example, there are scope namespaces for:

• API Keys
• Checkout Component Configuration
• Checkout Component Instance
• Payment Processing
• Webhooks
• Account Updater API
• Level 3 Profiles
• 3D Secure

To see the full list of the scope definitions, check out the Scope Documentation.

Payment Processing

Similar to other top-level scopes, these can become more specific depending on the purpose. If the merchant creates multiple API keys, each serving a different set of scopes or purposes, they can refine the wildcard to target a specific scope.

For example,

POST /api/v4/accounts/{accountId}/api-keys

{
  "methods": [ "HMAC", "BASIC" ],
  "accounts": [
    "220614965201",
    "123456789012"
  ],
  "scopes": [
    "pcx:payments:card_not_present:credit",
    "pcx:payments:device:credit",
    "pcx:payments:refund"
  ],
  "label": "API-Key for credits and refunds only"
}

*Required Scopes: pcx:api_key:*, pcx:api_key:create

📘

Note

For all of the scope definitions, refer to API Reference.

Common Errors

These are some of the most frequently occurring API errors, as demonstrated in the examples below.

Unauthorized Error

{
  "message": "Unauthorized",
  "errorCode": 40003,
  "errorType": "authorization",
  "source": "Headers",
  "value": "Authorization",
  "traceId": "9e5683f7-cf1e-4304-9ee5-5b6999075eef"
}

This error typically signifies that the request lacks the necessary permission scope. It is crucial to verify and ensure that your API keys are set up correctly and have the appropriate permissions.

Possible Causes

1. Insufficient permissions: The API Key used may not have the required scope or permissions to access the requested resource.
2. Incorrect accountId: Make sure to create the API key under the same accountId.

Unauthenticated Error

{
  "message": "Unauthenticated",
  "errorCode": 40002,
  "errorType": "authentication",
  "source": "Headers",
  "value": "Authorization",
  "traceId": "56bfa8f4-e731-4408-9ede-6d37ceea59bc",
  "details": []
}

Possible Causes

1. Missing or incorrect authorization header: The request may be missing the Authorization header, or it may contain an incorrectly formatted Base64 token.
2. Invalid credentials: The credentials used might be incorrect or have been revoked.
3. HMAC authentication: To ensure the request body matches the one used to generate the HMAC hash, generate the hash precisly as it can be seen in our example script. We recommend removing all white spaces. See HMAC Script.
4. API Key Expiration or Deletion: The API Key used for the authentication might have been expired or deleted.