Introduction to Connections

In online businesses, various processes require collecting and handling users' sensitive data. While the most common case is gathering customers' card information on a checkout page, some flows involve sharing data between software systems via HTTP-based APIs. Regardless of the method, dealing with sensitive information comes with critical compliance and security challenges—this is where Payrails Vault helps merchants with proxy connections.

A Connection represents a secure route between the merchant, an upstream or downstream third party, and Payrails. It configures the data transfer to be safe and compliant throughout the flow by ensuring sensitive data will never reach the merchant's system.

A connection can be created to receive an inbound request initiated from a third party to the merchant's system or to send an outbound request to a third party initiated by the merchant's system. It is possible to configure a connection to tokenize or detokenize sensitive data both in a request or a response of an HTTP communication, enabling various use cases for merchants operating in travel, hospitality, marketplace, e-commerce industries, and many more.

Let's have a look at how inbound and outbound connections are used and how they are configured.

Inbound Connections

An Inbound Connection is used when a third party initiates a data transfer flow to the merchant. Typical use cases are:

1. Tokenize data received in an inbound connection:

You can configure a connection in order for a third party to initiate an HTTP request to send sensitive data to your merchant URL. Since sensitive data is received in the request to the merchant, Payrails works as a proxy before the merchant, tokenizes sensitive records, and forwards the request with aliases substituting the sensitive data with non-sensitive values. In the next sections, you will read how to manage those configure according to your specific tokenization flows.

✈️

A typical example use case for this flow is merchants in travel industry receiving reservations and payment data from OTAs (online travel agencies).

2. Detokenize data in the response to an inbound connection:

You can configure a connection for a third party to initiate an HTTP request, where in the response, they ask to receive sensitive data from the merchant. For this case, Payrails will replace the aliases that the merchants aims to send to the third party in the response, with the actual values.

Please note that the destination must comply with PCI DSS in this case. Payrails will need their Attestation of Compliance (AOC) to approve the connection before it goes live.

Outbound Connections

An Outbound Connection is used when your system (the merchant) initiates a data transfer flow to a third party. Typical use cases are:

1. Detokenize data requested in an outbound connection:

You can configure a connection in which the merchant initiates an HTTP request to send sensitive data to a third party. The merchant sends the request that has to be forwarded to the destination with aliases to Payrails, who then substitutes aliases with the actual data and forwards the request to the destination URL.

Please note that the destination must comply with PCI DSS in this case. Payrails will need their Attestation of Compliance (AOC) to approve the connection before it goes live.

💳

A typical example use case for this flow is merchants sending a payment authorization request to a PSP (payment service provider).

2. Tokenize data received in an outbound connection:

You can configure a connection in which the merchant initiates an HTTP request to receive sensitive data from a third party. The merchant, via Payrails Proxy, makes a request in which sensitive data will be included in the response. Payrails will substitute the sensitive data with token aliases before forwarding the response to the merchant. The aliases created via the proxy connection can be chosen to be stored in the vault to be used later for detokenization in different flows/connections. In the next sections, you will read how to manage those configure according to your specific tokenization flows.

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 has a proxy URL to invoke this connection, and a destination URL to which the proxied message should be transmitted.

📘

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

Configuring Inbound Connections

In an inbound connection, the Proxy URL is a public URL 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 destination URL to which Payrails should send the proxied message.

Configuring Outbound Connections

In an outbound connection, you will be provided the proxy URL to invoke this connection, and configure the trusted URL(s) to which you want Payrails to send the proxied message. When you invoke this connection, you can specify in the request headers to which destination each request should be sent to, and our system will check the trusted URL list.

The configuration for each record and field is similar to the one described above for inbound connections, except that this time, you're selecting the places in the request or response where you want us to replace the values for the actual ones stored in our Vault.

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 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(?=/)/

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

• a display format to choose how we display sensitive data in a non-sensitive way, e.g., the last four digits of a card number.
• an alias format that indicates how to store it in our Vault. Typically, a random UUID.
• a storage policy that indicates for how long we should store the value. Typically, permanent for the card data, except for its security code, which should be volatile to comply with PCI DSS policies.

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.