app_id and app_secret), which is used to obtain the accessToken and 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.
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.accessToken and include it in the request header Authorization (fill in the token directly, without the Bearer prefix). This step is required for both v1 and v2.| Account | Available Versions |
|---|---|
| Opened before 2026-10-30 and merchant public key configured | v1 or v2 |
| Opened before 2026-10-30 but merchant public key not configured | v2 only |
| Opened on or after 2026-10-30 | v2 only |
If you are not sure which case applies to you, please contact your account manager. v2 is recommended for new integrations. Users already integrated with v1 can switch to v2 directly: use your existing app_idandapp_secret, no need to apply for a new API account. v1 and v2 can be used at the same time.
| Item | v1 | v2 |
|---|---|---|
| API path | /{api}, e.g. /cardDetail | /v2/{api}, e.g. /v2/cardDetail |
| IP whitelist | Required | Not required |
| Merchant public/private keys | Must be generated, and the merchant public key configured in the console | Not required |
| Request format | Business parameters encrypted with the VM public key and placed in {"content": "ciphertext"} | Plaintext JSON submitted directly |
Response data | Encrypted string, decrypted with the merchant private key | Plaintext JSON object |
| Sandbox environment | Supported | Supported (also with the /v2 prefix) |
| accessToken | Required | Required |
| API fields | Same | Same |
| Webhook push and signature verification | Same | Same |
X-Client-Request-Id de-duplication | Same | Same |
app_id and app_secret (no IP whitelist and no merchant public key required).GET /v2/getAccessToken?app_id=xxx&app_secret=xxx to obtain the accessToken.Authorization request header and submit plaintext JSON in the request body.https://sandbox-api.vmcardio.com/ (see Environment Configuration for production)POST https://sandbox-api.vmcardio.com/v2/cardDetail
Authorization: <accessToken>
Content-Type: application/json
{
"vm_card_id": "v4Qg*************HHSfg"
}{
"code": 0,
"msg": "ok",
"data": {
"card_id": "card190202408301611597******",
"vm_card_id": "v4Qg*************HHSfg",
"status": "ACTIVE"
}
}Some fields are omitted in the response example. See each API page for the full fields.
api_private.pem as your API RSA private key):openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096api_public.pem as your API RSA public key):openssl rsa -in api_private.pem -out api_public.pem -puboutSaving 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-----body = {'param1': 'value1', 'param2': 'value2'}.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.content.{'content': content} to the corresponding API endpoint.{'code': 0, 'msg':'ok', 'data': 'encrypted data'}. Parameter, authentication, or decryption error responses are plaintext, and data does not need to be decrypted.data field from the response.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 merchant private key string. See the example below for the decrypt_data_with_private_key function (with padding using PKCS#1 v1.5).encrypt_data_with_public_keydata: The data to be encrypted, which should be a serializable object, typically a dictionary.public_key_str: The public key string.RSA.import_key method to load the provided public key string.PKCS1_v1_5 encryption method to encrypt the byte-encoded JSON string.decrypt_data_with_private_keyencrypted_data: The hex-encoded encrypted data string.private_key_str: The private key string.RSA.import_key method to load the provided private key string.PKCS1_v1_5 decryption method to decrypt the Base64 decoded data.PKCS#1 v1.5 padding during encryption.vm_public_key_str with the platform public key provided by VM, and merchant_private_key_str with your own merchant private key. Note: requests are encrypted with the VM public key and responses are decrypted with the merchant private key; they are not the same key pair.https://sandbox-api.vmcardio.com/Sample Business Request Parameters Before Encryption
{
"card_id": "341916e58af445f8aadeb95*******"
}
Use the VM public keyto encrypt the data, and place the encrypted data under thecontentfield.
{
"content": "434a7454477a7147757145315930652b4a733141724f5162797745496771514b474a6d6f554e58766b2f4b6f34467058474d4c6461445a7a386573636d39466836436d576b31756672427a6d6e62747a5470622b575a542b2b30687a735a46734a33476678425549664f31344f6d496d58485254627533676b43754a46674f41454367424d4970734a425642693535674e596b497146565a73434e7848696a6f622b56384a2f73324f6c5a514679746b674137546e363248772b2b4f4c7575724d366c7253704e33454467797537427a483135534e4b4835554d57576c775a376543663469506935414f7a524c64656d627a3674332f57775a5467653644354f482b326b4f50644756484f5135476364474477393553365550624c2f4f5363787a2f51544432346e2f426d5544643549344474346e734b2f4e33626b535a642b4c7654646757537a66654c414c6e464d6f49764b59513d3d"
}{
"code": 0,
"msg": "ok",
"data": "6f334f787a6c456c6173486f7236376757544a31676a47702b536b684b6972336f58454e67383459367039327433643770746337413739526b4361554f66472b586d7730585a5167304c30494d526839465664445376624c502f76716b7775392f306473733741557a7264666c576741796164344778562b505238714d456e57776f422b4a7a4d4e5a42354350774f312f786d53615737516a6d44386b493764576331534c7a6d61674c5332463978624e416577564371543462627554656c497577315a72575477534b4d55486748486f77326b544b7856704e454e45505341504e47752b57616a575733633041697a6b6e3330544a44656a42485a2f6a33304a462b7a593645716d666e2b6f764f69732f4a636e46385a4f574c797350573161334638555857663157304f4d656b6c445434546f536a545464656a5338505138665949327a5937543578465250384d4d627056634d32436f647941314643506a456d433265367359572f4f7566377368506a6a756372623739745068636d61516669536b306d30594b765065664f492f6f793555314f765031764747466369476550705962597a396f584566754162516759306d75524e70614e51757163505945534544724a4b6d595043566832445559464d626c5a39754d424577745270744b34576b2b66756f6b3172626a7954656b376564627a65446673636f4e4854664c7861363150556b6c7673596f52436f505068786a31634558795164546445333968354c4b366438676370716f6c525735586b3250656b6b4f67527a4c6e476c6e6754443437767a374730504c634755636c366446626f3978447043344e5571744c4c6f74582f54496d78645a7842344c52506f7735424d4573336d58612b4949564d37576f63583563494533793750766c784c52334c426f4249416d6f386b74524b396f39316b54383d"
}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-*********"}