Vault

Store payment credentials for multichannel use.

In the payments industry, tokenization is the act of pseudonymizing any sensitive information for secure storage and communication. Tokenization allows merchants to save customers’ payment details in a PCI DSS compliant manner—so that the next time the same customers make a purchase—they do not need to re-enter their payment credentials again, at most just one or two parameters not allowed to store under the existing security regulation.

Set up your fraud prevention strategy.

Check out our Risk Application and learn how to set up risk rules to detect and block any fraud.

By using tokenization, you place another obstacle between your business and fraudsters. It is not possible to link tokens to the respective payment information and make use of stolen payment credentials.

The Switch Vault allows for the tokenization of any Switch parameter. This means our application is not limited to card details but can go as far as being used to create Instruments for different Charge types without the need for further input. The Vault grants the following functionalities.

PCI DSS-compliant transaction initiation using the same payment credentials in multiple Providers.
Multi-channel use of the same payment instrument (e.g. in-store capture, online refund).
GDPR-compliant means of storing customer data for authentication (e.g. name, email, address, social security number).

The steps involved in Tokenization using the Switch Vault are as follows:

Creating a Vault
Creating an Instrument
Creating a Transaction

Create a Vault

To tokenize a card, firstly you need to create an Instrument, where payment credentials will be securely stored for later use. To achieve that—and as in any other Processing communication flow in the Switch Platform—you will need to create a Charge. You should set the charge_type to vault.

POST `/v2/charges`

Method	Path	Description
POST	Sandbox `https://api-test.switchpayments.com/v2/charges` Production `https://api.switchpayments.com/v2/charges`	Creates a new `charge` for a given transaction.

Request Body Parameters

charge_typeStringRequired

Indicates the payment method that the customer intends to use. The charge_type should be set to vault in this case.

currencyStringRequired

It indicates the currency that will be used by the transaction. Consider ISO 4217 format.

amountNumberRequired

The amount that should be charged to the customer.

events_urlString

It allows you to configure the URL that will be called by the Switch Platform to notify about lifecycle events related to this transaction. Please note that the URL must use HTTPS.

redirect_urlString

Specifies the HTTPS URL to where the users should be redirected after authenticating the transaction on the payment method page. This parameter is only compulsory for payment methods that require user redirection for authentication (e.g.: Paypal).

instrument_paramsJSON Object

Specifies configuration parameters that are passed to the provider when creating the instrument element. These allow you to configure how the funds’ transfer is executed.

metadataJSON Object

It allows you to pass any transaction related data points that may be useful for analysis in the Switch Dashboard.

channelsArray

Gives the ability to specify which Switch channel should be used to process the transaction. Using this parameter you can leverage your business logic to select the channel rather than relying on Switch’s Dynamic Routing. If multiple values are present a fallback mechanism will be used. It gives precedence to the first entries.

CREATE CHARGE FOR VAULT
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '
  {
    	"charge_type" : "vault",
    	"currency" : "EUR",
    	"amount" : 20
    }

The response to this request will have the charge_id that you will have to use in the next step when creating an instrument.

Create an Instrument

POST `/v2/instruments`

Method	Path	Description
POST	Sandbox `https://api-test.switchpayments.com/v2/instruments` Production `https://api.switchpayments.com/v2/instruments`	Creates a new `instrument` for a given transaction.

Request Body Parameters

chargeStringRequired

The unique identifier for the charge element previously created for this transaction.

The remaining fields are dependent on the Payment Method that was previously selected. Below you can find an example for card_onetime.

nameString

The name of the cardholder, as printed on the card.

numberString

The number of the card that will be used to process the payment. It should contain 14 to 19 digits, without spaces.

expiration_monthNumber

Zero padded, two-digit representation of the expiration month for the card.

expiration_yearNumber

Zero padded, two-digit representation of the expiration year for the card.

cvcNumber

The card verification code. It should contain 3 to 4 digits depending on the card brand.

CREATE INSTRUMENT IN VAULT
  $ curl -vX POST https://api-test.switchpayments.com/v2/instruments -u publicKey -d '
  {
    "charge" : "charge_id_from_previous_request",
    "cvc" : "123",
    "expiration_month" : 10,
    "expiration_year" : 2023,
    "number" : "4235647728025682",
    "vat_number": "50284414727",
    "name": "APRO"
    }

Your instrument is now tokenized. As with the charges, this request will have an instrument_id in the response. In the next step, we dive into the actual transaction.

Generate a Vault Transaction

To create the transaction you begin by creating another charge. Notice that this charge now must include more parameters in the body. Whenever you want to use a tokenized instrument you have to insert the instrument_id from the vault in the instrument_params of the charge belonging to the transaction in question.

Method	Path	Description
POST	Sandbox `https://api-test.switchpayments.com/v2/charges` Production `https://api.switchpayments.com/v2/charges`	Creates a new `charge` for a given transaction.

Request Body Parameters

charge_typeStringRequired

Indicates the payment method that the customer intends to use. The charge_type should be set to vault in this case.

currencyStringRequired

It indicates the currency that will be used by the transaction. Consider ISO 4217 format.

amountNumberRequired

The amount that should be charged to the customer.

events_urlString

It allows you to configure the URL that will be called by the Switch Platform to notify about lifecycle events related to this transaction. Please note that the URL must use HTTPS.

redirect_urlString

instrument_paramsJSON Object

Specifies configuration parameters that are passed to the provider when creating the instrument element. These allow you to configure how the funds’ transfer is executed. You should include an instrument for Vault use.

metadataJSON Object

It allows you to pass any transaction related data points that may be useful for analysis in the Switch Dashboard.

channelsArray

CREATE CHARGE USING VAULT
  $ curl -vX POST https://api-test.switchpayments.com/v2/charges -u accountId:privateKey -d '
  {
    "charge_type" : "card_onetime",
  	"currency" : "EUR",
  	"amount" : 20,
     "instrument_params": {
  		"instrument": "vault_instrument_id"
  	}
  }

Similarly to before, the next step is to create an instrument. Yet, now the body will not need further data input, except for the CVC, since tokenized card data is already in use. Any required payment credential not included in the instrument_type vault should be added into the new instrument. In this case, all the necessary credentials have already been stored, the only one missing is the CVV since it cannot be replicated due to PCI DSS regulations.

Method	Path	Description
POST	Sandbox `https://api-test.switchpayments.com/v2/instruments` Production `https://api.switchpayments.com/v2/instruments`	Creates a new `instrument` for a given transaction.

Request Body Parameters

chargeStringRequired

The unique identifier for the charge element previously created for this transaction.

cvcNumber

The card verification code. It should contain 3 to 4 digits depending on the card brand.

CREATE INSTRUMENT USING VAULT
  $ curl -vX POST https://api-test.switchpayments.com/v2/instruments -u publicKey -d '
  {
    "charge" : "charge_id_from_previous_request",
    "cvc" : "123"
  }

Next Steps

Learn more about the valuable insights you can extract from your transaction by using our Analytics Application.

Vault

Store payment credentials for multichannel use.

Set up your fraud prevention strategy.

Create a Vault

POST /v2/charges

Request Body Parameters

Create an Instrument

POST /v2/instruments

Request Body Parameters

Generate a Vault Transaction

Request Body Parameters

Request Body Parameters

Next Steps

POST `/v2/charges`

POST `/v2/instruments`