Overview

Please log in with a user account that has API management permissions to the VM console. Navigate to the Personal Center -> Developer tab to configure Webhooks and create API accounts. After successfully creating an API account, you can use the API Key to access the VM API.

Important Notes

The API can only manage cards created through the API!!!

Authentication

The accessToken is used to authenticate the user and allow operations on the API. All APIs use the accessToken as the authentication mechanism for client requests. Your access token should always be kept confidential and secure.
When making a request, you need to first obtain the accessToken and include it in the request header Authorization.

Generating Public and Private Keys

You can use OpenSSL to generate the RSA private key (api_private.pem as your API RSA private key):
openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096
Use OpenSSL to generate the corresponding public key for the RSA private key (api_public.pem as your API RSA public key):
openssl rsa -in api_private.pem -out api_public.pem -pubout

Saving Merchant Public Key.You must include both the header and footer when saving the key.
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA6v8JgHmwJS1gK1IR9jpb
fHD+mEEwAteV13pmM94ribQELnhbQegvmH/aCDg7nkIZasyQ5H3mfNa1Fuv6IATY
9Of58gA9TEUkcxzV0JrT0zVpkxmCaejUVA63gi6AVqQZWn4YqRBAqzVzgq4CpOG+
dGTXy/GS62+EdDvF3jrhPcECAwEAAQ==
-----END PUBLIC KEY-----

RSA Encryption and Decryption for API Interaction

1. Request Encryption Process

During the API request, the request parameters must be encrypted.

First, use the RSA algorithm to encrypt the request parameters. Assume the request parameters are a dictionary like body = {'param1': 'value1', 'param2': 'value2'}.

Call the encryption function encrypt_data_with_public_key(body, public_key_str), where public_key_str is the known VM platform public key string. See the example below for the encrypt_data_with_public_key function.

After encryption, you obtain the string content.

Finally, send the dictionary {'content': content} to the corresponding API endpoint.

2. Response Decryption Process

The response data from the API is {'code': 0, 'msg':'ok', 'data': 'encrypted data'}.

Retrieve the encrypted data field from the response.

Use the RSA decryption algorithm to decrypt the data. Call the decryption function decrypt_data_with_private_key(encrypted_data, private_key_str), where encrypted_data is the encrypted data from the response and private_key_str is the known private key string. See the example below for the decrypt_data_with_private_key function (with padding using PKCS#1 v1.5).

After decryption, you obtain the defined JSON structure.

Decode the decrypted JSON string to obtain the final data structure.

3. Encryption and Decryption Function Explanation

(1) Encryption Function

Function Name: encrypt_data_with_public_key

Description: Encrypts data using the given public key string.

Input Parameters:

data: The data to be encrypted, which should be a serializable object, typically a dictionary.

public_key_str: The public key string.

Process:

Load the public key: Use the RSA.import_key method to load the provided public key string.

Convert data: Convert the input data to a JSON string.

Encrypt data: Use the PKCS1_v1_5 encryption method to encrypt the byte-encoded JSON string.

Base64 encode: Base64 encode the encrypted data.

Hex encode: Hex encode the Base64 encoded data and return the result.

(2) Decryption Function

Function Name: decrypt_data_with_private_key

Description: Decrypts encrypted data using the given private key string.

Input Parameters:

encrypted_data: The hex-encoded encrypted data string.

private_key_str: The private key string.

Process:

Hex decode: Decode the input hex-encoded string.

Base64 decode: Base64 decode the decoded hex data.

Load the private key: Use the RSA.import_key method to load the provided private key string.

Decrypt data: Use the PKCS1_v1_5 decryption method to decrypt the Base64 decoded data.

Convert data: Try to convert the decrypted byte data into a JSON string and parse it as a dictionary.

Important Notes:

Some programming languages may encounter issues with long ciphertext during decryption, in which case the ciphertext must be decrypted in segments. Ensure that the padding method is consistent when decrypting in segments, as the API uses PKCS#1 v1.5 padding during encryption.

4. Usage Example

Here is a simple usage example demonstrating the encryption of request parameters and decryption of response data:

When using this in practice, make sure to replace your_public_key and your_private_key with actual public and private key strings. Additionally, ensure the data format is as expected and no errors occur during encryption and decryption.

Important Notes:

Ensure the correctness and matching of public and private keys.

Data format conversion during encryption and decryption may cause errors depending on the input data, so appropriate error handling is needed.

IP Whitelist

When calling the VM API, requests are only allowed from the IP addresses in your set whitelist. You must set the IP address from which the request will be made when creating the API Key, and changes will take effect after 10 minutes.

Request Example

Base Request URL

https://sandbox-api.vmcardio.com/

Request Parameters Before Encryption

Example of business request parameters before encryption

{   
	"apiKey": "341916e58af445f8aadeb95*******",
	"timestamp": "1623038312088",   
	"rsaType": "ECB_OAEP",   
	"aesType": "GCM_NOPADDING",   
	"bizContent": {     
		"page": 1,     
		"pageSize": 1   
	} 
 }

Request Parameters After Encryption

{
      "apiKey": "341916e58af445f8aadeb95170******",
      "timestamp": "1628652100447",
      "bizContent": "qjFMZXs2n+CxnrNGoaZmGrKQzPosy6QbWEumCMkGOEw=",
      "key": "gYZvuXdJADuaLYMU3z8q5vOtld62PSaPxrrhhr4UGwWbZm7Pw3/VImzHrd3oNy1XT8R55V7pbpQOBVdbmTev/rESnuaXlGofkB04JWAaRCIPytEKMHUNXZXEU9GLVppYst7bgiekMDIDScS4AkD75eDG8zru5Gr+gTxU4AYyHSzB0deQnxmNRemwZn+jaNgNs7WeBcuQWR1Cq2+1At8FlAqF5XzEaeQ3x1Q0N3iaLzSiXHQRYqP1Q6V6/aiIXchin/X9bBRYL618utjm4k0qoXU8Rw2JeEKzn7m2ShyyQQ31zX/rQ1xf0ar5PDtJPU/qYp9Kr4oVtcN6yHdG802nLqpGYlHlMvxy9vpnGFXb9oxh4xYnp0qRUfKLyJIylc3qhq6spHyWnuC5XV1S4lH+rIPNF1icV08ex7pjps2jvTICBzIIPExBamh1n00RcxZbkGqxYfRZ7SLTUCH06EaV5lP8yXNe3fNWjHk4mppaVDj0QFagqTzBM9AwMfHs1dOeDmcwkTacKQsvNRu3l5uZFQYkaUeVB9m3AhKw3lyl2oJIfJgYeBLJEHMGFVZXP92z8+J5KrZEVfkL8F80XkB3sXRP0BiIv/9Mm4VrjopYoDWyXttCysY0lJ9XImRyE7GkSy2sjmW0BCsrECoVHWh73s9o7Kw0uIegFaitch24GsM=",
      "sig": "ZPQcL1aIxMrA6HTq7RWWS8FZS08zSOkS69WohcBw1bDr4Qv2Wkrp2t+PNHMh3TmDUnOmUOiv7mBs/sOw08rhgPHqAU/qtvc1lzJFFOnPp5MBmDgffD1auwm7icGzm3myhEz3hKePxyRgZWB1DpPmMYaRuWt1RYcVmcqRa/Bfd0jR37a35neuOSlaip4jsQE1pHQzQ6itdQhBtZZABl1Plz5u8OaMIDTVj63485zi/n6iuuav+GL+JX2JL6pnWz3CT/9DNqa/McyYbxGswGMBAPgHCptseELVmOQ3ZKNHgMu6EtXEKLzmLeZ5REwnw2MTvpzuy5B1zIuxiafuAhh6Tg==",
      "rsaType": "ECB_OAEP",
      "aesType": "GCM_NOPADDING"
    }

Integration Guide

Overview#

Authentication#

Generating Public and Private Keys#

RSA Encryption and Decryption for API Interaction#

1. Request Encryption Process#

2. Response Decryption Process#

3. Encryption and Decryption Function Explanation#

(1) Encryption Function#

(2) Decryption Function#

4. Usage Example#

IP Whitelist#

Request Example#

Base Request URL#

Request Parameters Before Encryption#

Request Parameters After Encryption#