Take payments

Add custom fields to your integration

View as Markdown

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

Authenticate your requests before making API calls. If your request fails, 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

  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.

Note: If you want to add the custom field as a dynamic descriptor for other features, select the custom field from the Virtual Terminal, Hosted Payment Page, or Bulk Payments drop-down menus.

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

You can use custom fields with the following POST requests:

Bank transfer payments

Bank transfer refunds

Payments

Refunds

Secure tokens

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.

1"customFields": [
2  {
3    "name": "EXAMPLE",
4    "value": "1"
5  }
6]
ParameterDescription
nameThe name of the custom field. This must match the name you provided in the Self Care Portal and is case-sensitive.
valueThe 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.

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

Important: The name of the custom field must match the name you provided in the Self Care Portal.