Skip to main content
PUT
Forward a request to a PSP, substituting vaulted card data

Authorizations

X-Primer-Api-Key
string
header
required

Primer key for the proxy, distinct from the merchant's own PSP credential on the same request.

Headers

X-Target-Host
string<hostname>
required

Destination host for this request. Must be on both the global Primer allowlist and the merchant's own allowlist, or the proxy returns 403 destination_not_allowed.

Example:

"api.stripe.com"

Path Parameters

proxyPath
string
required

The target PSP's endpoint path, forwarded to X-Target-Host unchanged, including any further segments and query string.

Body

The request body to forward, with card placeholders substituted.

Response

The target PSP's response, relayed unchanged, unless X-Primer-Proxy-Error is present on the response, in which case the body is a Primer-raised problem document instead (application/problem+json). Known Primer fault statuses: 400 invalid_request, 401 unauthorized, 403 vault_not_enabled, 403 destination_not_allowed, 404 token_not_found, 405 method_not_allowed, 409 token_consumed, 410 token_expired, 413 payload_too_large, 415 unsupported_content_encoding, 422 unresolved_placeholder / unknown_field / field_not_available / card_data_in_request, 502 psp_unreachable, 503 vault_unavailable, 504 psp_timeout. Any other status is the PSP's own.

RFC 7807 problem document for a Primer-raised proxy fault. Present only when the response carries X-Primer-Proxy-Error: true.

type
string
required

Slug naming the Primer fault, for example token_not_found or unresolved_placeholder.

title
string
required

Short, human-readable summary of the fault.

status
integer<int32>
required

HTTP status code, repeated from the response.

detail
string
required

Human-readable explanation specific to this occurrence.

instance
string
required

The request ID, matching X-Primer-Request-Id.

forwarded
enum<string>
required

Whether the request reached the PSP. false: it did not, safe to retry once fixed. unknown: it left for the PSP with no usable answer back, retry only with the same PSP idempotency key or check with the PSP first. true: the PSP answered but the proxy could not relay it.

Available options:
false,
unknown,
true
token
string

The token implicated in the fault, where relevant.

field
string

The placeholder field implicated in the fault, where relevant.