Integration with Vault API

This section describes a new approach that enhances your security posture, reduces PCI compliance requirements, and achieves a Zero Data outcome by using the VGS Collect SDK. This solution can be used as a preferred alternative to traditional methods of collecting sensitive data.

VGS provides two APIs for creating aliases (tokenizing data).

• With Vault API v1, you simply configure your UI and call VGSCollect.tokenize().

• Integration with Vault API v2 requires authentication in order to create aliases in your Vault.

Integrate Collect SDK into Your Android Project

To learn how to integrate the VGS Collect SDK and start using it, refer to the How to Integrate the SDK section.

Create an Inbound route

To use the Vault API with the VGS Collect SDK, you must first establish an inbound connection. Go to the Dashboard and create a new Inbound Route, where the Upstream Host should point to the VGS tokenization service:

• API V1: api.sandbox.verygoodvault.com

• API V2:

  • Sandbox: https://<your-vault-id>.sandbox.vault-api.verygoodvault.com

  • Live: https://<your-vault-id>.live.vault-api.verygoodvault.com

Configuring UI Elements

Tokenization cannot be disabled for card-number and card-security-code fields.

XML

<com.verygoodsecurity.vgscollect.widget.VGSCardNumberEditText
    android:id="@+id/cardNumberField"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:fieldName="cardNumber"
    app:aliasFormat="FPE_SIX_T_FOUR"/>

Kotlin

val cardNumberField = findViewById<VGSCardNumberEditText>(R.id.cardNumberField)
cardNumberField.setVaultAliasFormat(VGSVaultAliasFormat.FPE_SIX_T_FOUR)
    

Java

VGSCardNumberEditText cardNumberField = findViewById(R.id.cardNumberField);
cardNumberField.setVaultAliasFormat(VGSVaultAliasFormat.FPE_SIX_T_FOUR);

Tokenization storage

VGS Collect SDK supports PERSISTENT | VOLATILE storages.

Field Type	Default Storage
card-number	PERSISTENT
card-security-code	VOLATILE
card-expiration-date	PERSISTENT
card-holder-name	PERSISTENT
ssn	PERSISTENT
text	PERSISTENT
date-range	PERSISTENT

Change storage using the app:storageType attribute in XML or programmatically via setVaultStorageType(storage: VGSVaultStorageType).

XML

<com.verygoodsecurity.vgscollect.widget.VGSCardNumberEditText
    android:id="@+id/cardNumberField"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:fieldName="cardNumber"
    app:storageType="PERSISTENT"/>

Kotlin

val cardNumberField = findViewById<VGSCardNumberEditText>(R.id.cardNumberField)
cardNumberField.setVaultStorageType(VGSVaultStorageType.PERSISTENT)
    

Java

VGSCardNumberEditText cardNumberField = findViewById(R.id.cardNumberField);
cardNumberField.setVaultStorageType(VGSVaultStorageType.PERSISTENT);

Submit Information

• Vault API v1: Use tokenize(). VGSCollect collects sensitive data from the input fields and stores it in your organization's Vault. See the API v1 documentation for more details.

• Vault API v2: Use createAliases(). This collects the data and stores it in the Vault using Vault API v2. You must also pass an Authorization Token in the request headers. See the API v2 documentation for more details.

Vault API v2

import com.verygoodsecurity.vgscollect.core.Environment
import com.verygoodsecurity.vgscollect.core.VGSCollect
import com.verygoodsecurity.vgscollect.widget.VGSCardNumberEditText
class MainActivity : AppCompatActivity() {
    private lateinit var vgsForm:VGSCollect
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        // Init collect object
        vgsForm = VGSCollect(this, "<VAULT_ID>", Environment.<SANDBOX>)
        // Setup authorization header
        vgsForm.setCustomHeaders(mapOf("Authorization" to "Bearer <TOKEN>"))
        val submitBtn = findViewById<Button>(R.id.submitBtn)
        submitBtn?.setOnClickListener {
            // Make request
            vgsForm.createAliases()
        }
        val cardNumberField = findViewById<VGSCardNumberEditText>(R.id.cardNumberField)
        vgsForm.bindView(cardNumberField)
    }
    override fun onDestroy() {
        vgsForm.onDestroy()
        super.onDestroy()
    }
}

Vault API v1

import com.verygoodsecurity.vgscollect.core.Environment
      import com.verygoodsecurity.vgscollect.core.VGSCollect
      import com.verygoodsecurity.vgscollect.widget.VGSCardNumberEditText
      class MainActivity : AppCompatActivity() {
          private lateinit var vgsForm:VGSCollect
          override fun onCreate(savedInstanceState: Bundle?) {
              super.onCreate(savedInstanceState)
              setContentView(R.layout.activity_main)
              // Init collect object
              vgsForm = VGSCollect(this, "<VAULT_ID>", Environment.<SANDBOX>)
              val submitBtn = findViewById<Button>(R.id.submitBtn)
              submitBtn?.setOnClickListener {
                  // Make request
                  vgsForm.tokenize()
              }\n
              val cardNumberField = findViewById<VGSCardNumberEditText>(R.id.cardNumberField)
              vgsForm.bindView(cardNumberField)
          }
          override fun onDestroy() {
              vgsForm.onDestroy()
              super.onDestroy()
          }
      }

Handling Responses

To handle responses or errors, implement VgsCollectResponseListener:

Kotlin

vgsForm.addOnResponseListeners(object : VgsCollectResponseListener {
    override fun onResponse(response: VGSResponse?) {
        val code = response.code
        val body = response.body
    }
})

Java

vgsForm.addOnResponseListeners(new VgsCollectResponseListener() {
    @Override
    public void onResponse(VGSResponse response) {
        int code = response.getCode();
        String body = response.getBody();
    }
});

Migrating from Vault API v1 to v2

To migrate from Vault API v1 to v2, follow these steps:

• Update your Vault Route to use the new Upstream Host:

  • Sandbox: https://<your-vault-id>.sandbox.vault-api.verygoodvault.com

  • Live: https://<your-vault-id>.live.vault-api.verygoodvault.com.

• Obtain a tokenization authToken from your backend and set it in the VGSCollect headers:

Kotlin

vgsCollect.setCustomHeaders(mapOf("Authorization" to "Bearer <TOKEN>"))

Java

HashMap headers = new HashMap<String, String>();
headers.put("Authorization", "Bearer <TOKEN>");
vgsCollect.setCustomHeaders(headers);

• Replace tokenize() with createAliases() to create aliases.

More Information

You may also want to review the following topics:

• Tracking Changes

• UI Components