Advanced
Kado offers additional authenticated API routes for partners that choose to undergo some additional setup. If the authenticated route offerings interest you, please reach out to partners@kado.money to kick off your advanced API integration.
Authentication 🔐
Kado utilizes Hash-Based Message Authentication Codes (HMAC) to ensure that incoming messages are authenticated, and that message integrity is maintained throughout the data transit process.
To get started making authenticated requests to Kado, you will first need to obtain your public and private server-to-server API keys from Kado.
👉 Once Kado issues you those, you will need to attach the following headers to authenticate your requests:
X-Timestamp
- current UTC timestamp (milliseconds)X-Public-Key
- The public key obtained from KadoX-Signature
- Computed as follows:method
= HTTP method (i.e. "GET", "POST", etc.)timestamp
= current UTC timestamp (milliseconds)path
= API route excluding base url (i.e. "/v2/ramp/quote")payloadHex
= MD5-hashed payload (after removing whitespace).This should be empty if the
Content-Type
is notapplication/json
and the method is notPOST
.Calculated in Postman:
CryptoJS.MD5(CryptoJS.enc.Utf8.parse(JSON.stringify(JSON.parse(payload)))).toString(CryptoJS.enc.Hex); toSign
=method
+timestamp
+path
+payloadHex X-Signature
=CryptoJS.HmacSHA256(toSign, privateKey)
Webhooks 📨
For convenience, Kado provides webhook updates throughout the fulfillment process for on and off-ramp orders.
Getting Started with Kado Webhooks
Create an API endpoint that can ingest a Kado webhook. Kado will POST to this API route, with the data specified in the following section. Your API route should promptly return a 200 response back to our server.
Once your API route is up and running, notify your point of contact at Kado of the URL API endpoint you've created and Kado will enable it for you.
Kado Webhook Data Structure
A typical webhook contains the following fields:
id
- The unique identifier for the webhook.resource
- The resource for which the webhook was sent.type
- The type of event which triggered the webhook.data
- The associated data. For ramp orders, this will be the same data that can be obtained in the order status route.message
- Description of the event.
Kado Webhook Data Reference
id | resource | type | data | message |
---|---|---|---|---|
| order | order_pending |
| Order is pending crypto trade |
| order | order_processing |
| Order is disbursing funds |
| order | order_completed |
| Order is complete |
| order | order_failed |
| Order has failed |
👉 Kado Webhook Demo: POST https://my-api.com/kado
Verifying Webhook Integrity
Kado provides additional headers on webhook posts, that your server can use to verify that incoming payloads are indeed coming from Kado, and have not been tampered with. This is just the client side version of the API Authentication Scheme, including all three headers described there: x-timestamp
, x-public-key
and x-signature
.
To verify the incoming payload, check that:
The
x-timestamp
is recent.The
x-public-key
matches your organization public key.Compute your own HMAC signature from the incoming request based on the method described in the API Authentication Scheme, and ensure that your computed signature matches the incoming
x-signature
header.
KYC, User Onboarding 🥸
The first step in the KYC process is uploading user information:
Initialize User KYC
POST
https://api.kado.money/v1/partner/kyc/submit
Submit KYC data to Kado
Request Body
Name | Type | Description |
---|---|---|
firstName* | String | First Name |
middleName | String | Middle Name |
lastName* | String | Last Name |
phone* | String | Phone Number Example: "+15183334444" |
email* | String | |
address* | String | { "street1": "street2": "postalCode": "state": "country": } |
dateOfBirth* | String | Example: "1992-01-01" |
ssn | String | 9-digit tax ID (US-required) |
Once user information is uploaded, grab the userId
from the KYC initialization step, and upload identity documentation for that user:
Upload Identity Documents
POST
https://api.kado.money/v1/partner/kyc/:userId/upload-docs
Upload identity documents to complete KYC information gathering process. The request data in the body should be of the type form-data
:
Path Parameters
Name | Type | Description |
---|---|---|
userId* | String | The user's Kado ID |
Request Body
Name | Type | Description |
---|---|---|
documentType* | String | "license", "identificationCard", "passport" |
documentFront* | File | Image file of the front of the ID document |
documentBack | File | Image file of the back of the ID document (if applicable) |
profileImage | File | Profile image collected during liveness checks |
Once KYC information and documentation are uploaded, we only need to monitor the KYC status while we wait for a user to become verified with the L2
status:
Get KYC Status
GET
https://api.kado.money/v1/partner/kyc/:userId
Obtain the KYC status of the user.
L0
means initial information has not been submitted, or there was a problem with the initial validation.
L1
means we are awaiting approval.
L2
means the user is fully KYC'd.
Path Parameters
Name | Type | Description |
---|---|---|
userId* | String | The user's Kado ID |
User Ref, Data Linking 🔗
For some partners, it may be useful to pass along each user's ID from their own system to the Kado Widget. By passing the userRef
query-string parameter to the Kado Widget URL, Kado can store that user reference upon user sign-in, to link a Client reference to a Kado user, for a Clients future use.
👉 Add to your query-string when loading the Kado iFrame or Webview ?userRef=c6e2e802-edfb-4478-9ae9-33fae16b7c0a
Simply put, integrators are able to pass an internal user ID to Kado, which Kado will then reference during subsequent API requests instead of the Kado userId
, for example:
GET
userRef
KYC StatusGET
userRef
Fiat or Asset Deposit InstructionsGET
userRef
Order HistoryParse and updated internal DB based on Webhook data
etc.
Last updated