Using Dynamic Descriptors

Overview

Before diving into this section, it is important to have a clear understanding of dynamic descriptors and their use cases, as they play a crucial role in providing transaction details to customers. Dynamic descriptors allow businesses to customize the information that appears on cardholder statements, enhancing transparency and reducing disputes. For an in-depth overview, refer to Legacy API Using Dynamic Descriptors.

In this section, we guide you through the process of utilizing dynamic descriptors with the PayConex™ V4 API. You will learn how to include a dynamic descriptor in your API calls to customize transaction information dynamically. Additionally, we cover other supported operations, including creating new dynamic descriptors, modifying existing ones, and retrieving dynamic descriptor details to manage them effectively.

📘

Note

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

Using a Dynamic Descriptor in a Transaction

When the name of a dynamic descriptor is included in the transaction request, it populates the dynamicDescriptor field and becomes a part of transaction metadata. This means that the descriptor data is available by getting a transaction by transactionId.

🚧

Note

A dynamic descriptor is required to be pre-created before using it in a transaction request. See Creating a Dynamic Descriptor.

For example,

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "bft_11...",
  "amounts":{
    "total": "5",
    "currency":"USD"
  },
  "posProfile":"ECOMMERCE",
  "dynamicDescriptor": "LOC001"
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Assuming a valid dynamicDescriptor name is provided, we get the following:

{
  "transactionId": "000000030646",
  "status": "CAPTURED",
  "timestamp": "2024-11-27T19:27:38.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "Kansas City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc.",
      "recipient": "Alice"
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "Kansas City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "transaction",
        "requestId": "97847854-6ebb-4b83-8e54-d7304261be9f",
        "correlationId": "7d7a2781-322d-43b6-b156-8d3337bdc235",
        "timestamp": "2024-11-27T13:27:35-06:00"
      }
    ],
    "networkTransactionId": "014332542301250G493"
  },
  "amounts": {
    "currency": "USD",
    "approved": "5.00",
    "requested": "5.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK2246",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "0.00"
  },
  "dynamicDescriptor": {
    "resourceId": "ddesc_de9182bf5eab4e12ad8d9f6faaaf57ca",
    "city": "Auburn",
    "state": "AL",
    "descriptor": "PayConex V4 Sale 001"
  }
}

Otherwise, we receive:

{
  "message": "Dynamic Descriptor was not found, or has been deleted",
  "errorCode": "40001",
  "errorType": "invalid_request",
  "source": "dynamicDescriptor",
  "value": "LOC001",
  "traceId": "c9769d48-227b-44f4-acbc-1a35fde4007a",
  "details": [
    {
      "source": "dynamicDescriptor",
      "value": "LOC001",
      "message": "Dynamic Descriptor was not found, or has been deleted"
    }
  ]
}

Creating a Dynamic Descriptor

Creating a dynamic descriptor involves providing the city, state, descriptor content and the name that is then used in a transaction request.

🚧

Note

The name of a dynamic descriptor is unique.

POST /api/v4/accounts/{accountId}/dynamic-descriptors

{
  "name": "LOC001",
  "city": "Auburn",
  "state": "AL",
  "descriptor": "PayConex V4 Sale 001"
}

*Required Scopes: pcx:dynamic_descriptors:*, pcx:dynamic_descriptors:create

Response

In response, we get the newly created dynamic descriptor entry.

{
  "id": "ddesc_5e60c81479694edb8802bdbc02a062d7",
  "name": "LOC001",
  "city": "Auburn",
  "state": "AL",
  "descriptor": "PayConex V4 Sale 001"
}

Modifying a Dynamic Descriptor

Modifying a dynamic descriptor makes all the parameters of a dynamic descriptor entity optional so you can choose which one you would like to modify.

PATCH /api/v4/accounts/{accountId}/dynamic-descriptors/{resourceId}

📘

Note

• {accountId} value in the path is the PayConex™ account ID number.
• {resourceId} value in the path is the id of a dynamic descriptor to modify.

{ 
  "name": "LOC002",
  "city": "Auburn",
  "state": "AL",
  "descriptor": "PayConex V4 Sale 001"
}

*Required Scopes: pcx:dynamic_descriptors:*, pcx:dynamic_descriptors:update

Getting Dynamic Descriptors

To receive a list of all active dynamic descriptors within your PayConex™ account, you can use a GET request with optional query parameters if needed.

GET /api/v4/accounts/{accountId}/dynamic-descriptors

*Required Scopes: pcx:dynamic_descriptors:*, pcx:dynamic_descriptors:read

Response

[
  {
    "id": "ddesc_5e60c81479694edb8802bdbc02a062d7",
    "name": "LOC001",
    "city": "Auburn",
    "state": "AL",
    "descriptor": "PayConex V4 Sale 001"
  },
  {
    "id": "ddesc_de9182bf5eab4e12ad8d9f6faaaf57ca",
    "name": "LOC002",
    "city": "Kansas City",
    "state": "MO",
    "descriptor": "PayConex V4 Store 001"
  }
]

Query Parameters

Getting a Dynamic Descriptor

This endpoint is used to get a single active dynamic descriptor by its identifier to retrieve the data. It also comes in handy if we are looking at a dynamic descriptor from the transaction metadata but we don't know its name and have the identifier.

📘

Note

• {accountId} value in the path is the PayConex™ account ID number.
• {resourceId} value in the path is the id of a dynamic descriptor to get.

GET /api/v4/accounts/{accountId}/dynamic-descriptors/{resourceId}

*Required Scopes: pcx:dynamic_descriptors:*, pcx:dynamic_descriptors:read

{
  "id": "ddesc_5e60c81479694edb8802bdbc02a062d7",
  "name": "LOC001",
  "city": "Auburn",
  "state": "AL",
  "descriptor": "PayConex V4 Sale 001"
}

Deleting a Dynamic Descriptor

This endpoint handles deleting an active dynamic descriptor.

📘

Note

• {accountId} value in the path is the PayConex™ account ID number.
• {resourceId} value in the path is the id of a dynamic descriptor to delete.

DELETE /api/v4/accounts/{accountId}/dynamic-descriptors/{resourceId}

*Required Scopes: pcx:dynamic_descriptors:*, pcx:dynamic_descriptors:delete