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).

  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:

Request URL & Headers

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

Example Request Body

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

Required Parameter

Type

Description

Valid Values

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

{ "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

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.

 

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.

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.

 

timesUsed

number

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

 

timesAppoved

number

The number of transaction approval requests that were approved.

 

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:

 

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:

  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.