Using Dynamic Descriptors

A dynamic descriptor (also known as a soft descriptor) is a customizable set of information that can be included with a credit card transaction. It can consist of a merchant descriptor, as well as city and state information. This is particularly useful in instances where a merchant's descriptor might differ from the merchant's default DBA (doing business as) name, which is configured with the back-end processor.

📘

Note

This feature currently is only available for accounts using the PayConex interfaces for FIS Express or Fiserv RapidConnect, or Elavon for processing.

When a dynamic descriptor value is sent with a transaction, the merchant's end-customer will see the dynamic descriptor information on their card statement instead of the default DBA information. This feature can help provide more context to customers about their transactions, and potentially reduce chargebacks due to customers misidentifying the merchant based on the descriptor seen on their account statements.

The first step to using dynamic descriptors is to log into your PayConex account and create a descriptor. After creating a descriptor, it can be applied to a transaction using a reference passed with a PayConex API request. When that reference is used, PayConex will utilize the descriptor data when processing the transaction.

Creating a Dynamic Descriptor

To create a dynamic descriptor, a user will log into their PayConex account and navigate to the Settings tab, and then click the Dynamic Descriptors link.

📘

Access to this feature requires enablement by a Bluefin administrator. Please contact [email protected] for more information.

After following this link, the user will see a table that includes any currently configured descriptors that exist on the account.

To begin creating a new descriptor, click the Add New Descriptor button.

A form will display where a user can input the name, city, state, and descriptor.

The name field is the value that will be used in a PayConex API request to process a transaction with the desired city, state, and descriptor.

The name field allows 25 alphanumeric characters (no dashes underscore, or spaces) and must be unique for each descriptor created within a PayConex account.

The descriptor field allows 25 characters. The city field allows 13 characters, and the state field allows 2 characters.

Click the Add Descriptor button and the form will close and the table will display the newly created descriptor.

Using a Dynamic Descriptor in a Transaction

After creating a dynamic descriptor, you will use the name of the descriptor as the value for the PayConex API parameter dynamic_descriptor_name.

For example, in the cURL request below, the dynamic_descriptor_name value is set as LOC001, which references the descriptor we created above.

curl --request POST
--url https://cert.payconex.net/api/qsapi/3.8/
--header 'Content-Type: application/x-www-form-urlencoded'
--data account_id=220614966801
--data api_accesskey=32d42f0f0b6c89616d42aed8c96801r6
--data tender_type=CARD
--data transaction_type=SALE
--data transaction_amount=1.00
--data response_format=JSON
--data card_number=4444333322221111
--data card_expiration=1222
--data first_name=Bluefin
--data last_name=Test
--data dynamic_descriptor_name=LOC001

If the dynamic_descriptor_name and all other parameters in the request are valid, then the PayConex API response won't look any different than it would for a typical transaction.

Here is an example JSON response where the transaction was approved:

{
	"transaction_id": "000000037666",
	"tender_type": "CARD",
	"transaction_timestamp": "2023-04-03 09:50:14",
	"card_brand": "VISA",
	"transaction_type": "SALE",
	"last4": "1111",
	"card_expiration": "1222",
	"authorization_code": "041303",
	"authorization_message": "APPROVED",
	"request_amount": 1,
	"transaction_amount": 1,
	"first_name": "Ryan",
	"last_name": "Test",
	"keyed": true,
	"swiped": false,
	"entry_mode": "keyed",
	"transaction_approved": true,
	"currency": "USD",
	"error": false,
	"error_code": 0,
	"error_message": null,
	"error_msg": null
}

However, If the dynamic_descriptor_name does not exist or is invalid, then you will experience an API error.

Here is an example JSON error response if an invalid dynamic_descriptor_name was used:

{
	"error": true,
	"error_code": 20325,
	"error_message": "dynamic_descriptor_name is invalid or does not exist.",
	"error_msg": "dynamic_descriptor_name is invalid or does not exist."
}