Add custom fields to your integration

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:

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

Example request

1
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.

1
{
2
  "access_token": "eyJhbGc....adQssw5c",
3
  "expires_in": 3600,
4
  "scope": "service_a service_b",
5
  "token_type": "Bearer"
6
}

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.

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

1. Log in to the Self Care Portal or the UAT version of the Self Care Portal.
2. From the side menu, select Settings > Custom Fields > NEW CUSTOM FIELD.
3. 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.
4. (Optional) If you want to use custom fields with payment plans and subscriptions, select Enable Subscription.
5. (Optional) Select the other payment features that you want to use custom fields with.
6. 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

1. In the Self Care Portal, select Merchants, and then select the merchant that you want to edit.
2. Select Processing Terminal, and then select the terminal that you want to edit.
3. Select Features.
4. Select Allow Dynamic Descriptor.
5. 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.
6. Select SAVE.

Select the custom field to use as the dynamic descriptor

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

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

• Create subscription
• Pay manual subscription

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

1
"customFields": [
2
  {
3
    "name": "EXAMPLE",
4
    "value": "1"
5
  }
6
]

If your request is successful, we store the custom field and return it 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.

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.

1
"customFieldNames": [
2
  "yourCustomField"
3
  ]