API Reference

Send card

The/card endpoint triggers a merchant switch. This endpoint should be called after receiving the AUTHENTICATEDwebhook.

💡
Important!
The base URL of the /card endpoint contains the secure subdomain. This is needed to send any card information.
You'll have up to 15 seconds to send this request after receiving the AUTHENTICATED webhook.

Endpoint

POST https://secure.production.knotapi.com/card

Request fields

Field Name	Type	Description
task_id	required, number	The `task_id` property available in the `AUTHENTICATED` webhook.
user.name.first_name	required, string	A string with at least one non-whitespace character, with a max length of 100 characters.
user.name.last_name	required, string	A string with at least one non-whitespace character, with a max length of 100 characters.
user.phone_number	required, string	The user's phone number in E.164 format.
user.address.street	required, string	The primary street portion of an address. If the user has submitted their address, this field will always be filled.
user.address.street2	string	Extra street information, like an apartment or suite number.
user.address.city	required, string	City from the end user’s address.
user.address.region	required, string	An ISO 3166-2 sub-division code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
user.address.postal_code	required, string	The postal code for the associated address. Between 2 and 10 alphanumeric characters.
user.address.country	required, string	Valid, capitalized, two-letter ISO code representing the country of this object. It must be in ISO 3166-1 alpha-2 form.
card.number	required, string	A valid card number without spaces or hyphens.
card.expiration	required, string	A string with the card expiration in `MM/YYYY` or `MM/YY` format. (e.g. 08/2027)
card.cvv	required, string	A Valid security code, between 3 and 4 digits.

curl -X POST 'https://secure.production.knotapi.com/card' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "task_id": 408321,
    "user": {
      "name": {
        "first_name": "John",
        "last_name": "Smith"
      },
      "address": {
        "street": "348 WEST 57TH STREET",
        "street2": "#367",
        "city": "NEW YORK",
        "region": "NY",
        "postal_code": "10019",
        "country": "US"
      },
      "phone_number": "+14155550123"
    },
    "card": {
      "number": "4242424242424242",
      "expiration": "08/2025",
      "cvv": "012"
    }
  }'

package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

func main() {
	url := "https://secure.development.knotapi.com/card"

	data := map[string]interface{}{
		"task_id":    408321,
		"user": map[string]interface{}{
			"name": map[string]string{
				"first_name": "John",
				"last_name":  "Smith",
			},
			"address": map[string]interface{}{
				"street":      "348 WEST 57TH STREET",
				"street2":     "#367",
				"city":        "NEW YORK",
				"region":      "NY",
				"postal_code": "10019",
				"country":     "US",
			},
			"phone_number": "+14155550123",
		},
		"card": map[string]string{
			"number":     "4242424242424242",
			"expiration": "08/2025",
			"cvv":        "012",
		},
	}

	jsonData, err := json.Marshal(data)
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	if err != nil {
		panic(err)
	}

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Knot-Version", "2.0")

	username := "bd271e95-14e6-47ab-9f4f-225898f69183"
	password := "cf819749c0574616ba93b5935b8cf108"
	auth := base64.StdEncoding.EncodeToString([]byte(username + ":" + password))
	req.Header.Add("Authorization", "Basic "+auth)

	client := &http.Client{Timeout: 10 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

const axios = require('axios');

const url = 'https://secure.development.knotapi.com/card';

const headers = {
  'Knot-Version': '2.0',
};

const data = {
  task_id: 408321,
  user: {
    name: {
      first_name: 'John',
      last_name: 'Smith',
    },
    address: {
      street: '348 WEST 57TH STREET',
      street2: '#367',
      city: 'NEW YORK',
      region: 'NY',
      postal_code: '10019',
      country: 'US',
    },
    phone_number: '+14155550123',
  },
  card: {
    number: '4242424242424242',
    expiration: '08/2025',
    cvv: '012',
  },
};

axios.post(url, data, {
  headers,
  auth: {
    username: 'bd271e95-14e6-47ab-9f4f-225898f69183',
    password: 'cf819749c0574616ba93b5935b8cf108',
  },
})
  .then(response => {
    console.log('HTTP Response data:', response.data);
  })
  .catch(console.error);

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$url = "https://secure.development.knotapi.com/card";

$headers = [
    "Content-Type" => "application/json",
    "Knot-Version" => "2.0",
];

$data = [
    "task_id" => 408321,
    "user" => [
        "name" => [
            "first_name" => "John",
            "last_name" => "Smith",
        ],
        "address" => [
            "street" => "348 WEST 57TH STREET",
            "street2" => "#367",
            "city" => "NEW YORK",
            "region" => "NY",
            "postal_code" => "10019",
            "country" => "US",
        ],
        "phone_number" => "+14155550123",
    ],
    "card" => [
        "number" => "4242424242424242",
        "expiration" => "08/2025",
        "cvv" => "012",
    ],
];

try {
    $response = $client->post($url, [
        'headers' => $headers,
        'json' => $data,
        'auth' => ['bd271e95-14e6-47ab-9f4f-225898f69183', 'cf819749c0574616ba93b5935b8cf108']
    ]);

    echo "\nResponse Body: " . $response->getBody();
} catch (\GuzzleHttp\Exception\RequestException $e) {
    echo "HTTP request failed. " . $e->getMessage();
}

import requests

url = "https://secure.development.knotapi.com/card"

headers = {
    "Content-Type": "application/json",
    "Knot-Version": "2.0"
}

data = {
    "task_id": 408321,
    "user": {
        "name": {
            "first_name": "John",
            "last_name": "Smith"
        },
        "address": {
            "street": "348 WEST 57TH STREET",
            "street2": "#367",
            "city": "NEW YORK",
            "region": "NY",
            "postal_code": "10019",
            "country": "US"
        },
        "phone_number": "+14155550123"
    },
    "card": {
        "number": "4242424242424242",
        "expiration": "08/2025",
        "cvv": "012"
    }
}

response = requests.post(url, json=data, headers=headers, auth=('bd271e95-14e6-47ab-9f4f-225898f69183', 'cf819749c0574616ba93b5935b8cf108'))

print("Response Body:", response.text)

Response Status Codes

200: Success

The request was successful.

{
    "message": "Success"
}

400: Client Errors

This group of status codes indicates that there was an error due to the request sent by the client.

Examples:

Invalid Input:

{
    "error_type": "INVALID_REQUEST",
    "error_code": "INVALID_FIELD",
    "error_message": "the user.name.first name field is required",
    "display_message": null
}

Handling 3xx, 4xx, 5xx Status Codes

3xx (Redirection): Clients should follow the redirect or adjust the request accordingly.

4xx (Client Errors): Clients should check the request for mistakes and correct them before retrying.

5xx (Server Errors): Consider retrying after a delay. Implement a back-off mechanism, like exponential backoff or jitter, to increase the delay between retry attempts.

Send Card Information

API Reference

Send card

💡
Important!

Endpoint

Request fields

Response Status Codes

200: Success

400: Client Errors

Handling 3xx, 4xx, 5xx Status Codes

API Reference

Send card

💡Important!

Endpoint

Request fields

Response Status Codes

200: Success

400: Client Errors

Handling 3xx, 4xx, 5xx Status Codes

💡
Important!