Implementing Reverse Proxy
The Reverse Proxy product enables clients with their own card data APIs to route sensitive payment data through Firstoken's infrastructure without changing their existing API surface. Card data is intercepted, tokenized, and returned transparently — clients' systems and their end users interact only with the client's own domain.
This product combines three Firstoken components:
Inbound Route (Domain type) — receives inbound requests on the client's domain
Proxy — defines the upstream destination where Firstoken forwards the processed request
Custom Domain configuration — handled by Firstoken upon request
Setup requires contacting Firstoken. Custom domain registration and SSL certificate provisioning are performed by the Firstoken team. Clients cannot complete this setup independently through the Console.
How It Works
The client points their domain to Firstoken's infrastructure via a CNAME record. Firstoken provisions an SSL certificate and registers the domain. From that point, requests to the client's API pass through Firstoken's reverse proxy: card data is tokenized in transit, and the tokenized request is forwarded to the client's configured proxy destination.
Setup Process
Step 1 — Create a Proxy
In the Firstoken Console, create a Proxy that defines the upstream destination where Firstoken will forward the tokenized request.
See Create a Proxy for field descriptions and steps.
The proxy destination must be a different endpoint from the inbound route path. Configuring the same host and path for both creates an infinite routing loop.
Step 2 — Create a Domain Inbound Route
In the Firstoken Console, create an Inbound Route, assign the Proxy created in Step 1, and enable the Custom Hostname toggle to configure it as a Domain Inbound Route.
See Create an Inbound Route for field descriptions and steps.
Step 3 — Contact Firstoken
Send the following information to the Firstoken team:
Custom domain
Full domain name to be registered (e.g. api.client.com)
Account ID
Your Firstoken Account ID
Inbound Route ID
UUID of the Domain Inbound Route created in Step 2
Request body schema
Field structure for each path configuration that handles card data
Firstoken will generate the SSL certificate and share the CNAME records you need to configure in your DNS provider.
Step 4 — Configure your DNS
Once you receive the CNAME records from Firstoken, create both records in your DNS provider:
Domain redirect
Points your domain to the Firstoken Route URL provided.
Certificate validation
Host and value provided by Firstoken. Required to validate the SSL certificate.
Both CNAME records must be created within 48 hours of receiving them from Firstoken. After that period the SSL certificate provisioning expires and the process must be restarted.
Once both records are created, notify the Firstoken team. Firstoken will validate the DNS configuration and complete the setup to allow requests from your domain to reach the reverse proxy. DNS propagation may take up to 48 hours depending on your provider and TTL settings.
Body Mapping and Field Filtering
Body Mapping
Each Inbound Route is configured with a field mapping that identifies which fields in the request body contain card data. This mapping is set in the Console when creating the Inbound Route.
See Create an Inbound Route for the list of supported mapping fields (e.g. cardnumber).
Field-Level Filtering
Configuring a filter that routes requests based on the value of a specific field — for example, routing only requests where type: Card and skipping type: PSE — requires intervention by the Firstoken team and cannot be configured through the Console.
To request this configuration, contact Firstoken with:
The Inbound Route ID (
Domaintype) already createdThe specific path (route) to be filtered
The field name and the value to filter on
Any subsequent changes to field-level filtering on an existing route must also be requested through Firstoken support.
Configuring Multiple Endpoints
If your API has multiple endpoints that handle card data, add a separate path configuration for each one within the same Domain Inbound Route using + Add a configuration. Each path configuration defines its own field mapping independently, but all configurations share the same Proxy destination.
Example:
/checkout/pay
https://internal.client.com/upstream
/vault/store
https://internal.client.com/upstream
The path defined in each configuration and the destination path in the associated Proxy must always differ. Configuring the same host and path for both causes an infinite routing loop.
Validating the Integration
Once Firstoken confirms the setup is complete and DNS has propagated, validate the integration end to end:
Send a test request to your domain with card data in the body.
Confirm the request reaches your proxy destination.
Confirm the card fields in the forwarded request contain token values, not the original card data.
Confirm the response is returned correctly to the original caller.
If the request is not reaching the proxy destination or card data is not being tokenized, contact Firstoken support with the Inbound Route ID and a description of the observed behavior.
Reference
Information Required by Firstoken
Custom domain
Full domain name (e.g. api.client.com)
Account ID
Your Firstoken Account ID
Inbound Route ID
UUID of the inbound route
Request body schema
Field structure for each endpoint handling card data
Filter field (if applicable)
Field name, path, and value for field-level filtering
Related Pages
Last updated