Inbound Connection with Tokenization

Imagine an external system that wants to send you users and their card information. You want to store those cards in our Vault so that you can later use them to process payments.

In this case, you must create an Inbound Connection that tokenizes the card information and replaces the values with the aliases of each field in the request before sending it to your server.

While you configure this inbound connection from the Portal or via API, you will be provided a public URL that any third party can use to make an API call for this connection. The public URL will be the address that this inbound connection will be invoked by. It will be generated by Payrails with a default value, but it can be customized by you during connection configuration. You can find this value under Connection Version > Connection Details > Public URL in the Proxy Connections menu in our Portal.

Their request body for each user looks like this:

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 26,
  "card": {
    "number": "4111111111111111",
    "expireDate": "08/38",
    "holderName": "John Doe",
    "cvv": "007"
  }
}

<order>
    <firstName>John</firstName>
    <lastName>Doe</lastName>
    <age>26</age>
    <card>
        <number>4111111111111111</number>
        <expireDate>08/38</expireDate>
        <holderName>John Doe</holderName>
        <cvv>007</cvv>
    </card>
</order>

The request body that reaches your server will look like below:

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 26,
  "card": {
    "number": "3b8b6037-0019-4a43-87a0-c578bd813542",
    "expireDate": "dc51b23c-3180-40be-9054-a6bf18e1f5d9/abf559e5-81ca-418f-a198-60e03a8a9969",
    "holderName": "John Doe",
    "cvv": "31a91b8a-f48b-4f23-9284-1225fbd17621"
  }
}

<order>
    <firstName>John</firstName>
    <lastName>Doe</lastName>
    <age>26</age>
    <card>
        <number>3b8b6037-0019-4a43-87a0-c578bd813542</number>
        <expireDate>dc51b23c-3180-40be-9054-a6bf18e1f5d9/abf559e5-81ca-418f-a198-60e03a8a9969</expireDate>
        <holderName>John Doe</holderName>
        <cvv>31a91b8a-f48b-4f23-9284-1225fbd17621</cvv>
    </card>
</order>

If you would like to also receive the displayable values of aliases, you can either receive them in the headers or you can make an API call to get details of the aliases. As an example, the displayable value of an alias of a card number will be the last 4 digits of the card.

Note that fields that are not considered sensitive data by PCI DSS can also be configured in the connection to be tokenized without any alias replacement. In that case, you can choose to get the displayable values directly in the request body.

To achieve that, the connection must have the following selectors in the filtering configuration:

$.card.number to find the card number.
$.card.expireDate to find the expiration date, which will then be split into month and year.
$.card.holderName to find the cardholder name, which we don't need to hide in the request to your server.
$.card.cvv to find the card security code, which will be stored as volatile.

When you reply to that request, we will forward your response to the external system precisely as it comes, assuming that your response will not contain any sensitive information, depending on the way the connection is configured.

After the tokenization operation is applied, we will forward the transformed response to your Proxy URL. It is the URL of the merchant to which Payrails delivers the transformed HTTP message after applying the proxy rules. You will configure this value inside the connection under Connection Version > Connection Details > Proxy URL in the Proxy Connections menu in our Portal.

Inbound Connection with Detokenization

Imagine an external system asking you for card information about reservations made in your system. When we forward their request to your server, you must build the response using the aliases of the fields you want to include. We will replace them with the actual values in the response to the external system.

In this case, you will create an Inbound Connection that detokenizes the data behind each alias you include in the response.

If your response to us looks like this:

{
  "reservationStart": "2025-04-20",
  "reservationEnd": "2025-05-20",
  "guests": 2,
  "card": {
    "number": "3b8b6037-0019-4a43-87a0-c578bd813542",
    "expiryMonth": "dc51b23c-3180-40be-9054-a6bf18e1f5d9",
    "expiryYear": "63955d80-6a72-4a91-9f1c-21785adc3870",
    "securityCode": "31a91b8a-f48b-4f23-9284-1225fbd17621"
  }
}

<reservation>
    <reservationStart>2025-04-20</reservationStart>
    <reservationEnd>2025-05-20</reservationEnd>
    <guests>2</guests>
    <card>
        <number>3b8b6037-0019-4a43-87a0-c578bd813542</number>
        <expiryMonth>dc51b23c-3180-40be-9054-a6bf18e1f5d9</expiryMonth>
        <expiryYear>63955d80-6a72-4a91-9f1c-21785adc3870</expiryYear>
        <securityCode>31a91b8a-f48b-4f23-9284-1225fbd17621</securityCode>
    </card>
</reservation>

<reservation>
    <reservationStart>2025-04-20</reservationStart>
    <reservationEnd>2025-05-20</reservationEnd>
    <guests>2</guests>
    <card 
        number="3b8b6037-0019-4a43-87a0-c578bd813542" 
        expiryMonth="dc51b23c-3180-40be-9054-a6bf18e1f5d9" 
        expiryYear="63955d80-6a72-4a91-9f1c-21785adc3870" 
        securityCode="31a91b8a-f48b-4f23-9284-1225fbd17621" 
    />
</reservation>

We will find those aliases in our Vault, replace them in the places you selected in the configuration, and then send the following response to the external system.

{
  "reservationStart": "2025-04-20",
  "reservationEnd": "2025-05-20",
  "guests": 2,
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "27",
    "securityCode": "555"
  }
}

<reservation>
    <reservationStart>2025-04-20</reservationStart>
    <reservationEnd>2025-05-20</reservationEnd>
    <guests>2</guests>
    <card>
        <number>4111111111111111</number>
        <expiryMonth>12</expiryMonth>
        <expiryYear>27</expiryYear>
        <securityCode>555</securityCode>
    </card>
</reservation>

<reservation>
    <reservationStart>2025-04-20</reservationStart>
    <reservationEnd>2025-05-20</reservationEnd>
    <guests>2</guests>
    <card 
        number="4111111111111111" 
        expiryMonth="12" 
        expiryYear="27" 
        securityCode="555" 
    />
</reservation>

After the detokenization operation is applied, we will forward the transformed response back.

Outbound Connection with Tokenization

Imagine you are a car rental management system that wants to retrieve reservations made in an external system, including card information. You would make this call using Payrails as a proxy so that when they reply, we can filter the card information into our Vault and give you the original response with the replaced fields for aliases.

In this case, you must create an Outbound Connection that tokenizes the card information in the external system's response.

For invoking an outbound connection, you will use this API by providing:

The connectionId as a path parameter,
The bearer token of Payrails underPayrails-Authorization request header,
The destination URL that should receive the transformed body after proxying.

Every other header that you will send will be passed to the upstream party as it is.

As an example, if the external system's response looks like this:

{
  "from": "2025-04-20",
  "to": "2025-05-20",
  "user": "[email protected]",
  "vehicle": {
    "brand": "Fiat",
    "model": "Uno"
  },
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "10",
    "expiryYear": "26",
    "securityCode": "666"
  }
}

<reservation>
    <from>2025-04-20</from>
    <to>2025-05-20</to>
    <user>[email protected]</user>
    <vehicle>
        <brand>Fiat</brand>
        <model>Uno</model>
    </vehicle>
    <card>
        <number>4111111111111111</number>
        <expiryMonth>10</expiryMonth>
        <expiryYear>26</expiryYear>
        <securityCode>666</securityCode>
    </card>
</reservation>

We will take the card information from their response according to the configured connection, tokenize it in our Vault, and give you the corresponding aliases in the original response.

The response we give to you will look like:

{
  "from": "2025-04-20",
  "to": "2025-05-20",
  "user": "[email protected]",
  "vehicle": {
    "brand": "Fiat",
    "model": "Uno"
  },
  "card": {
    "number": "e3f02f5b-8c50-4221-b2c2-dfa94e7e4367",
    "expiryMonth": "56f2e398-a16b-4b56-b8ee-0087c39aa2d6",
    "expiryYear": "15d96fa4-3059-4548-a521-0bf8f105bf88",
    "securityCode": "a0258d98-b578-484c-8324-8bc7dfcfea5e"
  }
}

<reservation>
    <from>2025-04-20</from>
    <to>2025-05-20</to>
    <user>[email protected]</user>
    <vehicle>
        <brand>Fiat</brand>
        <model>Uno</model>
    </vehicle>
    <card>
        <number>e3f02f5b-8c50-4221-b2c2-dfa94e7e4367</number>
        <expiryMonth>56f2e398-a16b-4b56-b8ee-0087c39aa2d6</expiryMonth>
        <expiryYear>15d96fa4-3059-4548-a521-0bf8f105bf88</expiryYear>
        <securityCode>a0258d98-b578-484c-8324-8bc7dfcfea5e</securityCode>
    </card>
</reservation>

Outbound Connection with Detokenization

Imagine you want to use a card stored in our Vault to process a payment on a payment provider using your custom implementation without the intervention of Payrails' Payment Processing module.

You will need an Outbound Connection that detokenizes the stored card into a request to the payment provider.

For invoking an outbound connection, you will use this API by providing:

The connectionId as a path parameter,
The bearer token of Payrails underPayrails-Authorization request header,
The destination URL that should receive the transformed body after proxying.

Every other header that you will send will be passed to the upstream party as it is.

As an example, your request to us will look like this:

{
  "amount": "10.00",
  "currency": "EUR",
  "card": {
    "number": "dc7582c5-39f5-4922-b75c-5fef2caf4116",
    "expiryMonth": "883f1546-af2d-4a40-a823-1ed400d484ff",
    "expiryYear": "8ceaea24-c8ec-41b4-91aa-db427139fff3",
    "securityCode": "f12ad138-8bc0-4fa6-b06e-781c371dec6e"
  }
}

<payment>
    <amount>10.00</amount>
    <currency>EUR</currency>
    <card>
        <number>dc7582c5-39f5-4922-b75c-5fef2caf4116</number>
        <expiryMonth>883f1546-af2d-4a40-a823-1ed400d484ff</expiryMonth>
        <expiryYear>8ceaea24-c8ec-41b4-91aa-db427139fff3</expiryYear>
        <securityCode>f12ad138-8bc0-4fa6-b06e-781c371dec6e</securityCode>
    </card>
</payment>

We will replace the aliases for the actual values stored in our Vault, and forward the request to the payment provider like this:

{
  "amount": "10.00",
  "currency": "EUR",
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "29",
    "securityCode": "858"
  }
}

<payment>
    <amount>10.00</amount>
    <currency>EUR</currency>
    <card>
        <number>4111111111111111</number>
        <expiryMonth>03</expiryMonth>
        <expiryYear>29</expiryYear>
        <securityCode>858</securityCode>
    </card>
</payment>

Payload with multiple records

In case if you have a payload that contains many records, for example:

{
   "orders":[
      {
         "firstName":"John",
         "lastName":"Doe",
         "age":26,
         "card":{
            "number":"4111111111111111",
            "expireDate":"08/38",
            "holderName":"John Doe",
            "cvv":"007"
         }
      },
      {
         "firstName":"Alice",
         "lastName":"Smith",
         "age":34,
         "card":{
            "number":"5500000000000004",
            "expireDate":"12/27",
            "holderName":"Alice Smith",
            "cvv":"123"
         }
      },
      {
         "firstName":"Carlos",
         "lastName":"Martinez",
         "age":42,
         "card":{
            "number":"340000000000009",
            "expireDate":"05/30",
            "holderName":"Carlos Martinez",
            "cvv":"456"
         }
      }
   ]
}

<orders>
    <order firstName="John" lastName="Doe" age="26">
        <card 
            number="4111111111111111" 
            expireDate="08/38" 
            holderName="John Doe" 
            cvv="007" 
        />
    </order>
    <order firstName="Alice" lastName="Smith" age="34">
        <card 
            number="5500000000000004" 
            expireDate="12/27" 
            holderName="Alice Smith" 
            cvv="123" 
        />
    </order>
    <order firstName="Carlos" lastName="Martinez" age="42">
        <card 
            number="340000000000009" 
            expireDate="05/30" 
            holderName="Carlos Martinez" 
            cvv="456" 
        />
    </order>
</orders>

In this case you should set record selector (selector which selects elements which contain individual records) and then each element returned by this selector will be processed. On example above record selector should be set to $.orders (or /orders/order). Each element returned by this selector will be then handled individually and rule, in this case tokenization, will be applied.