API Reference

Send card

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

🚧

Info

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.development.knotapi.com/card

Request fields

Field NameTypeDescription
task_idrequired, numberThe task_id property available in the AUTHENTICATED webhook.
user.name.first_namerequired, stringA string with at least one non-whitespace character, with a max length of 100 characters.
user.name.last_namerequired, stringA string with at least one non-whitespace character, with a max length of 100 characters.
user.phone_numberrequired, stringThe user's phone number in E.164 format.
user.address.streetrequired, stringThe primary street portion of an address. If the user has submitted their address, this field will always be filled.
user.address.street2stringExtra street information, like an apartment or suite number.
user.address.cityrequired, stringCity from the end user’s address.
user.address.regionrequired, stringAn ISO 3166-2 sub-division code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
user.address.postal_coderequired, stringThe postal code for the associated address. Between 2 and 10 alphanumeric characters.
user.address.countryrequired, stringValid, capitalized, two-letter ISO code representing the country of this object. It must be in ISO 3166-1 alpha-2 form.
card.numberrequired, stringA valid card number without spaces or hyphens.
card.expirationrequired, stringA string with the card expiration in MM/YYYY format. (e.g. 08/2027).
card.cvvrequired, stringA Valid security code, between 3 and 4 digits.
curl -X POST 'https://secure.development.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.


What’s Next