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.
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": {
"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:00Z",
"updated_at": "2025-08-01T00:00:00Z",
"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": {
"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:00Z",
"updated_at": "2025-08-01T00:00:00Z",
"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 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": {
"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:00Z",
"updated_at": "2025-08-01T00:00:00Z",
"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:01Z"
}
}
],
"metadata": {
"observability": {
"trace_id": "2d137f00cc53f5a9265f3b40402f7892",
"client_id": "ACHwLNAA4-jc_testvault-sY8MF",
"vault_id": "tnt9hg3iiwy",
"account_id": "ACTrKr34UF7YyvbVPwcWqXHWn",
"fingerprint": "KCxZx3kkeXF9xnJvyzJHRwx5ycyrDNgzAXk8K15E5BpyuHmpTR5qfBRgzAvrzurFdtM"
}
}
}Last updated