Skip to main content
This guide shows how to call a third-party API with real card data through the Yuno PCI Proxy. If you have not read it yet, start with the PCI Proxy Overview.

​
Requirements

  • Your public-api-key and private-secret-key from the Yuno Dashboard.
  • A card stored with Yuno and its vaulted_token. See Enroll Payment Method.
  • The destination API you want to call, reachable over HTTPS on port 443, and registered on your destination allowlist.
Server-side onlyProxy requests detokenize card data and must only be made from your backend. Never expose your private-secret-key in client-side code.
1

Build the destination request

Write the request exactly as the destination API expects it — same body shape, same headers — but put vaulted token expressions where the card data belongs:
The four fields you can reference are number, expiration_month, expiration_year, and holder_name. They resolve to the stored card (PAN) data — this flow is specifically for retrieving card data from a vaulted token, not provider tokens or network tokens.Expressions work in the request body and in header values. Everything that is not an expression is forwarded untouched.
No CVVThere is no placeholder for the security code (CVV/CVC). Card networks do not allow it to be stored after a payment is authorized, so a stored payment method has none to inject — the available fields are number, expiration_month, expiration_year, and holder_name. If your destination requires the CVV, your customer must supply it and you include it directly in the body yourself (the proxy forwards it without storing it); note that transmitting a raw security code keeps that request in your PCI scope.
2

Send it through the proxy

Send the request to https://api.y.uno/v1/pci-proxy/forward with the destination in the yuno-proxy-destination-url header:
The HTTP method you use is the method the destination receives. Headers you set for the destination (like Authorization above) pass through; Yuno’s own credential headers and all yuno-* headers are stripped before forwarding.The yuno-account-id header is optional: include it when you need to scope the request to a specific account. Like all yuno-* headers it is removed before forwarding and never reaches the destination. It narrows which allowlisted destinations are permitted for the request; it does not affect token resolution — vaulted tokens are always scoped to your organization.Put the complete destination URL — including its path and any query string — in yuno-proxy-destination-url (for example https://api.example-processor.com/charges/ch_123/capture?expand=true). Do not add a path or query string to the /v1/pci-proxy/forward request itself; a query string on the proxy request is rejected, so that merchant data is never logged.
3

Read the response

The destination’s status code, headers, and body are returned to you unchanged, except that any card number the destination echoes back is redacted first (see Card data in responses below). Redirects are not followed: a 3xx from the destination is returned to you as-is, so you decide whether to follow it. The proxy adds diagnostic headers:
4

Handle errors

Errors produced by the proxy itself use the standard Yuno error format and never include the yuno-proxy-destination-status header:
A 401 is returned before your request reaches the proxy, so it does not carry the yuno-proxy-request-id header; every other response does.Any 4xx/5xx accompanied by yuno-proxy-destination-status is the destination’s own error, passed through for you to handle as if you had called it directly.

​
Content types

The proxy is content-type agnostic. It forwards the body verbatim, without parsing or coercing it to JSON. Expression resolution is a text substitution over the raw body bytes, so a vaulted_token expression is replaced wherever it appears — JSON, XML, SOAP, or form key-value pairs. Place the expressions inside your payload and send the Content-Type your destination expects. JSON is shown above. The examples below cover the other common formats. XML
SOAP — an XML envelope plus the destination’s own SOAPAction header, forwarded unchanged:
Form key-value pairs (application/x-www-form-urlencoded):
Special characters in holder_nameBecause substitution is literal, a holder_name containing markup or delimiter characters can break the payload structure at the destination:
  • XML / SOAP: a name with &, <, or > (for example Doe & Sons) can break well-formedness. The number, expiration_month, and expiration_year fields are digits only, so they are unaffected — the risk is limited to holder_name.
  • Form key-value pairs: a name with &, =, or spaces can break the key/value structure. Send holder_name URL-encoded, or use a JSON/XML payload if the holder name may contain special characters.

​
Card data in responses

If a destination echoes a card number back in its response, the proxy redacts it before returning the response to you — keeping only the last four digits — so raw card numbers never reach your systems. The number of redactions is reported in the yuno-proxy-response-redactions response header:
A non-zero yuno-proxy-response-redactions is a signal that your destination is returning card data you should not receive. Redaction is the default behavior. Yuno can optionally be configured — as a service-wide setting, not per account — to instead reject any response containing card data with 502 RESPONSE_BLOCKED.

​
Authenticating to the destination

A proxy request carries two independent sets of credentials:
  • Your Yuno credentials (public-api-key / private-secret-key) authenticate you to the proxy. They are consumed by Yuno and never forwarded.
  • The destination’s own credentials are whatever that third-party API expects. Put them on the request and they are forwarded untouched — Yuno only strips its own headers.
Send whatever authentication header your destination requires — it is not limited to Authorization. The header name is defined by the destination provider’s API, not by Yuno; take it from that provider’s own documentation. What Yuno forwards vs. removes: Common authentication header names by provider (examples — always check the destination’s docs):
Signed requests and mutual TLS are not yet supportedBecause the proxy substitutes the real card number only inside its secure environment, you cannot pre-compute a request signature (HMAC) over a body that contains a {{vaulted_token…}} placeholder — the signature would have to be calculated over the resolved body containing the real PAN, which you never see.Similarly, destinations that require mutual TLS (a client certificate) are not supported inline: the certificate is presented by Yuno during the TLS handshake, not sent in your request, so it must be configured with Yuno per destination rather than passed in the body or a header.Both request signing and mTLS are planned for a later release via managed proxy routes.

​
Timeouts

The proxy waits up to 30 seconds for the destination by default. Override it with the yuno-proxy-timeout header (seconds, maximum 120):

​
Testing in sandbox

Use https://api-sandbox.y.uno/v1/pci-proxy/forward with your sandbox credentials and sandbox vaulted_token values. Sandbox tokens resolve to test card numbers, so you can point the proxy at your destination’s own sandbox safely.
Verify your integrationCheck yuno-proxy-replacements in the response while integrating: it confirms the proxy found and replaced your expressions before forwarding.