menu

Payment API

What's on this page

Online Payments / Payment Features / Secure Vault

Vault

The vault 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.

For Merchant or Customer Initiated Transactions involving the storage of sensitive data, it is recommended to use Mandates instead of Vault.

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 Access Token Usage

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

Vault Access Token Expiration

The expiration of the Vault Access 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.

Vault Access Token Initiation

See the Create Token operation for more details.

PCI Vault Access Token

If you are PCI compliant, you can send the sensitive data directly to our vault without the need to redirect the customer to us.

See the Create PCI Vault Access Token operation for more details.

Read a Vault Access Token

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. By default this is turned off, and will only be turned on when requested by the account owner.

See the Query Token operation for more details.

Delete a Vault Access Token

If necessary, you can delete the sensitive data that is stored in our vault. By default, the sensitive data is removed from the vault when the Vault Access Token expires, but you can also choose to delete it before that.

See the Erase Token operation for more details.