PCI Proxy Dashboard ↗️Status Page
API Reference

HTTP headers and errors

Making sense of requests that we return to you.

For push (third-party initiated) or pull (merchant initiated) requests, the response's HTTP headers will tell you what happened in the request.

❗️

An 'Error' in this context does not refer to an 'HTTP error' (e.g. response codes 400-499 or 500-599).

'Errors' here refer to when tokenization or detokenization was not executed properly. For example, x-cc-error (missing header) may be returned along with a HTTP response code of 200.

HTTP HeaderDescription
x-cc-error-codeAn error code returned by PCI Proxy in case of error. This means we were not able to tokenize or detokenize properly.
x-cc-errorAn error message returned by PCI Proxy which corresponds to x-cc-error-code. See the error table for more details.
x-cc-matchesReturned by us in case of success. The value represents the number of total replacements (card to alias or alias to card) that were made.
x-cc-matches-caThe number of card to alias replacements.
x-cc-matches-acThe number of alias to card replacements.
x-cvv-matchesThe total number of CVV to alias and alias to CVV replacements.
x-cvv-matches-acvvThe number of alias to CVV replacements.
x-cvv-matches-cvvaThe number of CVV to alias replacements.
x-custom-matchesReturned by us in case of a successful replacement. The value represents the number of total replacements (custom value to alias or alias to custom value) that were made.
pci-proxy-masked-aliasesThis header contains pairs of tokens, in the format of alias2.0=masked card. For example,
AAABcH0Bq92s3kgAESIAAbGj5NIsAHWC=424242xxxxxx4242.

There is a pair for each tokenization and in the case of multiple tokens, they are separated by semicolons, for example:
AAABcH0BrGOs3kgAESIAAc6gFVXTAGTv=540400xxxxxx0001; AAABcH0Bq92s3kgAESIAAbGj5NIsAHWC=424242xxxxxx4242.
x-cc-proxy-action-idThe unique request identifier.

For push requests, the following header is also returned:

HTTP HeaderDescription
x-cc-forwarded-forReturns the IP address of the origin called of the Push integration.

Special error cases

❗️

In case of XML requests/response bodies, the charset must be specified in the Content-type header so that we are able to read them properly.

If not specified, PCI Proxy defaults to ISO-8859-1.

If we are able to parse and correctly match the replacement targets but an error occurs during tokenization or detokenization, the match will be replaced with a constant which has 16 characters.

Possible constantsx-cc-errorDescription
0000000000000000Invalid card number.The card number/CVV was matched but it was invalid.
0000000000000001Internal error.The card number/CVV was matched but an internal error occurred during the transformation to alias.

Example

If a channel response contains three card numbers and one of them fails to validate or convert, the two successful replacement tokens will be present in the returned body and the failed card number will be replaced with one of the two special constants above. No x-cc-error or x-cc-error-code headers will be returned and x-cc-matches will have the value 2.

Error codes

To reiterate, the following error codes are internal to PCI Proxy and are not related to HTTPS codes. They correspond to x-cc-error and x-cc-error-code as seen above.

Request errors

Error codeError messageExplanation
1Missing header: <HEADER-NAME>.One or more required headers are missing.
2Invalid merchantId.Merchant not found, disabled or not properly configured. Get in touch with support.
3Target host not allowed: x-cc-url.The target URL is not allowed.
4Invalid merchant setup: security sign was not defined.Merchant did not define the security sign.
5Invalid authentication (API-key or sign).Either pci-proxy-api-key or sign is incorrect.
6Invalid proxy type.
7Invalid XPath.
8Invalid target URL.
9Invalid proxy type: white-label not matched.The provided merchant/url headers did not match to a valid known proxy type. Get in touch with support.

Push request errors

Error codeError messageExplanation
50Missing parameter: <PARAMETER-NAME>.Push request parameter missing.

HTTP layer errors

Error codeError messageExplanation
100Unsupported method: <METHOD-NAME>.Unsupported HTTP method.

Processing errors

Error codeError messageExplanation
200Could not apply XPath on XML response: <XPATH-EXPRESSION>.There was an error applying the XPATH expression.
201Denied by velocity check.Sent during alias to card conversion if there were too many attempts to convert bad aliases to cards.

You can make 20 bad alias requests in a 15 minute window, after which the IP is blocked. As soon as you stop sending bad aliases, it takes a maximum of 15 minutes to get unblocked.
202Denied by parallel connection checker.Security measure for too many parallel requests.
203Denied by whitelist.The IP is not whitelisted on PCI Proxy. Get in touch with support.

Parse errors

Error codeError messageExplanation
300Unknown content type in third-party response: <CONTENT-TYPE>.PCI Proxy is not able to parse the third-party response.
301Unknown content type in source request: <CONTENT-TYPE>.PCI Proxy is not able to parse the source request.
303Invalid payload.

Configuration errors

Error codeError messageExplanation
400Pull not configured.There is no pull configuration for the specified merchant. Get in touch with support.
401Missing push configuration for: <REASON>.Incorrect merchant configuration. Get in touch with support.
402Missing billing configuration for: <REASON>.
403Invalid SSL certificate.

Connection errors

Error codeError messageExplanation
800Connection error.PCI Proxy could not connect to a third-party, or encountered an error that caused no response, for example a read timeout or DNS error. We return a HTTP error code of 504 (Gateway Timeout) and an empty response.

Unknown errors or exceptions

Error codeError messageExplanation
900PCI Proxy error.Uncategorized system error.
901PCI Proxy internal error.Uncategorized internal system error.