Overview

Vmcardio API provides comprehensive API capabilities that allow full management of Vmcardio VCC virtual card functions, including card issuance, card management, transaction data synchronization, and more.

Please log in to the VM Console using an account with API management permissions, then go to Personal Center -> Developer tab to configure the Webhook and create API accounts. After the API account is created, you can use the API Key to access the VM API.

How to apply for API access and integration process:
1.
Register a vmcardio.com account and complete the required verification. After the account is activated, contact your account manager or online customer service to discuss your business scenario and API usage needs.
2.
In the Personal Center - Developer section, click to submit an application for activation, then contact customer service for approval.
3.
Register a sandbox account for integration testing (registration address). After registration, contact customer service to configure the necessary permissions. Once the setup is complete, you can use the sandbox account's API functions. If you encounter any technical issues, we will provide necessary technical support via the group.
4.
After completing sandbox integration testing, inform customer service. Vmcardio will then configure the production environment API access. Once configured, you can migrate to the production environment and use the API services normally.

Important Notes

The API can only manage cards created via the API. Cards manually created through the user dashboard cannot be managed via 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

Sample Business Request Parameters Before Encryption

{   
	"card_id": "341916e58af445f8aadeb95*******"
 }

Request Parameters After Encryption

Use the VM public key to encrypt the data, and place the encrypted data under the content field.

{
      "content": "434a7454477a7147757145315930652b4a733141724f5162797745496771514b474a6d6f554e58766b2f4b6f34467058474d4c6461445a7a386573636d39466836436d576b31756672427a6d6e62747a5470622b575a542b2b30687a735a46734a33476678425549664f31344f6d496d58485254627533676b43754a46674f41454367424d4970734a425642693535674e596b497146565a73434e7848696a6f622b56384a2f73324f6c5a514679746b674137546e363248772b2b4f4c7575724d366c7253704e33454467797537427a483135534e4b4835554d57576c775a376543663469506935414f7a524c64656d627a3674332f57775a5467653644354f482b326b4f50644756484f5135476364474477393553365550624c2f4f5363787a2f51544432346e2f426d5544643549344474346e734b2f4e33626b535a642b4c7654646757537a66654c414c6e464d6f49764b59513d3d"
}

Response Data

{
    "code": 0,
    "msg": "ok",
    "data": "6f334f787a6c456c6173486f7236376757544a31676a47702b536b684b6972336f58454e67383459367039327433643770746337413739526b4361554f66472b586d7730585a5167304c30494d526839465664445376624c502f76716b7775392f306473733741557a7264666c576741796164344778562b505238714d456e57776f422b4a7a4d4e5a42354350774f312f786d53615737516a6d44386b493764576331534c7a6d61674c5332463978624e416577564371543462627554656c497577315a72575477534b4d55486748486f77326b544b7856704e454e45505341504e47752b57616a575733633041697a6b6e3330544a44656a42485a2f6a33304a462b7a593645716d666e2b6f764f69732f4a636e46385a4f574c797350573161334638555857663157304f4d656b6c445434546f536a545464656a5338505138665949327a5937543578465250384d4d627056634d32436f647941314643506a456d433265367359572f4f7566377368506a6a756372623739745068636d61516669536b306d30594b765065664f492f6f793555314f765031764747466369476550705962597a396f584566754162516759306d75524e70614e51757163505945534544724a4b6d595043566832445559464d626c5a39754d424577745270744b34576b2b66756f6b3172626a7954656b376564627a65446673636f4e4854664c7861363150556b6c7673596f52436f505068786a31634558795164546445333968354c4b366438676370716f6c525735586b3250656b6b4f67527a4c6e476c6e6754443437767a374730504c634755636c366446626f3978447043344e5571744c4c6f74582f54496d78645a7842344c52506f7735424d4573336d58612b4949564d37576f63583563494533793750766c784c52334c426f4249416d6f386b74524b396f39316b54383d"
}

Decrypted Response Data

1.
Use the merchant's private key to decrypt the data field in the response to obtain the expected response string.
2.
The merchant's public key must be pre-configured in the VM developer settings.

{"card_id":"809c8dcc-1234-5678-abcd-*********"}

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#

Response Data#

Decrypted Response Data#