Managing Connections

Proxy connections can be created and managed via our Portal or our API. We recommend using our Portal, which allows you to configure them step by step and test them before creating them. However, our API may be more efficient if you want to create many connections at once and if you have prepared a JSON object for your connections.

Step 1: Create a new connection

Navigate to Merchant configurations > Proxy connections in your Portal and click on + Create connection. This option is only available to Admin users at the Organization level.

Choose a unique, simple but descriptive name for your connection and a description if needed. You can update the name and description at any time later.

📘

This step is equivalent to the API endpoint here if you wish to use API to create a connection.

Similarly, the API endpoint to update a connection details can be found here.

Most importantly, in this step, you must define the connection type.

How to choose the connection type

Is it an external system that initiates the connection? Then your connection is Inbound. An inbound connection can be configured for both when the external system sends sensitive data in the request to your system, or it requests to get sensitive data in the response from your system.

Is it your system that initiates the connection? Then your connection is Outbound. An outbound connection can be configured for both when you want to send sensitive data to an external system, or to request to get sensitive data in the response from an external system.

Step 2: Create the first version of the connection

Once you create the connection, you will configure the first version of the connection. Connections has versioning so that you can create immutable versions, which allows you to make changes always on new versions without risking your version on live. When you're creating a new version of an existing connection, select + New version to start with an empty configuration or select Edit as new version to duplicate an existing version to make your changes on. You can create as many versions as you want, but only one can be used on live at a time, which we call the Live version.

Regardless is inbound or outbound, any connection will have a URL to invoke this connection, and a URL to which the proxied message should be transmitted after.

📘

This step is equivalent to the API endpoint here in our API reference.

Configuring Inbound Connections

In an inbound connection, the 'Public URL' is an address that an external system can call to invoke this connection. This must be a unique URL that will be generated by Payrails or a custom URL that is defined by the merchant.

Next, you will provide the 'Proxy URL' to which Payrails should send the proxied message.

Configuring Outbound Connections

In an outbound connection, you will use the API endpoint by specifying the connection to invoke a given connection. When you invoke this connection, you will specify in the request headers to which destination the request should be sent, and our system will check the trusted URL list that you configure in the connection.

Configure proxy rules for all types of connections

When sending a card to an external system or receiving from an external system, you must help us find the sensitive data you intend to extract or reveal from the HTTP request, how you want to replace it in your server, and how you want us to store it in our Vault.

For each rule, you configure where in the HTTP message the proxy should target, the operation (tokenize or detokenize) to be made, the type of record to be targeted in the HTTP message, and the path of the fields to be targeted during proxy.

Operation target

Is the sensitive information in the Request body or Response body of the interaction with the external system, or both? You can create separate rules if you have sensitive information in the HTTP call's request and response bodies.

Operation type

• Tokenize: If you want us to extract sensitive information, tokenize it in our Vault, and replace it with an alias when we forward the request to you.
• Detokenize: If you want us to reveal sensitive information currently stored in our Vault to the external system.

Record type and selector

In case if payload contains multiple records at once, you should specify the record selector.

You must indicate precisely where the Record is in the request or response body. The selector field follows the JSONPath format if the body is JSON and XPath format if it is XML.

For more information about Records and Fields, check here.

📘

Currently, we support only Card or Network token as record types, and JSON and XML as content types. You can request new ones to our team if needed.

Field type and selector

Depending on the record type you selected above, you will be asked to define details on each Field that composes the record.

Each field has:

• a selector that tells us where to find the field inside the HTTP message.
• the regex for parsing it if necessary. In most cases, the data that you want to tokenize or detokenize is returned by the selector, for example 1129. In some cases, your payload may contain multiple fields like 1129 or 11/29. In such cases selector will return data like 1129, and you need to specify which part of it is the month and which one is the year.
  • If data does not require any special parsing, you should leave regex empty: in this case whole content of the element or attribute returned by selector will be used as value.
  • An example of input format 11/29, if you want to extract the month, you can use a regex that matches to month, for example /^\d2(?=/)/
  • You can go to the next section to learn more about how to parse fields with Regex (regular expressions).

Additionally, in the case that the proxy rule is configured for the operation type of 'tokenize':

• an alias format that indicates how to store it in our Vault. Typically, a random UUID. In case that you need a particular format, contact our support team so that we can enable it for you.
• a display format to choose how we display the tokenized data in a non-sensitive way, e.g., the last four digits of a card number, or the original value of an expiry date. Displayable formats are defined according to the PCI DSS standards and shown in the Portal for each field.
• a replacement format that allows choosing whether the tokenized value should be replaced with the alias or with the displayable value inside the transformed body received by the merchant. For example, an expiry date can be received either as a UUID alias or as its original value, which is its displayable format.
• a storage policy that indicates how long we should store the value for. Typically, permanent for the card data, except for its security code, which should be volatile to comply with PCI DSS policies.

Parsing Fields with Regex

Regex (regular expressions) allows you to specify a certain part of the fields to be picked for processing a rule inside the connection configuration. The regex gives you the capability to split one single field into multiple inputs.

For example, if the expiry date for a card comes in a single field instead of 2 separate fields, you can use a regex to split the field for tokenization. Let's take an example below:

{
 "record":
    {
		"cardNumber": "4111111111111111",
		"expiryDate": "03/33"
    }
}

If you will receive a request where the expiryDate is passed as above, you should provide a regex in the connection configuration for expiry date fields in the following way:

Notice how the field selector for both fields is the same, but the regex for picking the value is different. In this case, our processing will pick the individual segments defined by the regex for processing and replace them back into their corresponding place in the original string.

The rules for parsing fields using regex are as follows:

• Must be written in Perl notation
• Must have only 1 group in the regex
• Must result in only 1 match in the regex

It is imperative that you ensure that the regex follows the above rules to ensure processing of the fields. Errors in regex can lead to unexpected behaviour.

Behaviour of regex

1. If the regex matches results in more than 1 group or more than 1 match, then we will be unable to pick the correct data from the field. This will result in the nullification of the field, and it will not be used for connection processing.
2. If there are collisions in the regex between fields (i.e., same regex used in 2 different selectors), we will attempt the processing for one of the fields but nullify the other.
3. If the regex is correct for the fields, then it will be used for processing and replaced in its original place. The original place is defined as the segment of the original group that got picked by the regex. The rest of the string is preserved as is.

Recommended tools

Regex101 with the Golang flavour will allow you to test the exact representation that is used by our platform for parsing regex.

Examples:

1. Extracting the month from date
2. Extract the year from date
3. Extract a card from a complex string

Step 3: Review configuration and make live

After defining the connection, we will take you to a Review page, where you can check the provided values before going live. After review, your connection version will be created but will not be live yet.

In order to make a version live, you will have to click on the version you want to make live on the versions page.

📘

In order to get a connection version's details by using API, you can use our API endpointhere.

In order to make a connection live by using API, you should use the API endpoint here presented in our API reference.

Step 4: Manage connections

After creating your connections, you will be able to list, filter, and see all created versions of them in our Portal and via API endpoints.

You can simply select connections to see the details of the connection, the live version, and the inactive versions' details. You can change the live version anytime, or deactivate it. When editing, you can either start with an empty configuration or use an existing version and make changes to it if you don't want to start from scratch.

📘

In order to list & filter connections by using API, you should use our API endpoint here and for listing connection versions of a particular connection, use here in our API reference.