To allow merchants to add their own information to transactions, use the custom fields feature of our API. For example, your merchants can use custom fields to add a credit agreement ID, a magazine subscription name, or an internal customer ID. You can also use the custom fields feature to create dynamic descriptors. A dynamic descriptor is text that appears on the customer's statement with the transaction. For more information about dynamic descriptors, go to Dynamic Descriptors. The following resources on our API support the custom fields feature:

Card payments and refunds
Bank transfer payments and refunds
Subscriptions
Secure tokens

Integration steps

Step 1. Contact us to activate custom fields.
Step 2. Create the custom field on the merchant's Self Care Portal.
Step 3. (Optional) Set the custom field as a dynamic descriptor.
Step 4. Add the custom field to your integration.

Before you begin

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

Include your API key in the x-api-key parameter in the header of a POST request.
Send your request to https://identity.payroc.com/authorize.

You need to generate a new Bearer token before the previous Bearer token expires.

Example request

curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

Headers

To create the header of each POST request, you must include the following parameters:

Content-Type: Include application/json as the value for this parameter.
Authorization: Include your Bearer token in this parameter.
Idempotency-Key: Include a UUID v4 to make the request idempotent.

curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"
-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Note: If your request is successful but there is an issue with the custom field, we don’t store the custom field and don’t return it in the response.

Step 1. Contact us to activate custom fields

Before you can use custom fields, contact our Integrations Team to activate the custom fields feature on your account. To contact our Integrations Team, send an email to [email protected].

Step 2. Create the custom field on the Self Care Portal

Log in to the Self Care Portal or the UAT version of the Self Care Portal.
From the side menu, select Settings > Custom Fields > NEW CUSTOM FIELD.
Enter the following information about the custom field:
- Name – The name of the custom field.
- Type – The data type that the Self Care Portal displays for the custom field.
- Display order – The position of the custom field on the Self Care Portal. For example, if you set the value for the display order to 3, the custom field appears third in the list of custom fields.
- Label – The label for the custom field in the Self Care Portal.
- Language – The language for the label.
(Optional) If you want to use custom fields with payment plans and subscriptions, select Enable Subscription.
(Optional) Select the other payment features that you want to use custom fields with.
Select SAVE.

Step 3. (Optional) Set the custom field as a dynamic descriptor

To set the custom field as a dynamic descriptor, turn on dynamic descriptors for the processing terminal, and then select which custom field you want to use as the dynamic descriptor.

Enable dynamic descriptors

In the Self Care Portal, select Merchants, and then select the merchant that you want to edit.
Select Processing Terminal, and then select the terminal that you want to edit.
Select Features.
Select Allow Dynamic Descriptor.
Enter the following information for the dynamic descriptor:
- Dynamic Descriptor Prefix – The prefix that appears at the start of the description. For example, Order #.
- Dynamic Descriptor Default Value – The default description for the dynamic descriptor if the merchant doesn't provide a value.
Select SAVE.

Select the custom field to use as the dynamic descriptor

From the Custom Fields screen, select the Settings tab, and then select Dynamic Descriptors.
From the Other drop-down menu, select the custom field that you want to use as the dynamic descriptor.

Note: If you want to add the custom field as a dynamic descriptor for other features, select the custom field from the following drop-down menus:

Virtual Terminal
Hosted Payment Page
Bulk Payments

Step 4. Add the custom field object to your API requests

You can use custom fields with the following POST requests: Bank transfer payments

Create payment

Bank transfer refunds

Create refund

Payments

Create payment

Refunds

Create refund

Secure tokens

Create secure token

Subscriptions

Note: Before you can use a custom field with a subscription, you need to add the custom field to the payment plan. For more information about using custom fields with payment plans and subscriptions, go to Payment plans and subscriptions.

To add custom fields to your integration, include the customFields object in the body of your requests.

"customFields": [
  {
    "name": "EXAMPLE",
    "value": "1"
  }
]

Parameter	Description
name	The name of the custom field. This must match the name you provided in the Self Care Portal and is case-sensitive.
value	The string value for the custom field.

If your request is successful, we store the custom field and return it in the response.

Important: If there is a problem with the custom field, we still process the request but we don't return the custom field in the response. For example, if the name of the custom field doesn't match the name you provided in the Self Care Portal, we don't return the custom field in the response.

Update the value of a custom field

To update a custom field, send a PATCH request to the relevant endpoint. Structure your request to follow the RFC 6902 standard.

Note: If you update a custom field that is also a dynamic descriptor, the new value doesn’t appear on the customer’s statement.

Payment plans and subscriptions

When you create a payment plan you need to indicate which custom fields are available for subscriptions that are linked to the payment plan. To indicate which custom fields are available for subscriptions, add the name of the custom field in a customFieldNames array to the Create payment plan request.

  "customFieldNames": [
"yourCustomField"
]