Proxy Request

Makes a proxy request using created payment credentials with template substitution for secure credential handling.

Request

curl -X POST \
  https://api.basistheory.ai/tenants/your-tenant-id/proxy \
  -H 'BT-Authorization: Bearer your-api-key' \
  -H 'BT-Target-URL: https://api.merchant.com/payments' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "currency": "usd",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "{{ paymentMethod: 815029c2-29ec-4fc2-8cd4-99feb3ee582c | type: '\''virtualCard'\'' | json: '\''$.card.number'\'' }}",
        "exp_month": "{{ paymentMethod: 815029c2-29ec-4fc2-8cd4-99feb3ee582c | type: '\''virtualCard'\'' | json: '\''$.card.expirationMonth'\'' }}",
        "exp_year": "{{ paymentMethod: 815029c2-29ec-4fc2-8cd4-99feb3ee582c | type: '\''virtualCard'\'' | json: '\''$.card.expirationYear'\'' }}",
        "cvc": "{{ paymentMethod: 815029c2-29ec-4fc2-8cd4-99feb3ee582c | type: '\''virtualCard'\'' | json: '\''$.card.cvc'\'' }}"
      }
    }
  }'

URL Parameters

Parameter	Required	Type	Default	Description
`tenantId`	true	string	`null`	The tenant ID.

Required Headers

Authentication will use a slightly different header in the case of the Proxy to avoid colliding with the target url’s headers.

Header	Required	Description
`BT-Authorization`	true	Bearer token for API authentication
`BT-Target-URL`	true	The target API endpoint URL to proxy the request to

Template Syntax

The proxy supports template substitution to securely inject payment credentials into API requests.

Basic Template Format

{{ paymentMethod: <paymentMethodId> | type: '<credentialType>' | json: '<jsonPath>' }}

Template Components

Component	Description	Example
`paymentMethod`	The payment method ID	`815029c2-29ec-4fc2-8cd4-99feb3ee582c`
`type`	The credential type to use	`virtualCard`, `networkToken`, `pan`
`json`	JSONPath to extract specific field	`$.card.number`, `$.token.cryptogram`

Supported Credential Types

Type	Description	Available Fields
`virtualCard`	Virtual card credential	`$.number`, `$.expirationMonth`, `$.expirationYear`, `$.cvc`
`networkToken`	Network token credential	`$.number`, `$.expirationMonth`, `$.expirationYear`, `$.cryptogram`
`pan`	Original card PAN	`$..number`, `$.expirationMonth`, `$.expirationYear`, `$.cvc`

JSONPath Examples

// Virtual Card Fields
"{{ paymentMethod: <id> | type: 'virtualCard' | json: '$.number' }}"
"{{ paymentMethod: <id> | type: 'virtualCard' | json: '$.expirationMonth' }}"
"{{ paymentMethod: <id> | type: 'virtualCard' | json: '$.expirationYear' }}"
"{{ paymentMethod: <id> | type: 'virtualCard' | json: '$.cvc' }}"

Response

The proxy returns the response from the target API endpoint unchanged. Status codes and response bodies are passed through directly from the target API.

Error Handling

{
  "error": {
    "status": 400,
    "type": "invalidTemplate",
    "title": "Invalid template syntax",
    "message": "Template syntax is malformed in request body.",
    "details": {
      "field": "credit_card.number",
      "template": "{{ paymentMethod: invalid-id | type: 'virtualCard' }}"
    }
  }
}