Cards
The Create Card Operation allows clients to register a card into the Card Management Platform (CMP) using a simple API call. This card object is linked to a specific account, supporting account-level management and visibility. Each card is uniquely identified by a persistent Card ID, which does not change, even if updates are made to the underlying card data. This Approach enables businesses to manage card-related features like tokenization and account updates in a centralized, consistent way. (Read more about Duplicate Card Detection and Card Fingerprint). CMP ensures secure handling and logical grouping of cards under customer accounts, offering a scalable and organized card management experience.
The card object also supports user-defined metadata through a meta object. This allows clients to attach structured, application-specific information to a card without affecting payment processing. Metadata can include any string key-value pairs to meet business needs — for example, linking a card to internal customer records, identifying the source system, or tagging the card with relevant attributes.
PAN and Card Verification Code (CVC) tokens/aliases generated by VGS will be included as part of the response and the actual CVC can be included securely as part of a transaction. Only PCI-Compliant clients will be able to view the actual CVC, while non-PCI-Compliant clients will only be able to view an indicator that CVC was added as part of the transaction. Find more information on CVC here.
Optional processing mode for the card creation request.
This feature is currently in BETA and is available only to customers using the Migration Capability. Contact your VGS customer representative to learn more or request access.
Example: POST /cards?processing=backbook
backbook: network token and account updater enrollment are skipped, treating the card as backbook traffic.
Ignored on Wallet Decryption card creation requests.
The card information.
Card created
The card you are trying to create already exists within the system.
The request was invalid.
No credentials were provided, or the provided credentials were expired.
Valid credentials were provided, but they do not permit access to this resource.
The server was unable to process the request because it contains invalid data.
Internal Server Error
Service Unavailable
POST /cards HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 90
{
"data": {
"attributes": {
"pan": "4111111111111111",
"cvc": "123",
"exp_month": 4,
"exp_year": 28
}
}
}{
"data": {
"id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"type": "cards",
"attributes": {
"enrollment_source": "frontbook",
"pan": "4111111111111111",
"cvc_status": "active",
"pan_alias": "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu",
"cvc": "123",
"cvc_alias": "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL",
"token_type": "pan",
"bin": "411111",
"first8": "41111111",
"last4": "1111",
"exp_month": 5,
"exp_year": 28,
"card_fingerprint": "6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu",
"capabilities": [
"network-tokens",
"card-updates"
],
"created_at": "2025-08-01T00:00:00.123456Z",
"updated_at": "2025-08-01T00:00:00.123456Z",
"card_brand": "VISA",
"card_type": "DEBIT"
}
},
"metadata": {
"observability": {
"trace_id": "2d137f00cc53f5a9265f3b40402f7892",
"client_id": "ACHwLNAA4-jc_testvault-sY8MF",
"vault_id": "tnt9hg3iiwy",
"account_id": "ACTrKr34UF7YyvbVPwcWqXHWn",
"fingerprint": "KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM"
}
}
}The Get Card API allows clients to retrieve details for a specific card using its unique Card ID. This includes core card metadata and any associated account updater or network token information, if applicable. This endpoint is useful for verifying enrollment status, accessing the current state of a card, or reviewing the card's lifecycle attributes. It provides a comprehensive snapshot of the card and its current relationships within CMP.
Comma-delimited list of fields to include in the response.
Item requested by ID
The request was invalid.
No credentials were provided, or the provided credentials were expired.
Valid credentials were provided, but they do not permit access to this resource.
Resource not found.
Internal Server Error
Service Unavailable
GET /cards/{card_id} HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": {
"id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"type": "cards",
"attributes": {
"enrollment_source": "frontbook",
"payment_account_reference": "V0013545834930585516258022674",
"pan": "4111111111111111",
"pan_alias": "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu",
"cvc": "123",
"cvc_status": "active",
"cvc_alias": "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL",
"token_type": "pan",
"bin": "411111",
"first8": "41111111",
"last4": "1111",
"exp_month": 5,
"exp_year": 28,
"card_fingerprint": "6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu",
"cardholder": {
"name": "John Q. Public",
"company": "Acme Co.",
"phone": "+18009998888",
"email": "bob.smith@gmail.com",
"address": {
"address1": "123 Main St.",
"address2": "Suite 404",
"address3": "another row",
"address4": "and another row",
"city": "San Francisco",
"region": "CA",
"postal_code": "80922",
"country": "US"
}
},
"capabilities": [
"network-tokens",
"card-updates"
],
"created_at": "2025-08-01T00:00:00.123456Z",
"updated_at": "2025-08-01T00:00:00.123456Z",
"card_brand": "VISA",
"card_type": "DEBIT",
"enriched_attributes": {
"card_properties": {
"card_number_length": 16,
"card_segment_type": "PERSONAL",
"virtual_card": false,
"prepaid_card": false,
"product_name": "CLASSIC",
"issuer_bin": "411111",
"country_letter_code": "US",
"country_name": "UNITED STATES",
"country_numeric": 840
},
"card_capabilities": {
"reloadable": false,
"hsa": true,
"fsa": false,
"ebt": false,
"commercial_level2": true,
"commercial_level3": false
},
"bank": {
"issuer_name": "U.S. EQUITY ADVANTAGE, INC.",
"issuer_phone_number": "1-800-123-4567",
"issuer_website": "https://www.examplebank.com"
},
"additional_card_brands": [
{
"card_brand": "BANCONTACT"
}
],
"interchange": {
"regulated": "N"
}
}
}
},
"included": [
{
"type": "card_update_subscriptions",
"id": "CUSgkqZl3zRgXU3TFmtcDduFt",
"attributes": {
"created_at": "2019-05-15T12:30:45.123456Z",
"updated_at": "2019-05-16T06:00:01.123456Z",
"state": "enrolled"
}
},
{
"type": "card_updates",
"id": "ae1189bf-9b9b-4ec4-9214-119fafb87b52",
"attributes": {
"changed_fields": [
"pan",
"exp_month",
"exp_year"
],
"updated_values": [
{
"field_name": "pan",
"old_value": 4111111111111111,
"new_value": 411111111111123
},
{
"field_name": "exp_month",
"old_value": 5,
"new_value": 7
},
{
"field_name": "exp_year",
"old_value": 25,
"new_value": 27
}
],
"event": "updated",
"received_at": "2019-05-16T06:00:01.123456Z"
}
},
{
"type": "network_tokens",
"id": "NTecqZp3xRgXU3TFmtcDdzQa",
"attributes": {
"network_token": "99999900059200",
"last4": "9200",
"bin": "999999",
"payment_account_reference": "V0013545834930585516258022674",
"state": "active",
"created_at": "2019-05-15T12:30:45.123456Z",
"updated_at": "2019-05-15T12:32:00.123456Z",
"exp_month": 12,
"exp_year": 25
},
"meta": {
"card_art": {
"foreground_color": "0F0F0F",
"issuer_name": "Test-Issuer",
"short_description": "MasterCard Test Bank",
"long_description": "Test Bank for MasterCard MTF",
"assets": [
{
"type": "CARD_SYMBOL",
"mime_type": "image/png",
"width": 1536,
"height": 968,
"download_url": "https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CAacNMMShJk4pqhmY2E1N8Vz.png"
},
{
"type": "DIGITAL_CARD_ART",
"mime_type": "image/png",
"width": 1536,
"height": 969,
"download_url": "https://assets.calm.sandbox.verygoodsecurity.com/sandbox/calm/assets/CA3JmEG1bSX88VSv4f5Gz2pG.png"
}
]
}
}
}
],
"metadata": {
"observability": {
"trace_id": "2d137f00cc53f5a9265f3b40402f7892",
"client_id": "ACHwLNAA4-jc_testvault-sY8MF",
"vault_id": "tnt9hg3iiwy",
"account_id": "ACTrKr34UF7YyvbVPwcWqXHWn",
"fingerprint": "KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM"
}
}
}The Delete Card API allows clients to permanently remove a card object from the CMP system using a unique Card ID. This operation automatically removes all services associated with the card, such as Network Tokens and Account Updater. Please note that this action is irreversible; once deleted, the card object cannot be recovered, and subsequent calls to the GET endpoint will return no data.
Note: Error responses currently omit payload previews; expect a standard JSON error object.
Card deleted
No content
No credentials were provided, or the provided credentials were expired.
Valid credentials were provided, but they do not permit access to this resource.
Resource not found.
Internal Server Error
Service Unavailable
DELETE /cards/{card_id} HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
The Update Card API enables clients to modify specific fields on a card using its unique Card ID. The update endpoint only updates the card object; it does not automatically trigger any secondary services or processes. The endpoint response provides a comprehensive snapshot of the card object and its current relationships within CMP.
Card update request payload
Updated card
The request was invalid.
No credentials were provided, or the provided credentials were expired.
Valid credentials were provided, but they do not permit access to this resource.
Resource not found.
The server was unable to process the request because it contains invalid data.
Internal Server Error
Service Unavailable
PATCH /cards/{card_id} HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 65
{
"data": {
"attributes": {
"cvc": "123",
"exp_month": 4,
"exp_year": 28
}
}
}{
"data": {
"id": "CRDecqZp3xRgXU3TFmtcDdzQsx",
"type": "cards",
"attributes": {
"enrollment_source": "frontbook",
"pan": "4111111111111111",
"pan_alias": "tok_sandbox_hhyPgvvdFfFGBnyi73TfFu",
"cvc": "123",
"cvc_alias": "tok_sandbox_5XK62B8G2i1mTwoGR5o4tL",
"cvc_status": "active",
"token_type": "pan",
"bin": "411111",
"first8": "41111111",
"last4": "1111",
"exp_month": 4,
"exp_year": 28,
"card_fingerprint": "6TeSCB16LtyifEAmY2goxYfSk5sALriXpefzzxh29xhu",
"capabilities": [
"network-tokens",
"card-updates"
],
"created_at": "2025-08-01T00:00:00.123456Z",
"updated_at": "2025-08-01T00:00:00.123456Z",
"card_brand": "VISA",
"card_type": "DEBIT"
}
},
"included": [
{
"type": "card_updates",
"id": "ae1189bf-9b9b-4ec4-9214-119fafb87b52",
"attributes": {
"changed_fields": [
"cvc",
"exp_month",
"exp_year"
],
"updated_values": [
{
"field_name": "exp_month",
"old_value": 5,
"new_value": 4
},
{
"field_name": "exp_year",
"old_value": 24,
"new_value": 28
}
],
"event": "api-update",
"received_at": "2019-05-16T06:00:01.123456Z"
}
}
],
"metadata": {
"observability": {
"trace_id": "2d137f00cc53f5a9265f3b40402f7892",
"client_id": "ACHwLNAA4-jc_testvault-sY8MF",
"vault_id": "tnt9hg3iiwy",
"account_id": "ACTrKr34UF7YyvbVPwcWqXHWn",
"fingerprint": "KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM"
}
}
}Last updated