Guides

Sending Card Data

Suggest Edits

Overview

There are a few options for how you can send card data to Knot when integrating the CardSwitcher product. The first option is to send the card data in JSON to a secure endpoint controlled by a vault provider, the second option is to send the card data encrypted in a JWE, and the third is to rely on the Knot <> Unit integration.

No option is more or less secure than the other, all maintain strict handling of the card data to comply with PCI guidelines, and all are valid options for sending card data to Knot.

Send Data to Secure Vault Provider

This option is often chosen by those integrating with Knot that already have a vault set up with a PCI-compliant vendor such as Very Good Security (VGS) or Basis Theory.

  1. Set up a route to Knot's Switch Card endpoint from the vault that stores card data at your PCI-compliant vendor.
  2. When you receive the authenticated webhook, make a request to the vault.
  3. The vault provider will send the necessary card data to Knot's Switch Card endpoint in JSON.
  4. Knot receives the card data to the aforementioned endpoint. This endpoint is controlled by Knot's PCI-compliant vendor which stores the data and proxies it to Knot via an alias. Card data is never processed or stored outside PCI-compliant vendor environments.

After card data is used for a card switch, it is explicitly deleted from the PCI-compliant vendor's vault within milliseconds.

You can also request to enable Mutual Transport Layer Security (mTLS) for the Switch Card endpoint as an additional security measure if desired.

VGS 1-Click Route Setup

Knot partners with VGS (a PCI-compliant vendor) to streamline the process of sending card data in a PCI-compliant manner as part of your integration with Knot.

Within your VGS account online, you can setup an outbound route to Knot's Switch Card endpoint. VGS specifies how to set up an outbound connection to a 3rd party (in this case Knot) here. Doing so will allow you to automatically route card data stored in your VGS vault to Knot. To make this process even easier, in the "Addons" section of your vault in your VGS account online, you will find a set of "route templates." You can search for and select the "KnotAPI" route template to get started.

Send Encrypted Data Directly to Knot

In this option, you can encrypt the JSON payload of card data in a JWE format prior to sending it to Knot.

  1. Get a JWE public key from Knot's Retrieve JWK endpoint.
  2. Encrypt the JSON string payload of the card data with the JWE public key (referenced here).
  3. Send the encrypted payload to Switch Card (JWE).
  4. Knot sends the encrypted data (the JWE) to a PCI-compliant vendor's environment.
  5. Knot receives an alias associated with the encrypted card data.

Like in option 1, card data is never processed or stored outside PCI-compliant vendor environments. Furthermore, after card data is used for a card switch, it is explicitly deleted from the PCI-compliant vendor's vault within milliseconds.

VGS JWE Encryption

If you already have a vault set up with Very Good Security (VGS), you can manipulate the payload and send the JWE directly from your VGS vault via an outbound route to the Switch Card (JWE) endpoint. Below is an example of how to implement a JWE encryption on VGS:

load("@stdlib//json","json")
load("@vendor//jose/jwe", jwe="jwe")
load("@vendor//jose/jwk", jwk="jwk")
load("@vendor//jose/utils", base64url_encode="base64url_encode")
load("@vendor//jose/constants", ALGORITHMS="ALGORITHMS")

def process(input_http, ctx):
    # Parse to JSON
    body = json.loads(input.body())
    
    # Set encryption key
    encryption_key = bytes('3800321e74ff4334bbb8feb815195592', encoding='utf-8')
    
    # Encrypt the body using JWE
    data = jwe.encrypt(json.dumps(body), encryption_key, algorithm='A256KW', encryption='A256GCM')
    
    # Replace the original body with the encrypted data
    encrypted_body = {"encrypted": data}
    input.set_body(json.dumps(encrypted_body))
    
    return input

Knot <> Unit Integration

With this option, you can allow Knot to retrieve the card data directly from Unit if you use their software as your issuer processor. More on this integration here.

Updated 3 days ago