Integrated Payment Pages: Best Practices

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

Use Transaction Session Keys

To enhance security, replace rolling API keys (see Implement a Rolling API Key System) 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.

Generating a Session Key

Use the API request shown to generate a transaction 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 the key will be active. Important: 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`. Note: The Merchant’s Admin User is recommended.	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. Important: 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. Note: 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. Note: 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

Note

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

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 six hours if you suspect your original API key has been compromised. See the following section for the steps to implement a rolling API key system.
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 six 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 two hours after updating the PayFields or PayFrame API key value.

Note

You should wait about two 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.

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:

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.