Vault Learn how to securely store credit card data in the vault

Overview

Payyo's vault uses credit card tokenization, which is the process of creating a non-sensitive substitute (token or alias) of credit card data, which can be used in place of the original credit card.

Payyo supports< two methods of collecting/storing credit cards:

  • API: Integrators submit credit card data using the API (vault.storeCreditCard). Integrators must be PCI-DSS certified.
  • vault.js: Integrators add a JS widget to their website that collects credit card data and submits it to Payyo. Integrators do not have to be PCI-DSS certified.

Store a credit card using the API

To store a credit card in the vault using the API integrators issue a call to vault.storeCreditCard. In return Payyo will respond with an alias_id that can be used as a funding instrument when authorizing a transaction.

Please consider that the CVC may only be stored until after the first authorization. If you want to make multiple charges to the same credit card you should use Payment Plans. It is however also possible to use the credit card alias funding instrument and provide the CVC explicitly.

{
  "jsonrpc": "2.0",
  "method": "vault.storeCreditCard",
  "params": {
    "merchant_id": 1,
    "credit_card": {
      "type": "credit_card",
      "number": "4242424242424242",
      "expires": "2020-04",
      "cvc": "123",
      "holder": "Terry Pratchett"
    }
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "alias_id": "als_123ad44377b0b9735b864360aa89",
    "credit_card_mask": "XXXX XXXX XXXX 4242"
  },
  "id": 1
}

Store a credit card using the vault.js widget

Storing a credit card in the vault using the vault.js widget is a bit more complicated.

  1. Make a vault reservation (vault.makeReservation)
  2. Embed vault.js and configure it using the obtained reservation ID
  3. Trigger credit card collecting JS functionality
  4. Handle/store returned credit card alias

Please note that for each customer the integrator needs to generate a new vault reservation. Vault reservations are not re-usable.

1. Make vault reservation

{
  "jsonrpc": "2.0",
  "method": "vault.makeReservation",
  "params": {
    "merchant_id": 1
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "reservation_id": "vltr_65f50843af7dc87450a930e08814"
  },
  "id": 1
}

2. Embed vault.js

<script src="https://checkout.sandbox.payyo.ch/vault/v1.js"></script>
<script>
  var vault = new TrekkPayVault('vltr_65f50843af7dc87450a930e08814', {
    endpoint: 'https://checkout.sandbox.payyo.ch',
    logo: 'https://example.org/your/logo.png'
  });
</script>

Tip: The endpoint property is not required in a live environment.

3. Store data

You can either use your own HTML form or use Payyo's overlay with form.

3a. Overlay
vault.collectCreditCard().then(function (aliasId) {
  console.log(aliasId);
});
3b. Own Form

You'll make sure on your own that credit card numbers and the expiry date is properly formatted so it will be accepted by the validation of vault.storeCreditCard.

vault.storeCreditCard({
  holder: document.getElementById('cc_holder').value,
  number: document.getElementById('cc_number').value,
  cvc: document.getElementById('cc_cvc').value,
  expires: document.getElementById('cc_expiry').value
}).then(function (aliasId) {
  console.log(aliasId);
});

Use a stored credit card

Using a stored credit card alias is achieved by using the credit_card_alias funding instrument.

{
  "jsonrpc": "2.0",
  "method": "transaction.initiate",
  "params": {
    "merchant_id": 1,
    "merchant_reference": "10000001",
    "currency": "CHF",
    "amount": 3000,
    "return_urls": {
      "success": "https://example.org/success",
      "fail": "https://example.org/fail",
      "abort": "https://example.org/abort"
    },
    "funding_instrument": {
      "type": "credit_card_alias",
      "alias_id": "als_8830e0501465fdc87450a9843af7"
    }
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "tra_30e0881465f50843af7dc87450a9",
    "status": "authorized",
    "next_action": "capture"
  },
  "id": 1
}

In general credit card numbers are stored for 60 months and CVCs for up to 20 months. Please consider that the CVC is only stored until after the first authorization. If you want to make multiple charges to the same credit card you should use Payment Plans or provide the cvc property in the funding_instrument block.

{
  "jsonrpc": "2.0",
  "method": "transaction.initiate",
  "params": {
    ...
    "funding_instrument": {
      "type": "credit_card_alias",
      "alias_id": "als_8830e0501465fdc87450a9843af7",
      "cvc": "123"
    }
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "tra_30e0881465f50843af7dc87450a9",
    "status": "authorized",
    "next_action": "capture"
  },
  "id": 1
}