> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/developer-resources/api/payment-account-reference.md).

# Payment Account Reference

## Retrieve a Payment Account Reference for a stored card

> Looks up the Payment Account Reference (PAR) for a card that has been\
> stored in VGS, identified by the \`card\_id\` path parameter.\
> \
> VGS resolves the lookup credential from the card's \`token\_type\`: for a\
> \`pan\` card the PAN is sent to the network, while for an \`mpan\` or \`dpan\`\
> card the stored network token is sent instead. VGS routes the request to\
> the appropriate card network, handles all payload encryption and\
> credential management, and returns a normalized PAR response — the\
> \`token\_type\` used is echoed in the response attributes.\
> \
> VGS resolves the PAR value in the following order, returning it without\
> a network call when it is already stored:\
> \
> 1\. If a PAR value is found on the card's network token, return that PAR\
> &#x20;  value.\
> 2\. Otherwise, if a PAR value is found on the persisted card, return that\
> &#x20;  PAR value.\
> 3\. Otherwise, call the card network to retrieve the PAR value, then\
> &#x20;  persist the result so subsequent lookups are network-free.\
> \
> The PAR is durable and does not expire. It is persisted internally and\
> is returned on \`GET /cards/{card\_id}\` once a successful lookup has been\
> performed.\
> \
> PAR lookup must be explicitly enabled at the CMP account level; the\
> endpoint returns \`403 Forbidden\` for accounts where it has not been\
> activated.<br>

```json
{"openapi":"3.1.0","info":{"title":"VGS Card Management Platform (CMP) API","version":"doc version 2.2.9 | API version 1.0.0"},"tags":[{"name":"Payment Account Reference"}],"servers":[{"url":"https://sandbox.vgsapi.com","description":"Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.\n"},{"url":"https://vgsapi.com","description":"Live environment server used for production workloads.\n"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"auth-header":{"in":"header","name":"Authorization","description":"Bearer token for authentication.","schema":{"type":"string"},"required":true},"content-type":{"in":"header","name":"Content-Type","description":"Content type of a request to CMP","schema":{"type":"string","enum":["application/vnd.api+json"]},"required":true}},"schemas":{"PaymentAccountReferenceResponseEnvelope":{"title":"PaymentAccountReferenceResponseEnvelope","type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships"],"properties":{"id":{"type":"string","description":"Opaque identifier for this PAR lookup result."},"type":{"type":"string","enum":["payment-account-references"]},"attributes":{"$ref":"#/components/schemas/PaymentAccountReferenceAttributes"},"relationships":{"$ref":"#/components/schemas/PaymentAccountReferenceRelationships"}}},"meta":{"$ref":"#/components/schemas/MetadataResponse"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"additionalProperties":false},"PaymentAccountReferenceAttributes":{"title":"PaymentAccountReferenceAttributes","type":"object","required":["payment_account_reference","network","token_type"],"properties":{"token_type":{"allOf":[{"$ref":"#/components/schemas/TokenType"}],"description":"The credential type VGS used to perform the lookup, resolved from\nthe card stored under `card_id` (the client does not supply it):\n- `pan`: the card stores a PAN; VGS sent the PAN to the network.\n- `mpan` / `dpan`: the card stores a network token (merchant PAN or\n  device PAN); VGS sent that network token to the network instead of\n  a PAN.\n"},"payment_account_reference":{"type":"string","minLength":29,"maxLength":32,"pattern":"^[0-9A-Z]{29,32}$","description":"Payment Account Reference value issued by the card network. Links\nthe PAN to all associated network tokens for consistent transaction\ntracking. Fixed length: 29 to 32 uppercase alphanumeric characters\ndepending on the issuing network.\n"},"network":{"type":"string","enum":["visa","mastercard","discover"],"description":"The card network that issued the PAR."},"par_creation_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Date the PAR was created by the network, in ISO 8601 format\n(`YYYY-MM-DD`). Populated only for networks that supply a creation\ndate; null otherwise.\n"}}},"TokenType":{"type":"string","description":"The type of token being used for the card.","enum":["dpan","mpan","pan"]},"PaymentAccountReferenceRelationships":{"title":"PaymentAccountReferenceRelationships","type":"object","required":["card"],"properties":{"card":{"$ref":"#/components/schemas/CardRelationship"}},"additionalProperties":false},"CardRelationship":{"title":"CardRelationship","type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["cards"],"description":"Related resource type. Must be `cards`."},"id":{"type":"string","description":"VGS card id identifying the stored card."}},"additionalProperties":false}},"additionalProperties":false},"MetadataResponse":{"type":"object","title":"MetadataResponse","properties":{"observability":{"$ref":"#/components/schemas/Observability"}}},"Observability":{"type":"object","title":"Observability","properties":{"trace_id":{"type":"string"},"client_id":{"type":"string"},"vault_id":{"type":"string"},"account_id":{"type":"string"},"fingerprint":{"type":"string"}}},"JsonApiVersion":{"properties":{"version":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Version","default":1.1},"ext":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Ext"}]},"profile":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Profile"}]},"meta":{"type":"object","title":"Meta"}},"title":"JsonApi"},"PaymentAccountReferenceErrorResponse":{"title":"PaymentAccountReferenceErrorResponse","type":"object","required":["errors"],"properties":{"errors":{"type":"array","description":"One or more errors describing why the request failed.","items":{"type":"object","required":["error_code","summary","detail"],"properties":{"error_code":{"type":"string","enum":["unauthorized","forbidden","service-not-enabled","card-not-found","par-not-found","unsupported-par-network","service-unavailable","internal-server-error"],"description":"Machine-readable error code."},"summary":{"type":"string","description":"Short human-readable summary of the error."},"detail":{"type":"string","description":"Longer human-readable explanation of the error."},"path":{"type":"string","description":"JSON path or request location the error pertains to (e.g. `data.type` or `path.card_id`)."}}}},"meta":{"$ref":"#/components/schemas/MetadataResponse"}},"additionalProperties":false}}},"paths":{"/cards/{card_id}/payment-account-references":{"post":{"tags":["Payment Account Reference"],"summary":"Retrieve a Payment Account Reference for a stored card","description":"Looks up the Payment Account Reference (PAR) for a card that has been\nstored in VGS, identified by the `card_id` path parameter.\n\nVGS resolves the lookup credential from the card's `token_type`: for a\n`pan` card the PAN is sent to the network, while for an `mpan` or `dpan`\ncard the stored network token is sent instead. VGS routes the request to\nthe appropriate card network, handles all payload encryption and\ncredential management, and returns a normalized PAR response — the\n`token_type` used is echoed in the response attributes.\n\nVGS resolves the PAR value in the following order, returning it without\na network call when it is already stored:\n\n1. If a PAR value is found on the card's network token, return that PAR\n   value.\n2. Otherwise, if a PAR value is found on the persisted card, return that\n   PAR value.\n3. Otherwise, call the card network to retrieve the PAR value, then\n   persist the result so subsequent lookups are network-free.\n\nThe PAR is durable and does not expire. It is persisted internally and\nis returned on `GET /cards/{card_id}` once a successful lookup has been\nperformed.\n\nPAR lookup must be explicitly enabled at the CMP account level; the\nendpoint returns `403 Forbidden` for accounts where it has not been\nactivated.\n","operationId":"createPaymentAccountReference","parameters":[{"$ref":"#/components/parameters/auth-header"},{"$ref":"#/components/parameters/content-type"},{"name":"card_id","in":"path","required":true,"description":"VGS card id identifying the stored card.","schema":{"type":"string"}}],"responses":{"200":{"description":"PAR successfully retrieved (from a persisted result or a fresh network lookup).","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceResponseEnvelope"}}}},"401":{"description":"No credentials were provided, or the provided credentials were expired.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}},"403":{"description":"PAR lookup has not been enabled for this CMP account, or the\nprovided credentials do not permit access to this resource.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}},"404":{"description":"No stored card exists for the given `card_id`, or the card does not belong to the authenticated account.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}},"422":{"description":"The request could not be processed due to a validation failure.\nIncludes `par-not-found` when the card network has no Payment\nAccount Reference for the account. This is a definitive negative\nresult from the network — not a technical failure (which surfaces as\n`500`). Also includes `unsupported-par-network` when the card's\nnetwork does not have a certified PAR integration (currently\nsupported: Visa, Mastercard, Discover).\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}},"500":{"description":"Internal Server Error — a non-recoverable error occurred (including a non-recoverable failure from the upstream card network). The request should not be reattempted.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}},"503":{"description":"The upstream card network is temporarily unavailable (rate-limited or throttled). Retry after a brief delay.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/PaymentAccountReferenceErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/payment-account-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.