> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Invoking Connections

> Learn how to invoke inbound and outbound connections that are created in the previous step.

## 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:

```json JSON theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "age": 26,
  "card": {
    "number": "4111111111111111",
    "expireDate": "08/38",
    "holderName": "John Doe",
    "cvv": "007"
  }
}
```

```xml theme={null}
<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:

```json theme={null}
{
  "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"
  }
}
```

```xml theme={null}
<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](/reference/getrecordbyalias). 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**.

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.

If your response to us looks like this:

```json theme={null}
{
  "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"
  }
}
```

```xml theme={null}
<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>
```

```Text XML with attributes theme={null}
<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.

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

```xml theme={null}
<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>
```

```Text XML with attributes theme={null}
<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](/reference/outboundconnectioninvocation#/) by providing:

* The `connectionId` as a path parameter,
* The [bearer token](/reference/getoauthtoken#/) of Payrails under `Payrails-Authorization` request header,
* The destination URL that should receive the transformed body after proxying under`Payrails-Destination` request header.

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

<Note>
  Note that any query parameters that you want to send to destination URL should be included in Payrails-Destination header, for example `Payrails-Destination: https://thirdparty.com/path?param1=value1`.
</Note>

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

```json theme={null}
{
  "from": "2025-04-20",
  "to": "2025-05-20",
  "user": "john@doe.com",
  "vehicle": {
    "brand": "Fiat",
    "model": "Uno"
  },
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "10",
    "expiryYear": "26",
    "securityCode": "666"
  }
}
```

```xml theme={null}
<reservation>
    <from>2025-04-20</from>
    <to>2025-05-20</to>
    <user>john@doe.com</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:

```json theme={null}
{
  "from": "2025-04-20",
  "to": "2025-05-20",
  "user": "john@doe.com",
  "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"
  }
}
```

```xml theme={null}
<reservation>
    <from>2025-04-20</from>
    <to>2025-05-20</to>
    <user>john@doe.com</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>
```

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](/reference/getrecordbyalias). 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 response body.

## 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](/reference/outboundconnectioninvocation#/) by providing:

* The `connectionId` as a path parameter,
* The [bearer token](/reference/getoauthtoken#/) of Payrails under`Payrails-Authorization` request header,
* The destination URL that should receive the transformed body after proxying under`Payrails-Destination` request header.

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:

```json theme={null}
{
  "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"
  }
}
```

```xml theme={null}
<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:

```json theme={null}
{
  "amount": "10.00",
  "currency": "EUR",
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "29",
    "securityCode": "858"
  }
}
```

```xml theme={null}
<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:

```json theme={null}
{
   "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"
         }
      }
   ]
}
```

```xml theme={null}
<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.

## Inbound connections URL notes

Please note that paths `/ping` and `/sping` are reserved for internal purposes.


## Related topics

- [List connection versions for connection](/reference/listconnectionversions.md)
- [Managing Connections](/docs/token-vault/vault-proxy/proxy-connections/managing-connections.md)
- [Create a connection](/reference/createvaultconnections.md)