Onramp Web Hosted SDK and KYC
User Flow
The user needs to follow a series of steps on the client platform to purchase crypto as given below:
Onramp Hosted SDK
Saber’s Hostel SDK can be integrated by following the below mentioned steps. The integration is done in two steps:
- Sandbox Testing: Initial testing of integration
- Production: Final integration for going live
The steps to integrate are SDK are highlighted below:
The overall integration includes two major areas:
- User Registration: Creation of user on Mudrex’s system and generate a UUID for the user for payment processing
- Payment Initiation: Generation of URL for payment where the user needs to be redirected for Onramp
User Registration
The user registration part contains the following steps:
Steps to Register a User
To be able to make payments a user has to be first registered with Mudrex. To register a user on Mudrex you need to follow the steps:
- Generate a secret key for user registration using the following script
var timestamp = Math.floor(Date.now() / 1000).toString();
var sigString = clientId + timeInSeconds;
var secret = CryptoJS.HmacSHA256(sigString, clientSecrect).toString().toUpperCase();
- Use this API endpoint to register a user
Method | URL |
---|---|
POST | {base_url}/api/v1/user/client_user |
Headers | Description | Values |
---|---|---|
X-Timestamp | Timestamp used to generate the secret | string |
X-Client-Id | Client ID provided by Mudrex | string |
X-Secret-Key | The secret key generated in the first step | string |
X-Request-Id | For client reference (can be anything) | string |
Sample Request and Response
curl --location 'https://mudrex.com/api/v1/user/client_user' \
--header 'X-Timestamp: {{timestamp}}' \
--header 'X-Client-Id: •••••••' \
--header 'X-Secret-Key: •••••••' \
--header 'X-Request-Id: 123456789876' \
--data-raw '{
"user_uuid": "77c4562e-ce47-4054-9d4e-4df69ca61ac2",
"client_user_id": "Abhishek-TestAcc",
"email": "kk@mail1.com",
"phone":"8734567891"
}'
{
"success": true,
"data": {
"client_user_id": "",
"user_id": "d57626e7-d6f3-44e0-bc82-12c5f42843af"
}
}
Payment Initiation
Post user registration, URL needs to be generated for payment where the user will be redirected
Buy Quote API
Method | URL |
---|---|
GET | https://mudrex.com/api/v2/wallet/w/quote?from_currency=INR&to_currency=USDT&network=MATIC&to_amount=55.38 |
Headers | Description | Values |
---|---|---|
X-Timestamp | Timestamp used to generate the secret | string |
X-Client-Id | Client ID provided by Mudrex | string |
X-Secret-Key | The secret key generated in the first step | string |
X-Request-Id | For client reference | |
X-User-Id | UUID of the user | string |
Params | Description |
---|---|
from_currency | Fiat currency (INR for Indian Rupees) |
to_currency | Crypto currency (USDT) |
network | Network for transaction |
to_amount | Crypto Amount (USDT) |
from_amount | Fiat Amount (INR) |
Sample Request:
curl --location 'https://mudrex.com/api/v2/wallet/s/quote?from_currency=INR&to_currency=USDT&network=BSC&to_amount=55.38' \
--header 'X-Timestamp: {{timestamp}}' \
--header 'X-Client-Id: •••••••' \
--header 'X-Request-Id: 3456' \
--header 'X-User-Id: •••••••' \
--header 'X-Secret-Key: •••••••'
Sample Response:
{
"success": true,
"data": {
"from_currency": "INR",
"to_currency": "USDT",
"from_amount": 5036.81,
"pre_fee_to_amount": 55.49,
"to_amount": 55.38,
"base_price": 90.77,
"final_price": 90.95,
"total_fee": 0.11,
"fee_currency": "USDT",
"fee_breakup": {
"platform_fee": 0.111,
"network_fee": 0,
"client_fee": 0,
"discount": 0,
"tax_on_fee": 0,
"tds": 0
}
}
}
Steps to Initiate Payment
To generate a payment URL for the user where he must be redirected, follow these steps:
- Generate a secret key for payment using the following script. Please note that this script is slightly different from the one used at the time of user registration
var timestamp = Math.floor(Date.now() / 1000).toString();
var sigString = clientId + timeInSeconds + "sdk" + user_id;
var secret = CryptoJS.HmacSHA256(sigString, clientSecrect).toString().toUpperCase();
- Pass the following parameters as URL params to the base payment URL
Parameters | Description | Sample Value |
---|---|---|
client_id | Client ID provided by Mudrex | d951b040-ecb0-432b-ae3c-2ae7d2d19987 |
user_id | A UUIDv4 unique identifier for the user-generated by the client during user registration | d951b040-ecb0-432b-ae3c-2ae7d2d19987 |
timestamp | The timestamp of the payment request (used at the time of creating the secret) | 1687276964 |
secret | The secret generated by the client in previous step to authenticate the request | CE1B5BD087BA408C2AFF01B00595007858DF496D3468CE3307CB1A7966DDC265 |
Sample URL
Payment URL Customization
If you wish to customize the integration with Mudrex Onramp, you can add query parameters to the URL. This allows you to set specific options according to your requirements. Check sample URL for example.
Parameters | Description | Sample Value |
---|---|---|
crypto_symbol | This is the unique identifier of the cryptocurrency. Currently, we support USDT | USDT |
network | This is the network on which you want to withdraw the cryptocurrency. Currently supported networks include: BSC, BNB, ETH, MATIC TRX, ARB | MATIC |
wallet_address | This is the on-chain wallet address to which the cryptocurrency will be withdrawn. | 0x5ccff9cf986079c6d6f2187c3dc4bd9ba9834a9k |
crypto_amount | This is the amount denoted in the native coin/token. Please note that either crypto_amount or fiat_amount can be passed, and if both are provided, fiat_amount takes precedence. | 100 |
fiat_amount | This is the amount denoted in fiat currency (currently only INR is supported). | 10000 |
payment_method | The type of method the user would choose to pay with. Supported payment methods: - bank_transfer - upi_transfer | bank_transfer |
transaction_id | A UUID16 identifier passed by the client (optional). The client will receive webhooks with same transaction_id | |
fiat_currency | This is the fiat currency the user wants to pay (currently only INR is supported). | INR |
redirect_url | This is the URL to which the user will be redirected after a successful transaction. This parameter is applicable only in hosted mode. |
Webhooks
The following webhooks can be received by the client for obtaining status of the order as given below:
Status | Description | Sample Value |
---|---|---|
‘CREATED’ | Triggered when the user confirms to have made the payment (click on ‘I have transferred’ CTA) | {'failure_code': None, 'crypto_symbol': 'USDT', 'exchange_rate': '85.00000000', 'status': 'CREATED' , 'id': '146b37f1-26b5-411d-ae49-a4b6d3aa17f3', 'network': 'BSC', 'fiat_amount': '850.00000000', 'crypto_wallet_address': '0xe7cdF59Db5202f970607E19dd9921A711D377Afc', 'tag': None, 'failure_desc': None, 'payment_method': 'upi_transfer', 'crypto_amount': '10.00000000', 'fiat_symbol': 'INR', 'created_at': 1702540033000, 'source_id': '37f7cfcb-4890-471d-9f37-aa762db3eba9', 'event': 'CRYPTO_BUY', 'user_id': '7970d2d2-401b-4322-9672-c03f051dedc0'} |
'ONRAMP_INITIATED' | Triggered immediately once the payment reconciliation process is triggered. | {'payment_method': 'upi_transfer', 'source_id': None, 'tag': None, 'exchange_rate': '84.99000000', 'failure_code': None, 'fiat_amount': '2299.00000000', 'created_at': 1694714157000, 'id': 'e4606ddb-8e63-4822-8be9-4698bb14174c', 'fiat_symbol': 'INR', 'failure_desc': None, 'crypto_symbol': 'USDT', 'network': 'MATIC', 'crypto_wallet_address': '0x466fA637cEB624F9d14fC470c509a818410768FD', 'crypto_amount': '27.05000000', 'status': 'ONRAMP_INITIATED', 'event': 'CRYPTO_BUY' , 'user_id': '11030590-8f27-4325-8db6-c3bb38ba4bf3'} |
'ONRAMP_COMPLETED' | Triggered when the user’s payment is successfully reconciled. | {'payment_method': 'upi_transfer', 'source_id': None, 'tag': None, 'exchange_rate': '84.99000000', 'failure_code': None, 'fiat_amount': '2299.00000000', 'created_at': 1694714157000, 'id': 'e4606ddb-8e63-4822-8be9-4698bb14174c', 'bank_transaction_id': '325795572402', 'fiat_symbol': 'INR', 'failure_desc': None, 'crypto_symbol': 'USDT', 'network': 'MATIC', 'crypto_wallet_address': '0x466fA637cEB624F9d14fC470c509a818410768FD', 'crypto_amount': '27.05000000', 'status': 'ONRAMP_COMPLETED', 'event': 'CRYPTO_BUY' , 'user_id': '11030590-8f27-4325-8db6-c3bb38ba4bf3'} |
'COMPLETED' | Triggered when the crypto withdrawal to client’s specified wallet address in completed | {'payment_method': 'upi_transfer', 'source_id': None, 'tag': None, 'exchange_rate': '84.99000000', 'failure_code': None, 'fiat_amount': '2299.00000000', 'created_at': 1694714157000, 'id': 'e4606ddb-8e63-4822-8be9-4698bb14174c', 'bank_transaction_id': '325795572402', 'fiat_symbol': 'INR', 'failure_desc': None, 'crypto_symbol': 'USDT', 'network': 'MATIC', 'crypto_wallet_address': '0x466fA637cEB624F9d14fC470c509a818410768FD', 'crypto_amount': '27.05000000', 'status': 'COMPLETED', 'event': 'CRYPTO_BUY' , 'user_id': '11030590-8f27-4325-8db6-c3bb38ba4bf3', ‘txn_hash’: ‘0x8bc46443e1bca3f32163d193466f216d2cc774093b8280483529b8c39957e53b’} |
'FAILED' | Triggered when user’s payment could not be found | {'failure_code': 'ONRAMP_FAILED', 'created_at': 1694631289000, 'exchange_rate': '84.99000000', 'fiat_amount': '300.00000000', 'tag': None, 'crypto_symbol': 'USDT', 'network': 'MATIC', 'source_id': None, 'failure_desc': 'Payment not received from the user', 'status': 'FAILED', 'fiat_symbol': 'INR', 'crypto_wallet_address': '0x9e706548D4443E0EdEa9a1B47AF251Ec0FF09B36', 'payment_method': 'upi_transfer', 'crypto_amount': '3.53000000', 'id': '1b824d4e-f5e5-4313-aa27-9ed67ed3d937', 'event': 'CRYPTO_BUY' , 'user_id': '4924280a-c703-47f2-a82d-78567b57cedc'} |
'ONRAMP_INCONSISTENT' | Triggered when a payment with different amount is found for the user. | {'crypto_amount': '0.57647100', 'fiat_symbol': 'INR', 'created_at': 1702202538000, 'crypto_wallet_address': '0x7ba0FF36f3bB47A0Bffd79D322CC71cFC5ddec92', 'fiat_amount': '49.00000000', 'status': 'ONRAMP_INCONSISTENT' , 'crypto_symbol': 'USDT', 'failure_code': None, 'failure_desc': None, 'payment_method': 'upi_transfer', 'tag': None, 'bank_transaction_id': '334463178476', 'source_id': None, 'network': 'MATIC', 'exchange_rate': '85.00000000', 'id': 'adedaad8-ed8d-4f9d-9241-3e0eef33f704', 'event': 'CRYPTO_BUY', 'user_id': '603da946-508a-412d-961a-393cbc65714b'} |
'REFUND_COMPLETED' | Triggered when user’s deposited amount is refunded. | {'bank_transaction_id': '334463178476', 'status': 'REFUND_COMPLETED' , 'created_at': 1702202538000, 'failure_desc': None, 'crypto_amount': '0.57647100', 'payment_method': 'upi_transfer', 'crypto_wallet_address': '0x7ba0FF36f3bB47A0Bffd79D322CC71cFC5ddec92', 'source_id': None, 'id': 'adedaad8-ed8d-4f9d-9241-3e0eef33f704', 'fiat_amount': '49.00000000', 'exchange_rate': '85.00000000', 'tag': None, 'failure_code': None, 'crypto_symbol': 'USDT', 'network': 'MATIC', 'fiat_symbol': 'INR', 'event': 'CRYPTO_BUY', 'user_id': '603da946-508a-412d-961a-393cbc65714b'} |
SDK Events
The client can received by the client from the SDK to get status of user actions as given below:
Event | Description | Sample Value |
---|---|---|
KYC_STATUS | Triggered when user completes their KYC | { |
ORDER_CREATED | Triggered when an order is created | { |
ORDER_UPDATED | Triggered when an order is updated, generally when a user updates their UTR manually. | { |
UPI_INTENT | Triggered when user attempts to pay via upi intent. url in payment can be used to trigger the intent url in cases where it doesn’t automatically get triggered. | { |
BACK | When user clicks back button in saber | { |
SUCCESS | Called when transaction is completed | { |
DIGILOCKER_URL | Called when digilocker url is generated. Can be used to navigate to the digilocker | { |
KYC Sharing
If the user has already completed KYC on client’s platform, the same data can be shared without the need for re-KYC. The steps are as follows:
The existing KYC data of user can be shared with Mudrex using this API Endpoint
Method | URL |
---|---|
POST | https://mudrex.com/api/v1/user/client_user/kyc |
Headers | Description | Values |
---|---|---|
X-Timestamp | Timestamp used to generate the secret | string |
X-Client-Id | Client ID provided by Mudrex | string |
X-Secret-Key | The secret key generated in the first step | string |
X-Request-Id | For client reference | |
X-User-Id | UUID of the user | string |
Example
curl --location 'https://mudrex.com/api/v1/user/client_user/kyc' \
--header 'X-Timestamp: 1709120158' \
--header 'X-Client-Id: 18e963ea-39fd-4a1b-b1e6-decbfe791d31' \
--header 'X-Secret-Key: <key>' \
--header 'X-Request-Id: 123456789876' \
--header 'X-User-Id: cbbb71b2-0dea-40d1-a7df-3bcdd62d1caa' \
--header 'Content-Type: application/json' \
--data-raw '{
"legal_name":"KARTIKEY AGARWAL",
"poi":"AWSPP1410L",
"poa":"500100111232",
"dob":"31-01-2000",
"gender":"M",
"income":"1,00,000-5,00,000",
"email":"kartikey@mudrex.com",
"phone":"8553383091",
"occupation":"professional",
"address":"my address is a addreess"
}'
As a second step, the documents corresponding to the data shared have to be shared through a document sharing API
Method | URL |
---|---|
POST | https://mudrex.com/api/kyc-services/v1/module/share/document |
Headers | Description | Values |
---|---|---|
X-Timestamp | Timestamp used to generate the secret | string |
X-Client-Id | Client ID provided by Mudrex | string |
X-Secret-Key | The secret key generated in the first step | string |
X-Request-Id | For client reference | |
X-User-Id | UUID of the user | string |
Example
curl --location 'https://mudrex.com/api/kyc-services/v1/module/share/document' \
--header 'X-Timestamp: 1709120158' \
--header 'X-Client-Id: 18e963ea-39fd-4a1b-b1e6-decbfe791d31' \
--header 'X-Secret-Key: 56C6CF9434D6D021B925A831C6105A38183CAB81D8C14F991B6132EFF7F1BBB7' \
--header 'X-Request-Id: 123456789876' \
--header 'X-User-Id: cbbb71b2-0dea-40d1-a7df-3bcdd62d1caa' \
--form 'live_image=@"/Desktop/live_image.png"' \
--form 'pan=@"/Downloads/1.4-KB-XML-File.xml"' \
--form 'aadhaar=@"/Downloads/1.4-KB-XML-File.xml"' \
--form 'passport=@"/Downloads/passport.png"' \
--form 'aadhaar_face_image=@"/Downloads/aadhaar_face_image.png"'