Integrated Payment Pages: Best Practices

PayFields and PayFrames serve as integrated checkout fields on various public payment pages, including shopping cart checkouts, company payment portals, donation pages, and other publicly accessible payment interfaces. Given that payment pages are publicly accessible, they can be vulnerable to card testing misuse and attacks. To protect against these threats and discourage misuse, it's essential to follow best practices when using PayFields or PayFrame in public environments.

Protect Your API Keys

API keys, used to authenticate PayFields and PayFrame transactions, must be public. 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 take simple steps with their API keys to keep them secure and prevent card testing misuse and attacks:

Do: Create a dedicated user login to host the API key and control or limit access.
Do: Create new “rolling” API keys every 6 hours if you suspect your original API key has been compromised. See Implement a Rolling API Key System below.
Don’t: Configure a public PayFields or PayFrame payment page with a private API key.

Implement a Rolling API Key System

To enhance the security and management of your API keys, follow these steps to implement a rolling API key system:

Create a New API Key: Using your public API key, generate a new API key with a dedicated user.
Update Your Setup: Apply this new API key to your PayFields or PayFrame setup.
Rotate API Keys: Every 6 hours, create another new API key with the dedicated user and update the PayFields or PayFrame API key value.
Deactivate Old Keys: Delete the previous API key 2 hours after updating the PayFields or PayFrame API key value.

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

For steps to generate new API keys, see Generating an API Key.

Use Transaction Session Keys

To enhance security, you can replace rolling API keys with transaction session keys, shown as txnSessionKey, to automatically refresh authentication in payment transactions. Using PayFields and PayFrame, these transaction session keys reduce misuse risks from third parties, including bot attacks that exploit fraudulent card numbers.

Use the API request shown in the Generating a Session Key section below to generate a Session Key:

Generating a Session Key

Request URL and 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_123abc4d567890efg1h2i34",
    "configurations": {
        "duration": 8,
        "maxTimesApproved": 4,
        "maxTimesUse": 10
    }
}

Required Parameter		Type	Description	Valid Values
`merchant`		string	The ID of the Merchant that needs the Session Key.	N/A
`configurations`		data object	Session Key setup info object.	N/A
	`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_123abc4d567890efg1h2i34",
                "created": "2023-10-26 22:28:07.7053",
                "modified": "2023-10-26 22:28:07.7053",
                "creator": "p1_log_123abc4d567890efg1h2i34",
                "modifier": "p1_log_123abc4d567890efg1h2i34",
                "login": "p1_log_123abc4d567890efg1h2i34",
                "merchant": "p1_mer_123abc4d567890efg1h2i34",
                "status": "created",
                "configurations": {
                    "duration": 8,
                    "maxTimesApproved": 4,
                    "maxTimesUse": 10
                },
                "durationAvailable": 8,
                "timesUsed": 0,
                "timesAppoved": 0,
                "key": "a12bc3d4e56f789g0h1ij23kl456789"
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Response Parameter		Type	Description	Valid Values
`id`		string	The new `txnSession` ID.	N/A
`created`		timestamp	The date and time the session key was originally created.	N/A
`modified`		timestamp	The date and time the session key was last modified.	N/A
`creator`		string	The user Login ID for the user that created this `txnSession`.	N/A
`modifier`		string	The user Login ID for the user that created this `txnSession`.	N/A
`login`		string	The Login ID for the Merchant user associated with the `txnSession`. We recommend using the Merchant’s Admin User.	N/A
`merchant`		string	The ID of the Merchant requiring the Session Key.	N/A
`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.	N/A
	`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`.	N/A
`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.	N/A
`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.	N/A
`key`		string	The actual Txn Session Key, used in place of the public API key for testing.	N/A

When generating new test transactions that require approval typically secured through the API key, use the key value obtained during the creation of a txnSessionKey instead of the API key placeholder.

JS

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

Create Payment Tokens

Using PayFields or PayFrame to generate a token instead of processing future transactions with genuine card information enhances security. Payment tokens ensure that live transactions can only be processed through the API. This crucial protection allows you to create velocity controls within your environment, so if unexpected transaction volume surges from a source, you can block it before it reaches Payrix.

To create tokens using PayFields or PayFrame, follow the steps outlined below for a general overview:

Establish a dedicated user login specifically for PayField or PayFrame transactions.
Generate a public API key from this login.
Ensure your PayFields or PayFrame backend JavaScript file is configured for token creation only, as shown in the example below:

JS

// PayFields: Token-Only Mode
PayFields.config.mode = 'token'
// PayFrame: Token-Only Mode
PayFrame.config.txnType = 'token'

Process the first Auth transaction for $0 to generate a token ID corresponding to the customer's payment information.
Process a second Sale transaction from your host server through the Payrix API with the /txns endpoint. Use the newly generated token ID value for the token parameter rather than re-entering the card information.
Communicate the transaction result back to the customer.

For specific steps for PayFields or PayFrame, see the PayFields Developer Guide or PayFrame Integration Guide.

Add a Failed Authorization Decision Rule

You can add a Failed Authorizations Decision Rule, found under the Merchant Transaction Risk Rule category of the Decision creation dialog to set a threshold for declines or failed authorizations and help you identify card testing misuse across your Merchants.

By setting a threshold for declines or failed authorizations, you can block further transactions after a specified number of failures, deterring misuse and reducing exposure to additional card testing attacks. See Using Decisions for Risk Mitigation for more information and setup steps.