API Reference

Building the JWE

We will generate a private and public key for you.

JWE specifications:

RSA 2048 certificate in JWK format
RSA-OAEP-256 as key encryption algorithm
A256GCM as content encryption algorithm

The JWE value should be a JSON string with this structure:

{
    "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"
    }
}

Send card

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

Endpoint

POST https://development.knotapi.com/card

Request fields

Field Name	Type	Description
session_id	required, string	The `session_id` property available in the `AUTHENTICATED` webhook.
task_id	required, number	The `task_id` property available in the `AUTHENTICATED` webhook.
jwe	required, string	The JWE value.

curl -X POST 'https://development.knotapi.com/card' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "session_id": "915efe72-5136-4652-z91q-d9d48003c102",
    "task_id": 408321,
    "jwe": "ey..."
  }'

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_INPUT",
    "error_code": "INVALID_JWE",
    "error_message": "invalid jwe",
    "display_message": null
}

Missing Field:

{
    "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.

Development

Before initiating a card switch, Knot needs certain details like card information, billing details, and the session_id and 'task_id that was returned in the AUTHENTICATED webhook. For the sake of development, you can skip waiting for the AUTHENTICATED webhook, and use the /card/test endpoint to skip needing the information obtained from the webhook. This endpoint can only be used in development.

Endpoint

https://development.knotapi.com/card/test

Request fields

Field Name	Type	Description
jwe	required, string	The JWE value.

curl -X POST 'https://development.knotapi.com/card/test' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "jwe": "ey..."
  }'