API Reference / Vault

Vault

The vault resource can be used to store sensitive data in our vault. This data is stored in an encrypted form. When storing something in the vault, through a process called Vault Enrollment, a Vault Access Token will be returned. The Vault Access Token is used to retrieve the stored information, and allows actions to be performed with the stored information through the VPOS API.

Vault Enrollment

A Vault Access Token is obtained by performing an initial vault enrollment process. The enrollment can be achieved in two ways:

• through a vault request;
• or by using the storeInVault field when performing a payment request (currently only supported for card payments).

The vault enrollment process creates two transactions: a parent vault transaction and a child transaction. The parent vault transaction contains the Vault Access Token and a reference to the child transaction (childReferenceId). The child transaction is created to validate the sensitive information (e.g. for the card vault data type the child transaction is used to validate the card and authenticate the cardholder).

A vault transaction can only have 1 child transaction. When the child transaction reaches a final transaction status such as success or manualintervention, the vault (parent) transaction will be updated with the same status.

Typical vault enrollment flow

The general vault enrollment request flow is:

1. You create a new vault request
2. Redirect the customer to us
3. We ask to enter the data that is to be stored in our vault
4. After the data is entered and stored, we redirect the customer back to your shop
5. You read the transaction to get the status and the Vault Access Token

Status Verification

We do not expose the status of the vault transaction or any of its details to the customer. It is up to you to verify the status of the vault transaction and act accordingly. Webhooks are provided to give you feedback, but this principle remains.

Vault Usage

After obtaining a Vault Access Token, there are three actions that can be taken in the system.

• Initiate a payment using the Vault Access Token
• Retrieve the sensitive data (Pan is returned in plain text if allowed by the settings for your merchant)
• Delete the sensitive data (if allowed by the settings for your merchant)

Vault transaction object

Example

{
  "status" : "success",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Vault description",
  "language" : "eng",
  "method" : "vault",
  "brand" : "bcmc",
  "metadata" : "my custom metadata",
  "reference" : "V1505181754007360.1",
  "created" : 1431964440770,
  "lastUpdate" : 1431964458858,
  "statusFinalDate" : 1431964458858,
  "payUrl" : "https://onlinepayments.ccv.eu/vault/card.html?reference=C1505181754007360.1",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "details" : {
    "expirationDuration" : "P0Y2M1DT0H0M0.000S",
    "vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53"
  }
}

Vault transaction details

The expiration of the vault token is configurable by account. By default this is set to 30 days. In some scenarios you want the default expiration set to the card expiry date. This is also configurable by account.

Example

{
  "dataType" : "card",
  "expirationDuration" : "P0Y2M1DT0H0M0.000S",
  "expirationTimestamp" : 1420106400000,
  "vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53",
  "maskedPan": "xxxxxxxxxxxx4242",
  "expiryDate": "0424",
  "scaToken": false,
  "brand": "visa"
}

Vault Token Object

Vault initiate request

The vault initiate request is used to create a new vault access token.

• Resource: /api/v1/vault/initiate
• Method: POST
• Content-Type: application/json
• Authentication: basic auth
• Parameters

!INFO * The - Required when shipping provided - fields are mandatory if at least one of them is specified when the scaReady flag is set to yes. If all of them are left blank they become optional and are assigned the corresponding billing-value as default.

Example

{
  "dataType" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Vault description",
  "language" : "eng"
}

Vault initiate response

• Status Code: 200
• Content Type: application/json
• Content: Vault Transaction

PCI vault token request

Create a new vault request from a PCI compliant environment.

• Resource: /api/v1/vault/token
• Method: POST
• Content-Type: application/json
• Authentication: basic auth

Example

{
  "merchantOrderReference" : "abcddd",
  "pan" : "6799998900000123456",
  "expiryDate" : "1803"
}

PCI vault token response

• Status Code: 200
• Content Type: application/json
• Content:

Read vault token request

This operation retrieves the sensitive data that was stored in the vault and returns it in plain text. The sensitive data can only be retrieved in plain text when this is allowed for your account. Default this is turned off, and will only be turned on when requested by the account owner.

• Resource: /api/v1/vault/token
• Method: GET
• Content-Type: application/json
• Authentication: basic auth
• Parameters: vaultToken: The vault access token for which the data must be retrieved.

Read vault token response

• Status Code: 200
• Content Type: application/json
• Content: Vault Token

Example of retrieval with non-sensitive data because not allowed by configuration

curl https://api.psp.ccv.eu/api/v1/vault/token?vaultToken=TOKEN1 -u apikey:

  {
    "eraseTimestamp" : 1543155649042,
    "referenceId" : "V181026162049038CB87E190.1",
    "merchantOrderReference" : "321",
    "maskedPan" : "4111XXXXXXXX1111",
    "expiryDate" : "1221",
    "cardholderFirstName" : "John",
    "cardholderLastName" : "Doe"
  }

Delete vault token request

This operation explicitly erases the sensitive data from the vault.

• Resource: /api/v1/vault/token
• Method: DELETE
• Authentication: basic auth
• Parameters

Example

# Delete the vault token using the merchant order reference 321
curl https://api.psp.ccv.eu/api/v1/vault/token?merchantOrderReference=321 -u apikey:

Delete vault token response

• Status Code: 200
• Content Type: application/json