Skip to content
/
Create gateway token

Token Vault service API (1.0.0)

This is an API reference for the Token Vault service, which provides endpoints to create and manage tokens and related cryptographic data.

Download OpenAPI description
token-vault.json
token-vault.yaml
Languages
Servers
Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Create gateway token

Request

Request to create a gateway token, which is used to represent sensitive payment data in a secure and tokenised form.

Path
OwnerIdstring[ 0 .. 20 ] charactersrequired

The unique identifier of the entity owning the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1
OwnerTypestringrequired

The type of entity owning the token (e.g., Referrer, MerchantGroup, Merchant or Site).

Enum"Referrer""MerchantGroup""Merchant""Site"
Example: MerchantGroup
Bodyapplication/json
primaryAccountNumberstringrequired

This refers to 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.

Example: "4111111111111111111"
expiryMonthstringrequired

This is the expiry month [MM] of the card.

Example: "03"
expiryYearstringrequired

This is the expiry year [YYYY] of the card.

Example: "2025"
cardVerificationCodestring or null

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.

Example: "123"
holderNamestringrequired

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.

Example: "Mr John Doe"
curl -i -X POST \
  https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/gateway-tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "primaryAccountNumber": "4111111111111111111",
    "expiryMonth": "03",
    "expiryYear": "2025",
    "cardVerificationCode": "123",
    "holderName": "Mr John Doe"
  }'

Responses

Successful creation of the gateway token

Bodyapplication/json
gatewayTokenIdstring(uuid)

The gateway token Id represents 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 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."

Example: "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341"
maskedPrimaryAccountNumberstring

The masked primary account number (PAN) of the card.

Example: "123456******7890"
fundingSourcestring or null

The funding source type (e.g., Credit Card).

Example: "Credit Card"
Response
application/json
{
  "gatewayTokenId": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341",
  "maskedPrimaryAccountNumber": "123456******7890",
  "fundingSource": "Credit Card"
}

Create scheme token

Request

Request to create a scheme token, representing payment data according to scheme rules.

Path
OwnerIdstring[ 0 .. 20 ] charactersrequired

The unique identifier of the entity owning the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1
OwnerTypestringrequired

The type of entity owning the token (e.g., Referrer, MerchantGroup, Merchant or Site).

Enum"Referrer""MerchantGroup""Merchant""Site"
Example: MerchantGroup
Bodyapplication/json
primaryAccountNumberstringrequired

This refers to 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.

Example: "4111111111111111111"
expiryMonthstringrequired

This is the expiry month [MM] of the card.

Example: "03"
expiryYearstringrequired

This is the expiry year [YYYY] of the card.

Example: "2025"
cardVerificationCodestring or null

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.

Example: "123"
holderNamestringrequired

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.

Example: "Mr John Doe"
curl -i -X POST \
  https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/scheme-tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "primaryAccountNumber": "4111111111111111111",
    "expiryMonth": "03",
    "expiryYear": "2025",
    "cardVerificationCode": "123",
    "holderName": "Mr John Doe"
  }'

Responses

Successful creation of the scheme token

Bodyapplication/json
schemeTokenIdstring(uuid)

The unique scheme token Id generated by PXP. It is used as a reference to extract the schemeTokenNumber.

fundingSourcestring or null

The funding source type (e.g., Bank Account).

Example: "Credit Card"
Response
application/json
{
  "schemeTokenId": "7d87f401-6977-43a4-8e72-8ff457fc8633",
  "fundingSource": "Bank Account"
}

Get scheme token

Request

Request to get a scheme token and its status

Path
OwnerIdstring[ 0 .. 20 ] charactersrequired

The unique identifier of the entity owning the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1
OwnerTypestringrequired

The type of entity owning the token (e.g., Referrer, MerchantGroup, Merchant or Site).

Enum"Referrer""MerchantGroup""Merchant""Site"
Example: MerchantGroup
SchemeTokenIdstringrequired

The unique scheme token ID generated by PXP. It is used as a reference to extract the schemeTokenNumber.

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
curl -i -X GET \
  https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/scheme-tokens/f47ac10b-58cc-4372-a567-0e02b2c3d479

Responses

Successful retrieval of the scheme token

Bodyapplication/json
schemeTokenIdstring(uuid)

The unique scheme token ID generated by PXP. It is used as a reference to extract the schemeTokenNumber.

schemeTokenProviderstring

The name of the scheme token provider.

schemeTokenProcurementStatestring

The procurement state of the scheme token.

externalSchemeTokenIdstring or null

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 utilize various payment processing services.

statusstring or null

The status of the scheme token.

paymentAccountReferencestring or null

The payment account reference associated with the scheme token.

schemeTokenNumberstring or null

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.

expiryMonthstring or null

This is the expiry year [YYYY] of the card.

expiryYearstring or null

This is the expiry month [MM] of the card.

Response
application/json
{
  "schemeTokenId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "schemeTokenProvider": "Visa",
  "schemeTokenProcurementState": "Completed",
  "externalSchemeTokenId": "ext-123456789",
  "status": "Active",
  "paymentAccountReference": "acc-987654321",
  "schemeTokenNumber": "1234567812345678",
  "expiryMonth": "12",
  "expiryYear": "2025"
}

Create scheme token cryptogram

Request

Request to create a scheme token cryptogram, a secure cryptographic representation of the token.

Path
OwnerIdstring[ 0 .. 20 ] charactersrequired

The unique identifier of the entity owning the token (e.g., Referrer, Merchant Group, Merchant, Site).

Example: MERCHANT-GROUP-1
OwnerTypestringrequired

The type of entity owning the token (e.g., Referrer, MerchantGroup, Merchant or Site).

Enum"Referrer""MerchantGroup""Merchant""Site"
Example: MerchantGroup
SchemeTokenIdstringrequired

The unique scheme token Id generated by PXP. It is used as a reference to extract the schemeTokenNumber.

Example: 7d87f401-6977-43a4-8e72-8ff457fc8633
curl -i -X POST \
  https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/scheme-tokens/7d87f401-6977-43a4-8e72-8ff457fc8633/cryptograms

Responses

Successful creation of the cryptogram

Bodyapplication/json
schemeTokenCryptogramstring or null

A unique cryptogram generated during the tokenisation process, utilized for enhancing the security of transaction processing. This cryptogram acts as a secure and unique identifier, akin to the 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.

Example: "E1F53135E559C253"
schemeTokenNumberstring

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.

Example: "4837261112345678"
cryptogramTypestring or null

The type of cryptogram (e.g., 3DSecure).

Example: "3DSecure"
clientPaymentDataIdstring or null

The client payment data identifier associated with the cryptogram.

Example: "abc123"
Response
application/json
{
  "cryptogramType": "3DSecure",
  "clientPaymentDataId": "abc123",
  "schemeTokenCryptogram": "E1F53135E559C253",
  "schemeTokenNumber": "4837261112345678"
}

Store card verification code for card

Request

Request to store the card verification code (CVC) for a card associated with a gateway token.

Path
OwnerIdstring[ 0 .. 20 ] charactersrequired

The unique identifier of the entity owning the token (e.g., Referrer, Merchant Group, Merchant, Site).

Example: MERCHANT-GROUP-1
OwnerTypestringrequired

The type of entity owning the token (e.g., Referrer, MerchantGroup, Merchant or Site).

Enum"Referrer""MerchantGroup""Merchant""Site"
Example: MerchantGroup
GatewayTokenIdstring(uuid)required

The gateway token Id represents 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 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."

Example: 7f46c09d-d1d1-4f94-9a88-6e8ac32e6341
Bodyapplication/json
cardVerificationCodestring[ 3 .. 4 ] charactersrequired

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.

Example: "123"
curl -i -X PUT \
  https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/gateway-tokens/7f46c09d-d1d1-4f94-9a88-6e8ac32e6341/card-verification-code \
  -H 'Content-Type: application/json' \
  -d '{
    "cardVerificationCode": "123"
  }'

Responses

Successful storage of the card verification code

Response
No content
©2025 PXP Financial. PXP Financial Registered Office: The Corn Mill - 1 Roydon Road - Stanstead Abbotts - Hertfordshire - SG12 8XL - United Kingdom Phone +44 2038850598. PXP Financial is Authorised By The Financial Conduct Authority And Our Financial Services Register Number is 504318.