Skip to main content
Skip table of contents

PayFields - Best Practices

PayFields and PayFrames are used as hosted checkout fields on public payment pages, such as shopping card checkout, company payment pages, donation pages, and other publicly viewable payment pages.

As these payment pages are used publicly with customers, they may become vulnerable to general card testing misuse or attacks. To mitigate these types of security risks and deter misuse, follow the best practices for security while using PayFields in a public setting.

API Keys

API Keys, used to authenticate the PayFields transaction, can be public or private. It is important to follow the best practices below to ensure you’re using the correct API Key. Each API key will also inherit the level of access from the user that it is associated with.

Users can add take simple steps with their API Keys to keep them secure and prevent card testing misuse and attacks:

  • Never use a private API Key to configure a public PayFields payment page.

  • Create a dedicated user to host the API key and control or limit access.

  • Create new “rolling” API Keys every 6 hours if you suspect your original API key has been compromised. (See steps below).

Create a "Rolling" API Key
  1. Utilizing your private/master API key, create a new API key using the dedicated user from earlier.

  2. Apply this new API key to your PayFields setup

  3. Every 6 hours, create another new API key with the dedicated user and update the PayFields API Key.

  4. Delete the previous API key 2 hours after you have updated the PayFields.

It is best to wait about 2 hours to deactivate the previous API key as a user may have the page opened, where old key is still cached.

Transaction Session Keys

Transaction Session Keys (also known as txnSession, used instead of “rolling” API Keys, can be used to refresh the generated authentication for payment transactions, using PayFields and PayFrames. These Session Keys are used to mitigate misuse by third parties, such as bot attacks using fraudulent card numbers.

Use the method below to generate a Session Key:

Generating a Session Key

Request URL & Headers

CODE
POST /txnSessions HTTP/1.1
Accept: application/json
Host: api-test.payrix.com
Content-Type: application/json
APIKEY:{{private_api_key}}

Example Request Body

JSON
{
    "merchant": "p1_mer_000000000000001",
    "configurations": {
        "duration": 8,
        "maxTimesApproved": 4,
        "maxTimesUse": 10
    }
}

Required Parameter

Type

Description

Valid Values

merchant

string

The ID of the Merchant requiring the Session Key.

configurations

data object

Session Key setup info object.

duration

number

Minutes this key will be active.

Any attempted transaction will be automatically voided if the txnSession has expired.

Minutes in whole number format.

Example: 8 = 8 minutes

maxTimesApproved

number

The maximum number of transactions that can be approved with this session key.

Quantity in whole number format.

Example: 4 = 4 approvals.

maxTimesUse

number

The maximum number of times transaction approval requests can be made with this key.

Quantity in whole number format.

Example: 10 = 10 approval requests.

Example Response Body

JSON
{
    "response": {
        "data": [
            {
                "id": "p1_tss_653b2037aad3277a8b69317",
                "created": "2023-10-26 22:28:07.7053",
                "modified": "2023-10-26 22:28:07.7053",
                "creator": "000000000000001",
                "modifier": "000000000000001",
                "login": "000000000000001",
                "merchant": "000000000000001",
                "status": "created",
                "configurations": {
                    "duration": 8,
                    "maxTimesApproved": 4,
                    "maxTimesUse": 10
                },
                "durationAvailable": 8,
                "timesUsed": 0,
                "timesAppoved": 0,
                "key": "06d8bf10eb9ea112b63bfc306c953224"
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Response Parameter

Type

Description

Valid Values

id

string

The new txnSession ID.

created

timestamp

The date and time the session key was originally created.

modified

timestamp

The date and time the session key was last modified.

creator

string

The user Login ID for the user that created this txnSession.

modifier

string

The user Login ID for the user that created this txnSession.

login

string

The Login ID for the Merchant user associated with the txnSession.

It is recommended to use the Merchant’s Admin User

merchant

string

The ID of the Merchant requiring the Session Key.

status

string

The status of the txnSession is either [newly] created, [currently] in use, or deleted (manually or expired).

Valid Values:

  • created

  • inUse

  • deleted

configurations

data object

Session Key setup info object.

duration

number

Minutes this key will be active.

Any attempted transaction will be automatically voided if the txnSession has expired.

Minutes in whole number format.

Example: 8 = 8 minutes

maxTimesApproved

number

The maximum number of transactions that can be approved with this session key.

Quantity in whole number format.

Example: 4 = 4 approvals.

maxTimesUse

number

The maximum number of times transaction approval requests can be made with this key.

Quantity in whole number format.

Example: 10 = 10 approval requests.

durationAvailable

number

The remaining number of minutes available for the txnSession time.

This will directly correspond to the duration field value and will automatically decrease from that preset value when the status is changed from created to inUse.

timesUsed

number

The number of requests for transaction approval that have been made.

This will directly correspond to the maxTimesUse field value and will decrease from that value as more approval requests are made.

timesAppoved

number

The number of transaction approval requests that were approved.

This will directly correspond to the maxTimesUse field value and will decrease from that value as more approval requests are made.

key

string

The actual Txn Session Key, used in place of the public API Key for testing.

When creating new test transactions that require approval normally obtained using the API Key, utilize the key value provided when creating a txnSession (Transaction Session Key) in place of the API key placeholder:

JS
// txnSession Key
PayFields.config.txnSessionKey = "TXNSESSIONKEYValue";
// Merchant id
PayFields.config.merchant = "t1_mer_123456789101112";

More Best Practices

Using PayFields to Create Payment Tokens

By using PayFields to create a token rather than directly process the transaction you could prevent actual card transactions from being attempted unless processed through the API using a tokenized version of the card, adding layer of security.

This will allow you to create velocity controls within your own environment. If you notice traffic coming from a specific source that is higher than expected, you can block it before it even comes through to Payrix

See the steps below to create tokens with PayFields:

Create a Token (only) with PayFields
  1. Create a login that will be dedicated to PayField transactions

  2. Create a public API key associated with this login

  3. Set the permissions on the login to only be able to create tokens

  4. Set up your PayFields to only create tokens

  5. When the customer runs their payment request, you will receive the token ID

  6. Run a sale transaction from your host server via the Payrix API using the token

  7. Respond to the customer with the result of the transaction

Add a Failed Authorization Transaction Rule

Another recommended security measure is to add a “failed authorization rule” on all Merchants.

This rule will quickly identify card testing misuse and block additional transactions after the number of declines has exceeded that rule. This lack of function will deter the misuse and mitigate any additional exposure from card testing misuse or attacks.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.