---
updatedAt: 2025-08-21T13:31:22.000Z
agentTools:
siteIndex: https://merchants.westpac.com.au/llms.txt
projectIndex: https://merchants.westpac.com.au/onlinepay/llms.txt
---
# Create/Update Token Details
Create/Update a token using the OnlinePay Tokenisation Service.
If a token exists for the card already, it is updated with the information in the request. Otherwise, a new token is created for the given card.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "eCommerce API",
"description": "The OnlinePay eCommerce API is used to process and manage payments via RESTful API requests.",
"version": "2.0.0",
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"contact": {}
},
"servers": [
{
"url": "https://au.gsc.verifone.cloud/oidc",
"description": "Australia"
},
{
"url": "https://cst.test-gsc.vfims.com/oidc",
"description": "Global Sandbox"
}
],
"components": {
"securitySchemes": {
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"BadRequestV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 400,
"enum": [
400
],
"default": 400
},
"message": {
"type": "string",
"example": "At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL.",
"enum": [
"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."
],
"default": "At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."
}
},
"required": [
"message"
]
},
"UnauthorizedV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 401,
"enum": [
401
],
"default": 401
},
"message": {
"type": "string",
"example": "Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request).",
"enum": [
"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."
],
"default": "Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."
}
},
"required": [
"message"
]
},
"ForbiddenV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 403,
"enum": [
403
],
"default": 403
},
"message": {
"type": "string",
"example": "Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator.",
"enum": [
"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."
],
"default": "Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."
}
},
"required": [
"message"
]
},
"NotFoundV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 404,
"enum": [
404
],
"default": 404
},
"message": {
"type": "string",
"example": "The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights.",
"enum": [
"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."
],
"default": "The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."
}
},
"required": [
"message"
]
},
"InternalErrorV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 500,
"enum": [
500
],
"default": 500
},
"message": {
"type": "string",
"example": "Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error",
"enum": [
"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"
],
"default": "Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"
}
},
"required": [
"message"
]
},
"TokenContextDto": {
"type": "object",
"title": "token_context",
"description": "The context and identifiers related to the token request. **Mandatory** for external Third-Party tokens. Use of the /v2/card endpoint:\n\n * If reuse_token_type = INTERNAL => then token_scope mandatory; token_context optional, and only token_context.entity_id would be used (if provided);",
"properties": {
"entity_id": {
"type": "string",
"format": "uuid-flexible",
"description": "The identifier of merchant entity for which this request is related to."
},
"payment_provider_contract": {
"type": "string",
"format": "uuid-flexible",
"description": "The identifier of payment provider contract you want to process this request with. Relevant only for external Third-party tokens."
}
}
},
"PutDto": {
"type": "object",
"properties": {
"token_scope": {
"type": "string",
"title": "Token Scope",
"description": "The token scope under which this token was created.",
"format": "uuid",
"example": "0e48425a-f1bc-431a-b7d8-f866de8ba276"
},
"encrypted_card": {
"type": "string",
"title": "Client encrypted cardholder data",
"description": "The cardholder data encrypted using the OnlinePay provided public key. This can be obtained using either Verifone.JS solution or OnlinePay Checkout in capture mode.\n\n The data to encrypt is a JSON with possible tags being cardNumber, sequenceNumber, cardholderName, startMonth, startYear, expiryMonth, expiryYear, cvv. This should be a single JSON line and should not contain any spaces. Read Secure card capture key for details.\n\n Additionally, a tag called captureTime must be presenting indicating the time the card was captured in UTC in format RFC 3339, section 5.6. eg. 2019-08-24T14:15:22Z. Encrypted card is valid for only 15 minutes.",
"example": "U3dhZ2dlciByb2Nrcw=="
},
"card_brand": {
"type": "string",
"title": "The Card Type",
"description": "Represents a Card type or brand. It should correspond to a consistent name, the list of standard names is as follows:\n\nValue | Description\n------|-------------\nAMEX|American Express\nJCB|Japan Credit Bureau\nMASTERCARD|MasterCard\nVISA|Visa \n"
},
"token_type": {
"type": "string",
"title": "Token Type",
"description": "Token type",
"enum": [
"REUSE",
"ANALYTICS",
"REUSE_AND_ANALYTICS"
],
"default": "REUSE"
},
"reuse_token_type": {
"title": "Reuse Token Type",
"description": "The type of Reuse Token. This indicates if the reuse token is an internal OnlinePay type or an external Third-Party type.",
"type": "string",
"enum": [
"INTERNAL"
],
"default": "INTERNAL"
},
"token_expiry_date": {
"type": "string",
"description": "When this Token will expire.",
"format": "date"
},
"public_key_alias": {
"type": "string"
},
"token_context": {
"allOf": [
{
"$ref": "#/components/schemas/TokenContextDto"
}
]
}
},
"required": [
"token_scope",
"encrypted_card",
"public_key_alias"
]
},
"SchemeToken": {
"type": "object",
"description": "This object is returned only if scheme_tokens were created already or scheme_token_action indicated creation (ACTIVATE) of new or suspension (SUSPEND) or deletion () of existing scheme tokens. Scheme token details are provided only if the token requestor is the Merchant, otherwise just the scheme_token_status is returned.",
"properties": {
"network_token": {
"type": "string",
"minLength": 12,
"maxLength": 16,
"description": "Card scheme token. Will be received only if a valid Token Requestor ID is stored on your account."
},
"status": {
"type": "string",
"title": "Token Status Type",
"enum": [
"VALID",
"SUSPENDED",
"DELETED"
],
"description": "The status of the cardholder data token."
},
"expiry_month": {
"type": "integer",
"minimum": 12,
"description": "Network tokens' expiry date's month\n. A 2 digit value. ISO8583 - DE 14"
},
"expiry_year": {
"type": "integer",
"minimum": 9999,
"description": "Network tokens' expiry date's year. A 4 digit value."
},
"payment_account_reference": {
"type": "string",
"maxLength": 50,
"description": "Payment Account Reference"
}
}
},
"CardResponse": {
"type": "object",
"properties": {
"reuse_token": {
"type": "string",
"description": "The identifier used to represent the Cardholder data."
},
"analytics_token": {
"type": "string",
"description": "A token that cannot be reversed to Card Holder data. This is included in a Payment for auditing and tracking purposes."
},
"bin": {
"type": "string",
"minLength": 4,
"maxLength": 11,
"example": "492912",
"description": "The Bank Identification Number (also called IIN - Issuer Identification Number) of this card."
},
"expiry_month": {
"type": "integer",
"example": 12,
"maximum": 12,
"description": "A 2 digit value as shown on card. ISO8583 - DE 14"
},
"expiry_year": {
"type": "integer",
"example": 2021,
"maximum": 9999,
"description": "A 4 digit value as shown on card."
},
"last_four": {
"type": "string",
"maxLength": 4,
"example": "3127",
"description": "The last 4 digits of the card number."
},
"card_holder_name": {
"type": "string",
"maxLength": 30,
"example": "MR J HOLDER",
"description": "The Card holder name as it appears on the card."
},
"bin_details": {
"$ref": "#/components/schemas/BinDetails"
},
"updated_at": {
"type": "string",
"description": "The last date token was updated.",
"format": "date"
},
"created_at": {
"type": "string",
"description": "The last date token was created.",
"format": "date"
},
"token_expiry_date": {
"type": "string",
"description": "When this Token will expire.",
"format": "date"
},
"reuse_token_type": {
"title": "Reuse Token Type",
"description": "The type of Reuse Token. This indicates if the reuse token is an internal OnlinePay type or an external Third-Party type.",
"type": "string",
"enum": [
"INTERNAL"
]
},
"token_scope": {
"type": "string",
"description": "The token scope under which this token was created.",
"format": "uuid"
},
"token_status": {
"type": "string",
"description": "The status of the Token.",
"title": "Token Status Type",
"example": "ACTIVE",
"enum": [
"DELETED",
"ACTIVE",
"SUSPENDED"
]
},
"currency": {
"$ref": "#/components/schemas/CurrencyCodeEnum"
},
"issuer_country": {
"$ref": "#/components/schemas/issuerCountryEnum"
},
"scheme_token": {
"allOf": [
{
"$ref": "#/components/schemas/SchemeToken"
}
]
}
}
},
"BinDetails": {
"type": "object",
"properties": {
"bin": {
"type": "string",
"minLength": 4,
"maxLength": 11,
"example": "492912",
"description": "The Bank Identification Number (also called IIN - Issuer Identification Number) of this card."
},
"brand": {
"type": "string",
"example": "VISA",
"description": "The brand of this card. eg. VISA, MASTERCARD, AMEX."
},
"issuer_country": {
"$ref": "#/components/schemas/issuerCountryEnum"
},
"issuer_name": {
"type": "string",
"example": "HSBC",
"description": "The issuer of this card. eg. HSBC, BARCLAYS."
},
"last_four": {
"type": "string",
"maxLength": 4,
"example": "3127",
"description": "The last 4 digits of the card number."
},
"type": {
"type": "string",
"description": "The type of card application or account selection.",
"example": "CREDIT",
"enum": [
"DEBIT",
"CREDIT"
]
},
"variant": {
"type": "string",
"description": "The variant of the card. eg. NEW_WORLD",
"example": "NEW_WORLD"
}
}
},
"issuerCountryEnum": {
"type": "string",
"description": "The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
.",
"enum": [
"ZZZ",
"ABW",
"AFG",
"AGO",
"AIA",
"ALA",
"ALB",
"AND",
"ARE",
"ARG",
"ARM",
"ASM",
"ATA",
"ATF",
"ATG",
"AUS",
"AUT",
"AZE",
"BDI",
"BEL",
"BEN",
"BES",
"BFA",
"BGD",
"BGR",
"BHR",
"BHS",
"BIH",
"BLM",
"BLR",
"BLZ",
"BMU",
"BOL",
"BRA",
"BRB",
"BSB",
"BRN",
"BTN",
"BVT",
"BWA",
"CAF",
"CAN",
"CCK",
"CHE",
"CHL",
"CHN",
"CIV",
"CMR",
"COD",
"COG",
"COK",
"COL",
"COM",
"CPV",
"CRI",
"CUB",
"CUW",
"CXR",
"CYM",
"CYP",
"CZE",
"DEU",
"DJI",
"DMA",
"DNK",
"DOM",
"DZA",
"ECU",
"EGY",
"ERI",
"ESH",
"ESP",
"EST",
"ETH",
"FIN",
"FJI",
"FLK",
"FRA",
"FRO",
"FSM",
"GAB",
"GBR",
"GEO",
"GGY",
"GHA",
"GIB",
"GIN",
"GLP",
"GMB",
"GNB",
"GNQ",
"GRC",
"GRD",
"GRL",
"GTM",
"GUF",
"GUM",
"GUY",
"HKG",
"HMD",
"HND",
"HRV",
"HTI",
"HUN",
"IDN",
"IMN",
"IND",
"IOT",
"IRL",
"IRN",
"IRQ",
"ISL",
"ISR",
"ITA",
"JAM",
"JEY",
"JOR",
"JPN",
"KAZ",
"KEN",
"KGZ",
"KHM",
"KIR",
"KNA",
"KOR",
"KWT",
"LAO",
"LBN",
"LBR",
"LBY",
"LCA",
"LIE",
"LKA",
"LSO",
"LTU",
"LUX",
"LVA",
"MAC",
"MAF",
"MAR",
"MCO",
"MDA",
"MDG",
"MDV",
"MEX",
"MHL",
"MKD",
"MLI",
"MLT",
"MMR",
"MNE",
"MNG",
"MNP",
"MOZ",
"MRT",
"MSR",
"MTQ",
"MUS",
"MWI",
"MYS",
"MYT",
"NAM",
"NCL",
"NER",
"NFK",
"NGA",
"NIC",
"NIU",
"NLD",
"NOR",
"NPL",
"NRU",
"NZL",
"OMN",
"PAK",
"PAN",
"PCN",
"PER",
"PHL",
"PLW",
"PNG",
"POL",
"PRI",
"PRK",
"PRT",
"PRY",
"PSE",
"PYF",
"QAT",
"REU",
"ROU",
"RUS",
"RWA",
"SAU",
"SDN",
"SEN",
"SGC",
"SGP",
"SHN",
"SJM",
"SLB",
"SLE",
"SLV",
"SMR",
"SOM",
"SPM",
"SRB",
"SSD",
"STP",
"SUR",
"SVK",
"SVN",
"SWE",
"SWZ",
"SXM",
"SYC",
"SYR",
"TCA",
"TCD",
"TGO",
"THA",
"TJK",
"TKL",
"TKM",
"TLS",
"TON",
"TTO",
"TUN",
"TUR",
"TUV",
"TWN",
"TZA",
"UGA",
"UKR",
"UMI",
"URY",
"USA",
"UZB",
"VAT",
"VCT",
"VEN",
"VGB",
"VIR",
"VNM",
"VUT",
"WLF",
"WSM",
"YEM",
"ZAF",
"ZMB",
"ZWE"
]
},
"CurrencyCodeEnum": {
"title": "Currency Code",
"type": "string",
"description": "Three-letter ISO 4217 alphabetical currency code. Supported values are: AUD",
"enum": [
"AUD"
]
}
}
},
"security": [
{
"BasicAuth": []
}
],
"paths": {
"/api/v2/card": {
"put": {
"operationId": "createUpdateToken",
"summary": "Create/Update Token Details",
"description": "Create/Update a token using the OnlinePay Tokenisation Service.\n\n If a token exists for the card already, it is updated with the information in the request. Otherwise, a new token is created for the given card.",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PutDto"
}
}
}
},
"responses": {
"200": {
"description": "Token result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestV2Docs"
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedV2Docs"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenV2Docs"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundV2Docs"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalErrorV2Docs"
}
}
}
}
},
"tags": [
"Token Management"
],
"security": [
{
"BasicAuth": []
}
]
}
}
},
"x-tagGroups": [
{
"name": "ECOMMERCE",
"tags": [
"Ecom Payments",
"Payment Modifications",
"Transaction",
"Secure Card Capture",
"Wallet"
]
},
{
"name": "Loyalty Program Operations",
"tags": [
"Redemption Order"
]
},
{
"name": "Balance Enquiry",
"tags": [
"Balance Enquiry"
]
},
{
"name": "Gift Card Operations",
"tags": [
"Load Card",
"Activate Card"
]
},
{
"name": "Bin",
"tags": [
"Bin"
]
},
{
"name": "Token Management",
"tags": [
"Token Management"
]
},
{
"name": "Health Check",
"tags": [
"Health"
]
}
]
}
```