Payment Account Reference

Beta

Retrieve a Payment Account Reference for a stored card

post

/cards/{card_id}/payment-account-references

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 value.

2. Otherwise, if a PAR value is found on the persisted card, return that PAR value.

3. Otherwise, call the card network to retrieve the PAR value, then 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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

card_idstringRequired

VGS card id identifying the stored card.

Example: CRDbQQBKWZjT2mCrE75SDHXdB

Header parameters

AuthorizationstringRequired

Bearer token for authentication.

Example: Bearer <JWT_TOKEN>

Content-Typestring · enumRequired

Content type of a request to CMP

Example: application/vnd.api+jsonPossible values:

Responses

200

PAR successfully retrieved (from a persisted result or a fresh network lookup).

application/vnd.api+json

401

No credentials were provided, or the provided credentials were expired.

application/vnd.api+json

403

PAR lookup has not been enabled for this CMP account, or the provided credentials do not permit access to this resource.

application/vnd.api+json

404

No stored card exists for the given card_id, or the card does not belong to the authenticated account.

application/vnd.api+json

422

The request could not be processed due to a validation failure. Includes par-not-found when the card network has no Payment Account Reference for the account. This is a definitive negative result from the network — not a technical failure (which surfaces as 500). Also includes unsupported-par-network when the card's network does not have a certified PAR integration (currently supported: Visa, Mastercard, Discover).

application/vnd.api+json

500

Internal Server Error — a non-recoverable error occurred (including a non-recoverable failure from the upstream card network). The request should not be reattempted.

application/vnd.api+json

503

The upstream card network is temporarily unavailable (rate-limited or throttled). Retry after a brief delay.

application/vnd.api+json

post/cards/{card_id}/payment-account-references

POST /cards/{card_id}/payment-account-references HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: text
Content-Type: application/vnd.api+json
Accept: */*

{
  "data": {
    "id": "par_3xKz8mNpQrXtV9wBsYhLfDc",
    "type": "payment-account-references",
    "attributes": {
      "payment_account_reference": "5001A2B3C4D5E6F7G8H9J0K1L2M3N4P5",
      "network": "mastercard",
      "par_creation_date": "2024-03-15",
      "token_type": "pan"
    },
    "relationships": {
      "card": {
        "data": {
          "type": "cards",
          "id": "CRDbQQBKWZjT2mCrE75SDHXdB"
        }
      }
    }
  },
  "meta": {
    "observability": {
      "trace_id": "d03de953fee8276999edd5a2e682ffa6",
      "client_id": "ACa6ayoHU-am-sa-9-oF1Qj",
      "vault_id": "tntvhmnsawa",
      "account_id": "ACTfJPr7umSPZiJJckX3dMYLP",
      "fingerprint": "4GqVMr6PvjLWZzJDv3XcojYVTsiicTAD9MuJZrdZHfqT6DYNG7wGbdkDCuq"
    }
  }
}