Send Card (JWE)

If desired, Knot allows you to send card information using JWE.

API Reference

Retrieving the JWK

The/jwe/key endpoint returns your JWE public key, which encrypts your payload.



You'll have up to 15 seconds to send this request after receiving the AUTHENTICATED webhook.


curl -X GET '' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Knot-Version: 2.0'

Response Status Codes

200: Success

The request was successful.


Building the JWE

Using your JWE public key you can encrypt the payload.

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"


Card Expiration format

The format of the expiration can be MM/YYYY or MM/YY.

Send card

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



Request fields

Field NameTypeDescription
task_idrequired, numberThe task_id property available in the AUTHENTICATED webhook.
jwerequired, stringThe JWE value.
curl -X POST '' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "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.


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