Guides
Log In

Send Card (JWE)

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

Suggest Edits

API Reference

Retrieving the JWK

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

🚧

Info

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

Endpoint

GET https://development.knotapi.com/jwe/key

curl -X GET 'https://development.knotapi.com/jwe/key' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Knot-Version: 2.0'

Response Status Codes

200: Success

The request was successful.

{
   "alg":"RSA-OAEP-256",
   "e":"...",
   "key_ops":[
      "encrypt"
   ],
   "kid":"...",
   "kty":"RSA",
   "n":"...",
   "use":"enc"
}

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.

Endpoint

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

Request fields

Field NameTypeDescription
task_idrequired, numberThe task_id property available in the AUTHENTICATED webhook.
jwerequired, stringThe 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 '{
    "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.

Updated 15 days ago