Why tokens alone can't pay: the other half of the PCI problem

Tokenizing card data is only half the job. Once your systems store tokens instead of card numbers, you've taken a big step toward reducing your PCI scope. Eventually, though, you'll need to do something with those cards: charge one through your PSP, send a guarantee to a hotel, or pay a supplier with a virtual card.

That's where things get tricky. Your PSP's /payments endpoint expects a real card number, not a token. The simple fix is to detokenize the card in your own backend and put the card number in the request. But that pulls raw card data back into your systems and puts you right back in PCI scope.

What you need is a way to send a request that contains only tokens, while the receiver still gets the real card data.

The Forward Proxy is PCI Proxy's API for exactly this, and its name explains how it works. A proxy is a server that sits between two systems and forwards traffic between them. The Forward Proxy is a proxy for outbound card data. You send your request through it with tokens where the card data would normally go. As it forwards the request, it swaps each token for the real card data, so the receiver gets exactly what its API expects. Your server never holds a card number at any point.

If you've read our Filter Proxy spotlight, this will feel familiar. The Filter Proxy takes card data out of traffic coming in. The Forward Proxy puts it back into traffic going out. Together, they let you collect, store, and use cards without raw card data ever touching your infrastructure.

The use cases

The Forward Proxy is useful whenever a third party needs real card data from you, but you only want to hold tokens. Three areas come up again and again.

Processing payments with any PSP or acquirer

This is the most common case. You store tokens, and when it's time to charge a card, you send a normal authorization request to your PSP, such as Adyen, Stripe, Checkout, through the Forward Proxy. The PSP receives the card number and CVV it expects. Because the tokens live in PCI Proxy's vault rather than with a single PSP, you aren't tied to one provider. You can route payments to different PSPs or acquirers, add a new one, or switch providers entirely, all without asking customers to re-enter their cards. If you're building a payment orchestration layer, this is what makes it portable.

Sharing card details across travel partners

In travel, card details often need to move on to the next business in the chain. A travel agency forwards a guest's card to a hotel or airline to secure a booking. A hotel lets its PSP or booking management platform retrieve card details for reservations it has already stored. With the Forward Proxy, you keep tokens on your side, and the partner receives the card data it needs for that specific booking.

How the Forward Proxy detokenizes card data in transit

Because it's a proxy, the Forward Proxy sees every message that passes through it and looks for PCI Proxy tokens.

When it finds a token, it does three things in a single step:

1. Looks up the original card data in PCI Proxy's secure vault.
2. Replaces the token in the message with the real value.
3. Forwards the message to the receiver.

Everything else in the message stays the same, including headers, structure, authentication, and every non-sensitive field. The receiver sees a normal request, as if you'd sent it directly.

Pull vs. Push: two ways to integrate the Forward Proxy

As with the Filter Proxy, the right integration depends on who starts the call. The detokenization is the same in both cases. The difference is whether the card data goes out in your request or in your response.

Pull: send tokens in your request

In a Pull integration, your system starts the call. A typical example is an online shop sending an authorization request to its PSP. You build the request exactly as the PSP's API expects, with a token in place of the card number and another in place of the CVV. Then you send it through the Forward Proxy, which swaps in the real card data and forwards the request to the PSP. The PSP's response comes back to you through the Forward Proxy as always.

The change on your side is small. You point the request at the Forward Proxy and tell it where to go next. Your request body, your PSP credentials, and your response handling all stay the same.

Push: send tokens in your response

In a Push integration, the receiver starts the call. An example is a booking management platform requesting reservation details, including card data, from a hotel. You give the receiver a unique Forward Proxy endpoint to use instead of your own. The Forward Proxy forwards each request to your original endpoint unchanged. Your API responds as usual, with tokens in place of card data. The Forward Proxy then swaps in the real values before the response reaches the receiver. This time, the change is on the receiver's side, and it's just as small: they call a different URL. Because card data goes out to whoever calls that endpoint, PCI Proxy only accepts requests from receivers it has verified. Their IP addresses are added to an allow list during setup.

What the receiver gets

In both cases, the receiver gets a message that looks as if it came directly from you, with real card data in it. A token such as AABcH0Bq92s3kgAESIAAbGj5NIsAHWC in your payload arrives as 4111 1111 1111 1111, and the CVV token arrives as the real CVV. Amounts, references, and every other field arrive unchanged. On your side, nothing ever held the card number.

For request formats, headers, and code examples, see the Pull and Push guides in the API documentation, or start with the Forward Proxy overview.