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

Utilizing your private/master API key, create a new API key using the dedicated user from earlier.
Apply this new API key to your PayFields setup
Every 6 hours, create another new API key with the dedicated user and update the PayFields API Key.
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.

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

Create a login that will be dedicated to PayField transactions
Create a public API key associated with this login
Set the permissions on the login to only be able to create tokens
Set up your PayFields to only create tokens
When the customer runs their payment request, you will receive the token ID
Run a sale transaction from your host server via the Payrix API using the token
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.