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.

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>

We must create an Inbound Connection that tokenizes the card information and replaces the values with the aliases of each field before sending it to your server.

The request that reaches your server will look like this:

{
  "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>

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.

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.

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>

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.

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

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