{ "openapi": "3.0.1", "info": { "title": "Token Vault service API", "description": "This is an API reference for the Token Vault service, which provides endpoints to create and manage tokens and related cryptographic data.", "version": "1.0.0" }, "servers": [ { "url": "https://api-services.pxp.io/api/v1", "description": "Production environment" }, { "url": "https://api-services.test.pxp.io/api/v1", "description": "Sandbox environment" } ], "paths": { "/token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens": { "post": { "x-hideReplay": true, "summary": "Create gateway token", "description": "Request to create a gateway token, which is used to represent sensitive payment data in a secure and tokenised form.", "operationId": "create-gateway-token", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTokenRequest" } } } }, "responses": { "200": { "description": "Successful creation of the gateway token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/gatewayTokenResponse" }, "examples": { "Create Gateway Token Response": { "value": { "gatewayTokenId": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341", "maskedPrimaryAccountNumber": "123456******7890", "fundingSource": "Credit" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens": { "post": { "x-hideReplay": true, "summary": "Create scheme token", "description": "Request to create a scheme token, representing payment data according to scheme rules.", "operationId": "create-scheme-token", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createTokenRequest" } } } }, "responses": { "200": { "description": "Successful creation of the scheme token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createSchemeTokenResponse" }, "examples": { "Create Scheme Token Response": { "value": { "schemeTokenId": "7d87f401-6977-43a4-8e72-8ff457fc8633", "fundingSource": "Debit" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens/{schemeTokenId}": { "get": { "x-hideReplay": true, "summary": "Get scheme token", "description": "Request to get a scheme token and its status", "operationId": "get-scheme-token", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/schemeTokenId" } ], "responses": { "200": { "description": "Successful retrieval of the scheme token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemeTokenResponse" }, "examples": { "Get Scheme Token Response": { "value": { "schemeTokenId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "schemeTokenProvider": "Visa", "schemeTokenProcurementState": "Completed", "externalSchemeTokenId": "ext-123456789", "status": "Active", "paymentAccountReference": "acc-987654321", "schemeTokenNumber": "1234567812345678", "expiryMonth": "12", "expiryYear": "2025" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens/{schemeTokenId}/cryptograms": { "post": { "x-hideReplay": true, "summary": "Create scheme token cryptogram", "description": "Request to create a scheme token cryptogram, a secure cryptographic representation of the token.", "operationId": "create-scheme-token-cryptogram", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/schemeTokenId" } ], "responses": { "200": { "description": "Successful creation of the cryptogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cryptogramResponse" }, "examples": { "Create Cryptogram Response": { "value": { "cryptogramType": "3DSecure", "clientPaymentDataId": "abc123", "schemeTokenCryptogram": "E1F53135E559C253", "schemeTokenNumber": "4837261112345678" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-data": { "get": { "x-hideReplay": true, "summary": "Get masked card data related to gateway token", "description": "Request to get card data related to the gateway token. The returned sensitive data is unencrypted but masked to ensure security.", "operationId": "get-masked-card-related-to-gateway-token", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/gatewayTokenId" } ], "responses": { "200": { "description": "Successful retrieval of masked card data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/maskedGatewayTokenCardDataResponse" }, "examples": { "Get Gateway Token Card Data Response": { "value": { "maskedPrimaryAccountNumber": "123456******7890", "expiryMonth": "12", "expiryYear": "2025", "holderName": "Mr John Doe", "fundingSource": "Credit" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-data/encrypted": { "get": { "x-hideReplay": true, "summary": "Get encrypted card data related to gateway token", "description": "Request to get card data related to the gateway token. The returned sensitive data is encrypted for enhanced security.", "operationId": "get-encrypted-card-related-to-gateway-token", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/gatewayTokenId" } ], "responses": { "200": { "description": "Successful retrieval of encrypted card data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/encryptedGatewayTokenCardDataResponse" }, "examples": { "Get Gateway Token Encrypted Card Data Response": { "value": { "encryptedPrimaryAccountNumber": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==", "expiryMonth": "12", "expiryYear": "2025", "encryptedHolderName": "Sm9obiBEb2U=", "fundingSource": "Credit" } } } } } }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/card-verification-code": { "put": { "x-hideReplay": true, "summary": "Store card verification code for card", "description": "Request to store the card verification code (CVC) for a card associated with a gateway token.", "operationId": "store-security-code", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/gatewayTokenId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addCardVerificationCodeRequest" } } } }, "responses": { "200": { "description": "Successful storage of the card verification code" }, "400": { "description": "Bad request due to invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "422": { "description": "Unprocessable entity due to semantic errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/gateway-tokens/{gatewayTokenId}/user-consents/{merchantShopperId}": { "delete": { "x-hideReplay": true, "summary": "Revoke gateway token consent", "description": "Revokes user consent for a gateway token and shopper. Consent is only available if you included an optional `customerConsent` when you created the token.\n\nA `404` usually means that there's no consent for this token and shopper, the `merchantShopperId` doesn't match exactly, or the token isn't in this vault.", "operationId": "revoke-gateway-token-consent", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/gatewayTokenId" }, { "$ref": "#/components/parameters/merchantShopperId" } ], "responses": { "204": { "description": "No content. Consent has been revoked. The gateway token stays in the vault but can't be used until consent is granted again." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Not found. No matching consent was found for this token and shopper in the vault.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } }, "/token-vault/{ownerType}/{ownerId}/vaults/scheme-tokens/{schemeTokenId}/user-consents/{merchantShopperId}": { "delete": { "x-hideReplay": true, "summary": "Revoke scheme token consent", "description": "Revokes user consent for a scheme token and shopper. Consent is only available if you included an optional `customerConsent` when you created the token.\n\nA `404` usually means that there's no consent for this token and shopper, the `merchantShopperId` doesn't match exactly, or the token isn't in this vault.", "operationId": "revoke-scheme-token-consent", "parameters": [ { "$ref": "#/components/parameters/ownerId" }, { "$ref": "#/components/parameters/ownerType" }, { "$ref": "#/components/parameters/schemeTokenId" }, { "$ref": "#/components/parameters/merchantShopperId" } ], "responses": { "204": { "description": "No content. Consent has been revoked." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } }, "404": { "description": "Not found. No matching consent was found for this token and shopper in the vault.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponse" } } } } } } } }, "components": { "schemas": { "fundingSource": { "description": "The funding source type of the card.", "type": "string", "nullable": true, "enum": [ "Credit", "Debit", "Prepaid" ], "example": "Credit" }, "createTokenRequest": { "type": "object", "required": [ "card" ], "properties": { "card": { "$ref": "#/components/schemas/card" }, "customerConsent": { "$ref": "#/components/schemas/customerConsent" } }, "additionalProperties": false }, "addCardVerificationCodeRequest": { "required": [ "cardVerificationCode" ], "type": "object", "properties": { "cardVerificationCode": { "description": "Represents the Card Verification Code (CVC) associated with the payment card, a security feature for transactions where the card is not physically present. The security code is typically a 3 or 4 digit number found on the card, used to verify that the cardholder is in possession of the card during non-face-to-face transactions.", "maxLength": 4, "minLength": 3, "example": "123", "type": "string" } }, "additionalProperties": false }, "gatewayTokenResponse": { "type": "object", "properties": { "gatewayTokenId": { "description": "A securely stored token that corresponds to a previously saved payment card. This token is generated and maintained by PXP to facilitate recurring transactions or transactions using stored card details, ensuring enhanced security and convenience. When a transaction is performed with a saved card, this gateway token ID should be provided instead of the full card details. This approach enhances security by reducing the exposure of sensitive card information and simplifies the transaction process for returning customers.", "type": "string", "example": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341", "format": "uuid" }, "maskedPrimaryAccountNumber": { "description": "The masked primary account number (PAN) of the card.", "type": "string", "example": "123456******7890" }, "fundingSource": { "$ref": "#/components/schemas/fundingSource" } }, "additionalProperties": false }, "createSchemeTokenResponse": { "type": "object", "properties": { "schemeTokenId": { "description": "The unique scheme token ID generated by PXP. It is used as a reference to extract the schemeTokenNumber.", "type": "string", "format": "uuid" }, "fundingSource": { "$ref": "#/components/schemas/fundingSource" } }, "additionalProperties": false }, "cryptogramResponse": { "type": "object", "properties": { "schemeTokenCryptogram": { "description": "A unique cryptogram generated during the tokenisation process, used to enhance the security of transaction processing. This cryptogram acts as a secure and unique identifier, akin to the Token Authentication Verification Value (TAVV), ensuring that each transaction is authenticated and verified without directly using sensitive card details. It plays a crucial role in the secure electronic payment ecosystem, especially in tokenised transactions, by providing an additional layer of security and authentication.", "type": "string", "example": "E1F53135E559C253", "nullable": true }, "schemeTokenNumber": { "description": "The scheme token number represents a scheme token issued by Visa or Mastercard, used for subsequent transaction processing. This token enhances security and facilitates recurring transactions, providing a secure and efficient alternative to sharing sensitive card details.", "type": "string", "example": "4837261112345678" }, "cryptogramType": { "description": "The type of cryptogram (e.g., 3DSecure).", "type": "string", "example": "3DSecure", "nullable": true }, "clientPaymentDataId": { "description": "The client payment data identifier associated with the cryptogram.", "type": "string", "nullable": true, "example": "abc123" } }, "additionalProperties": false }, "schemeTokenResponse": { "type": "object", "properties": { "schemeTokenId": { "type": "string", "format": "uuid", "description": "The unique scheme token ID generated by PXP. It is used as a reference to extract the schemeTokenNumber." }, "schemeTokenProvider": { "type": "string", "description": "The name of the scheme token provider." }, "schemeTokenProcurementState": { "type": "string", "description": "The procurement state of the scheme token." }, "externalSchemeTokenId": { "type": "string", "nullable": true, "description": "A unique identifier token provided by the external payment scheme. This token allows merchants to process payments through different payment service providers (PSPs) or transaction service providers (TSPs). The token facilitates interoperability between different PSPs, enabling merchants to seamlessly integrate with and use various payment processing services." }, "status": { "type": "string", "nullable": true, "description": "The status of the scheme token." }, "paymentAccountReference": { "type": "string", "nullable": true, "description": "The payment account reference associated with the scheme token." }, "schemeTokenNumber": { "type": "string", "nullable": true, "description": "The scheme token number represents a scheme token issued by Visa or Mastercard, used for subsequent transaction processing. This token enhances security and facilitates recurring transactions, providing a secure and efficient alternative to sharing sensitive card details." }, "expiryMonth": { "allOf": [ { "$ref": "#/components/schemas/expiryMonth" }, { "type": "string", "nullable": true } ] }, "expiryYear": { "allOf": [ { "$ref": "#/components/schemas/expiryYear" }, { "type": "string", "nullable": true } ] } } }, "maskedGatewayTokenCardDataResponse": { "type": "object", "properties": { "maskedPrimaryAccountNumber": { "description": "The masked primary account number (PAN) of the card.", "type": "string", "example": "123456******7890" }, "expiryMonth": { "$ref": "#/components/schemas/expiryMonth" }, "expiryYear": { "$ref": "#/components/schemas/expiryYear" }, "holderName": { "description": "The Cardholder Name represents the full name of the individual who owns the payment card. This name is printed on the physical card and is used for verifying the cardholder's identity during transactions. The cardholder name is a vital component for transaction processing, especially in cases of card-not-present transactions like online purchases. It should be treated with confidentiality to safeguard the cardholder's privacy and prevent potential misuse.", "type": "string", "example": "Mr John Doe" }, "fundingSource": { "$ref": "#/components/schemas/fundingSource" } }, "additionalProperties": false }, "encryptedGatewayTokenCardDataResponse": { "type": "object", "properties": { "encryptedPrimaryAccountNumber": { "description": "The encrypted primary account number (PAN) of the card.", "type": "string", "format": "byte", "example": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" }, "expiryMonth": { "$ref": "#/components/schemas/expiryMonth" }, "expiryYear": { "$ref": "#/components/schemas/expiryYear" }, "encryptedHolderName": { "description": "The encrypted name of the cardholder.", "type": "string", "example": "Sm9obiBEb2U=", "format": "byte" }, "fundingSource": { "$ref": "#/components/schemas/fundingSource" } }, "additionalProperties": false }, "card": { "type": "object", "description": "Details about the card for tokenisation.", "required": [ "primaryAccountNumber", "expiryMonth", "expiryYear", "holderName" ], "properties": { "primaryAccountNumber": { "description": "The unique number assigned to a payment card, such as a credit or debit card. This number typically contains 16 digits, structured in a specific format to indicate the card network, issuing bank, and account number.", "type": "string", "example": "4111111111111111", "minLength": 13, "maxLength": 19, "pattern": "^[0-9]+$" }, "expiryMonth": { "$ref": "#/components/schemas/expiryMonth" }, "expiryYear": { "$ref": "#/components/schemas/expiryYear" }, "holderName": { "description": "The full name of the individual who owns the payment card. This name is printed on the physical card and is used for verifying the cardholder's identity during transactions. The cardholder name is a vital component for transaction processing, especially in cases of card-not-present transactions like online purchases. It should be treated with confidentiality to safeguard the cardholder's privacy and prevent potential misuse.", "type": "string", "example": "Mr John Doe", "minLength": 2, "maxLength": 45 }, "cardVerificationCode": { "description": "The Card Verification Code (CVC) associated with the payment card, a security feature for transactions where the card is not physically present. The security code is typically a 3 or 4 digit number found on the card, used to verify that the cardholder is in possession of the card during non-face-to-face transactions.", "type": "string", "example": "123", "nullable": true, "minLength": 3, "maxLength": 4, "pattern": "^[0-9]{3,4}$" } }, "additionalProperties": false }, "customerConsent": { "type": "object", "description": "Optional details about the customer's consent to store their payment card. Include this when you create the token if you might need to revoke consent later.", "properties": { "hasCustomerConsent": { "type": "boolean", "description": "Whether the customer has consented to storing their payment card details.", "example": true, "nullable": true }, "merchantId": { "type": "string", "description": "The merchant identifier associated with the consent.", "maxLength": 100, "example": "MERCHANT-001", "nullable": true }, "merchantShopperId": { "type": "string", "description": "Your unique identifier for the shopper. Use the same value when you revoke consent. Matching is case-sensitive and doesn't ignore spaces.", "maxLength": 100, "example": "6152", "nullable": true } }, "additionalProperties": false }, "expiryMonth": { "description": "The expiry month of the card, as a number from 1 to 12. Typically zero-padded to two digits (for example, `03`).", "type": "string", "example": "03", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]+$" }, "expiryYear": { "description": "The expiry year of the card (`YYYY`).", "type": "string", "example": "2025", "minLength": 4, "maxLength": 4, "pattern": "^[0-9]{4}$" }, "errorResponse": { "type": "object", "description": "Standard error response structure.", "properties": { "correlationId": { "type": "string", "description": "The unique identifier for this error response. Include it when contacting PXP support.", "example": "81f32b80-2ba0-4430-8ecd-0b559274ba9c" }, "details": { "type": "array", "items": {}, "description": "Additional details about the error." }, "errorCode": { "type": "string", "description": "The error code returned for the operation.", "example": "INVALID_REQUEST" }, "errorReason": { "type": "string", "description": "The error reason returned for the operation.", "example": "The request parameters are invalid." } } } }, "parameters": { "ownerType": { "name": "ownerType", "in": "path", "description": "The type of entity that owns the token vault. Use with `ownerId` to identify which vault to use.", "required": true, "example": "MerchantGroup", "style": "simple", "schema": { "enum": [ "Referrer", "MerchantGroup", "Merchant", "Site" ], "type": "string" } }, "ownerId": { "name": "ownerId", "in": "path", "description": "The identifier of the vault owner. This must match the owner type. For example, provide your merchant group ID when `ownerType` is `MerchantGroup`.", "required": true, "example": "MERCHANT-GROUP-1", "style": "simple", "schema": { "maxLength": 20, "minLength": 0, "type": "string" } }, "gatewayTokenId": { "name": "gatewayTokenId", "in": "path", "description": "The gateway token ID.", "required": true, "style": "simple", "example": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341", "schema": { "type": "string", "format": "uuid" } }, "schemeTokenId": { "name": "schemeTokenId", "in": "path", "description": "The scheme token ID.", "required": true, "style": "simple", "example": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341", "schema": { "type": "string", "format": "uuid" } }, "merchantShopperId": { "name": "merchantShopperId", "in": "path", "description": "Your unique identifier for the shopper. Use the same value you stored in `customerConsent` when you created the token. Matching is case-sensitive and doesn't ignore spaces.", "required": true, "style": "simple", "example": "6152", "schema": { "type": "string", "maxLength": 100 } } } } }