# Authorize a Card using TaaS > The `POST /v1/tokenizer/proxy` endpoint allows enterprise merchants to **securely authorize transactions with their preferred payment processors (PSPs)** by proxying requests through Bolt's PCI-compliant infrastructure. This API is part of Bolt's Tokenization-as-a-Service (TaaS) platform, enabling merchants to inject sensitive card data (e.g., PAN, CVV) into PSP-native request formats without directly handling raw card data. The proxy replaces placeholders in the merchant-defined request body with actual card data retrieved securely using the provided `x-bolt-taas-id`, and forwards the complete request to the specified `x-bolt-forward-to` URL using the HTTP method specified in `x-bolt-forward-verb`. Source: https://help.boltapp.com/api-reference/embeddable-checkout-v1/transactions/proxytransaction `POST /v1/tokenizer/proxy` ## OpenAPI definition This endpoint as it appears in the OpenAPI document, with every schema it references included. ```json { "openapi": "3.2.0", "info": { "version": "1.0.1", "title": "Embedded API Reference", "description": "Postman Collection:\n\n[![](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\nThe Embedded API reference is a consolidation of critical APIs that a developer will use when integrating with Bolt's Embedded Accounts product suite.\n" }, "servers": [ { "url": "https://api.boltapp.com", "description": "The Production URL (Live Data)." }, { "url": "https://api-sandbox.boltapp.com", "description": "The Sandbox URL (Test Data)." }, { "url": "https://api-staging.boltapp.com", "description": "The Staging URL (Staged Data)." } ], "security": [ { "X-API-Key": [] }, { "OAuth": [ "bolt.account.manage", "bolt.account.view" ] } ], "paths": { "/v1/tokenizer/proxy": { "post": { "summary": "Authorize a Card using TaaS", "description": "The `POST /v1/tokenizer/proxy` endpoint allows enterprise merchants to **securely authorize transactions with their preferred payment processors (PSPs)** by proxying requests through Bolt's PCI-compliant infrastructure. This API is part of Bolt's Tokenization-as-a-Service (TaaS) platform, enabling merchants to inject sensitive card data (e.g., PAN, CVV) into PSP-native request formats without directly handling raw card data.\nThe proxy replaces placeholders in the merchant-defined request body with actual card data retrieved securely using the provided `x-bolt-taas-id`, and forwards the complete request to the specified `x-bolt-forward-to` URL using the HTTP method specified in `x-bolt-forward-verb`.\n", "operationId": "proxyTransaction", "tags": [ "Transactions" ], "security": [ { "X-API-Key": [] } ], "parameters": [ { "$ref": "#/components/parameters/x-bolt-forward-to" }, { "$ref": "#/components/parameters/x-bolt-taas-id" }, { "$ref": "#/components/parameters/x-bolt-forward-verb" } ], "requestBody": { "description": "Use this API to proxy an authorization request to a third-party PSP endpoint using Bolt's secure infrastructure.\n\n - Replace raw card fields (e.g., card[number]) with placeholders like `{{tk:cc}}`, `{{tk:cvv}}`, `{{tk:exp_month}}`, etc.\n - The placeholders will be securely replaced by Bolt using the identifier from `x-bolt-taas-id`.\n - The `x-bolt-forward-to` header must point to a whitelisted PSP URL.\n - The `x-bolt-forward-verb` header specifies the HTTP method (POST, PUT, or PATCH) for the PSP request.\n\n**Never submit raw PAN, CVV, or expiration directly. Use placeholders.**\nSupported placeholders:\n - `{{tk:cc}}` – Full card number \n - `{{tk:cvv}}` – Card CVV \n - `{{tk:exp_month}}` – Expiration month \n - `{{tk:exp_year}}` – Expiration year\n", "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": { "default": { "value": { "type": "card", "card": { "number": "{{tk:cc}}", "exp_month": "{{tk:exp_month}}", "exp_year": "{{tk:exp_year}}", "cvc": "{{tk:cvv}}" }, "billing_details": { "name": "Jane Doe", "address": { "postal_code": "94107" } } } } } } } }, "responses": { "200": { "description": "Successful proxy to the PSP. Returns the PSP's response along with a unique proxy operation ID for tracking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "description": "HTTP status code returned by the PSP", "examples": [ 200 ] }, "body": { "type": "string", "description": "Response body from the PSP (JSON string)", "examples": [ "{\"id\":\"pm_1NQzWT2eZvKYlo2C\",\"object\":\"payment_method\",\"type\":\"card\",\"card\":{\"last4\":\"4242\",\"brand\":\"visa\",\"exp_month\":12,\"exp_year\":2026}}" ] }, "header": { "type": "object", "description": "Response headers from the PSP", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "examples": [ { "Content-Type": [ "application/json" ] } ] }, "proxy_operation_id": { "type": "string", "description": "Unique identifier for this proxy operation", "examples": [ "PROXY-ABC123-DEF456-GHI789" ] } } }, "examples": { "default": { "value": { "status_code": 200, "body": "{\"id\":\"pm_1NQzWT2eZvKYlo2C\",\"object\":\"payment_method\",\"type\":\"card\",\"card\":{\"last4\":\"4242\",\"brand\":\"visa\",\"exp_month\":12,\"exp_year\":2026}}", "header": { "Content-Type": [ "application/json" ] }, "proxy_operation_id": "PROXY-ABC123-DEF456-GHI789" } } } } } }, "400": { "description": "Missing required headers or invalid request body", "content": { "application/json": { "examples": { "default": { "value": { "error": "Missing required headers (x-bolt-forward-to, x-bolt-taas-id, x-bolt-forward-verb) or invalid JSON body" } } } } } }, "401": { "description": "Unauthorized - missing or invalid merchant API key", "content": { "application/json": { "examples": { "default": { "value": { "error": "Invalid or missing merchant API key" } } } } } }, "422": { "description": "Invalid TaaS ID or credit card/token not found", "content": { "application/json": { "examples": { "default": { "value": { "error": "Invalid x-bolt-taas-id. Credit card not found or expired." } } } } } }, "502": { "description": "Upstream PSP error during proxy forwarding", "content": { "application/json": { "examples": { "default": { "value": { "error": "Stripe returned 402 - Card declined" } } } } } } } } } }, "components": { "parameters": { "x-bolt-forward-to": { "name": "X-Bolt-Forward-To", "in": "header", "description": "The fully qualified URL of the payment service provider (PSP) endpoint to which the request should be proxied. This URL must be whitelisted in advance by Bolt.\n", "required": true, "schema": { "type": "string", "examples": [ "https://api.stripe.com/v1/payment_methods" ] } }, "x-bolt-taas-id": { "name": "X-Bolt-Taas-Id", "in": "header", "description": "Provide your Tokenizer-as-a-Service (TaaS) identifier. This value tells Bolt which stored payment method to use when injecting sensitive data into the proxied request. The value must be in the following format:\n\n - `bolt_token:{token}` - Reference a Bolt-issued short-term token\n\nMerchant-scoped long-term tokens will be supported in a future release.\nExample usage allows Bolt to securely inject PAN, CVV, and expiration into the forwarded request body.\n", "required": true, "schema": { "type": "string", "examples": [ "bolt_token:your_bolt_token_here" ] } }, "x-bolt-forward-verb": { "name": "X-Bolt-Forward-Verb", "in": "header", "description": "The HTTP method to use when forwarding the request to the payment service provider (PSP) endpoint. This allows merchants to specify the appropriate HTTP verb for their PSP's API requirements.\n", "required": true, "schema": { "type": "string", "enum": [ "POST", "PUT", "PATCH" ], "examples": [ "POST" ] } } }, "securitySchemes": { "OAuth": { "description": "Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.\nFor all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.\n[Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)\n", "flows": { "authorizationCode": { "authorizationUrl": "https://api.boltapp.com/v1/oauth/authorize", "refreshUrl": "https://api.boltapp.com/v1/oauth/token", "scopes": { "bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data", "bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data", "openid": "This scope grants permissions that enable Bolt SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints" }, "tokenUrl": "https://api.boltapp.com/v1/oauth/token" } }, "type": "oauth2" }, "X-API-Key": { "description": "Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.", "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ```