Card (JWE)
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 AUTHENTICATED
webhook.
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..."
}'
Updated 22 days ago