Token Vault service API

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 that owns the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1

ownerTypestringrequired

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

Enum"Referrer""MerchantGroup""Merchant""Site"

Example: MerchantGroup

Bodyapplication/json

primaryAccountNumberstring(primaryAccountNumber)required

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"

expiryMonthstring(expiryMonth)[ 1 .. 2 ] charactersrequired

The expiry month of the card.

Example: "03"

expiryYearstring(expiryYear)= 4 charactersrequired

The expiry year of the card.

Example: "2027"

cardVerificationCodestring or null(cardVerificationCode)[ 3 .. 4 ] characters

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"

holderNamestring(holderName)required

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": "2027",
    "cardVerificationCode": "123",
    "holderName": "Mr John Doe"
  }'

Responses

Successful creation of the gateway token

Bodyapplication/json

gatewayTokenIdstring(uuid)(gatewayTokenId)

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(maskedPrimaryAccountNumber)

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

Example: "123456******7890"

fundingSourcestring or null(fundingSource)

The funding source type.

Example: "Credit"

Response

application/json

{
  "gatewayTokenId": "7f46c09d-d1d1-4f94-9a88-6e8ac32e6341",
  "maskedPrimaryAccountNumber": "123456******7890",
  "fundingSource": "Credit"
}

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 that owns the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1

ownerTypestringrequired

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

Enum"Referrer""MerchantGroup""Merchant""Site"

Example: MerchantGroup

Bodyapplication/json

primaryAccountNumberstring(primaryAccountNumber)required

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"

expiryMonthstring(expiryMonth)[ 1 .. 2 ] charactersrequired

The expiry month of the card.

Example: "03"

expiryYearstring(expiryYear)= 4 charactersrequired

The expiry year of the card.

Example: "2027"

cardVerificationCodestring or null(cardVerificationCode)[ 3 .. 4 ] characters

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"

holderNamestring(holderName)required

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": "2027",
    "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(fundingSource)

The funding source type.

Example: "Credit"

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 that owns the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1

ownerTypestringrequired

The type of entity that owns 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.

curl -i -X GET \
  'https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/scheme-tokens/{schemeTokenId}'

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 use 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(expiryMonth)[ 1 .. 2 ] characters

The expiry month of the card.

Example: "03"

expiryYearstring(expiryYear)= 4 characters

The expiry year of the card.

Example: "2027"

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 that owns the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1

ownerTypestringrequired

The type of entity that owns 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.

curl -i -X POST \
  'https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/scheme-tokens/{schemeTokenId}/cryptograms'

Responses

Successful creation of the cryptogram

Bodyapplication/json

schemeTokenCryptogramstring or null(schemeTokenCryptogram)

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 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"
}

Get masked card data related to gateway token

Request

Request to get card data related to the gateway token. The returned sensitive data is unencrypted but masked to ensure security.

Path

ownerIdstring[ 0 .. 20 ] charactersrequired

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

Example: MERCHANT-GROUP-1

ownerTypestringrequired

The type of entity that owns 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.

curl -i -X GET \
  'https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/gateway-tokens/{gatewayTokenId}/card-data'

Responses

Successful retrieval of masked card data

Bodyapplication/json

maskedPrimaryAccountNumberstring(maskedPrimaryAccountNumber)

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

Example: "123456******7890"

expiryMonthstring(expiryMonth)[ 1 .. 2 ] characters

The expiry month of the card.

Example: "03"

expiryYearstring(expiryYear)= 4 characters

The expiry year of the card.

Example: "2027"

holderNamestring(holderName)

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"

fundingSourcestring or null(fundingSource)

The funding source type.

Example: "Credit"

Response

application/json

{
  "maskedPrimaryAccountNumber": "123456******7890",
  "expiryMonth": "12",
  "expiryYear": "2025",
  "holderName": "Mr John Doe",
  "fundingSource": "Credit"
}

Get encrypted card data related to gateway token

Request

Request to get card data related to the gateway token. The returned sensitive data is encrypted for enhanced security.

Path

ownerIdstring[ 0 .. 20 ] charactersrequired

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

Example: MERCHANT-GROUP-1

ownerTypestringrequired

The type of entity that owns 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.

curl -i -X GET \
  'https://api-services.pxp.io/api/v1/token-vault/MerchantGroup/MERCHANT-GROUP-1/vaults/gateway-tokens/{gatewayTokenId}/card-data/encrypted'

Responses

Successful retrieval of encrypted card data

Bodyapplication/json

encryptedPrimaryAccountNumberstring(byte)(encryptedPrimaryAccountNumber)

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

Example: "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

expiryMonthstring(expiryMonth)[ 1 .. 2 ] characters

The expiry month of the card.

Example: "03"

expiryYearstring(expiryYear)= 4 characters

The expiry year of the card.

Example: "2027"

encryptedHolderNamestring(byte)(encryptedHolderName)

The encrypted name of the cardholder.

Example: "Sm9obiBEb2U="

fundingSourcestring or null(fundingSource)

The funding source type.

Example: "Credit"

Response

application/json

{
  "encryptedPrimaryAccountNumber": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
  "expiryMonth": "12",
  "expiryYear": "2025",
  "encryptedHolderName": "Sm9obiBEb2U=",
  "fundingSource": "Credit"
}

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 that owns the token (e.g., Referrer, Merchant Group, Merchant or Site).

Example: MERCHANT-GROUP-1

ownerTypestringrequired

The type of entity that owns 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.

Bodyapplication/json

cardVerificationCodestring or null(cardVerificationCode)[ 3 .. 4 ] charactersrequired

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/{gatewayTokenId}/card-verification-code' \
  -H 'Content-Type: application/json' \
  -d '{
    "cardVerificationCode": "123"
  }'

Responses

Successful storage of the card verification code

Response

No content

Token Vault service API (1.0.0)

Create gateway token

Request

Responses

Was this helpful?

Create scheme token

Request

Responses

Was this helpful?

Get scheme token

Request

Responses

Was this helpful?

Create scheme token cryptogram

Request

Responses

Was this helpful?

Was this helpful?

Was this helpful?

Store card verification code for card

Request

Responses

Was this helpful?