VM_API
    English
    • 简体中文
    • English
    • Integration Guide
    • Environment Configuration
    • Global Error Codes
    • Transaction Type Description
    • Card Status Description
    • VM Card operation V1 (only for accounts with a merchant public key configured before 2026-10-30)
      • Webhook Signature Verification
      • Get Account Balance
        POST
      • Get Card Product Code
        POST
      • Apply for Card
        POST
      • Card Details
        POST
      • Modify Card Limit(For credit line cards only)
        POST
      • Freeze/Unfreeze Card
        POST
      • Card Top-up(For prepaid cards only)
        POST
      • Card Refund(For prepaid cards only)
        POST
      • Transaction Records
        POST
      • Delete Card
        POST
      • Card List
        POST
      • Card Flow
        POST
    • VM Card operation V2 (available to all accounts, recommended)
      • Get Account Balance
        POST
      • Get Card Product Code
        POST
      • Apply for Card
        POST
      • Card Details
        POST
      • Modify Card Limit(For credit line cards only)
        POST
      • Freeze/Unfreeze Card
        POST
      • Card Top-up(For prepaid cards only)
        POST
      • Card Refund(For prepaid cards only)
        POST
      • Transaction Records
        POST
      • Delete Card
        POST
      • Card List
        POST
      • Card Flow
        POST
    • Notification
      • WebHook
      • Card 3DS Notification
    • Change Log
      • Change Log
    • FAQ
      • FAQ
    • Get accessToken
      GET
    • 数据模型
      • 示例数据模型
        • Pet
        • Category
        • Tag

    Integration Guide

    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 will receive an API Key (i.e. 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.
    Important Notes
    1.
    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 (fill in the token directly, without the Bearer prefix). This step is required for both v1 and v2.

    Version Selection#

    AccountAvailable Versions
    Opened before 2026-10-30 and merchant public key configuredv1 or v2
    Opened before 2026-10-30 but merchant public key not configuredv2 only
    Opened on or after 2026-10-30v2 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_id and app_secret, no need to apply for a new API account. v1 and v2 can be used at the same time.

    Differences Between v1 and v2#

    v2 is identical to v1 in API functions, request fields and response fields. The only difference is the integration process: v2 does not require an IP whitelist and does not require public/private key configuration. Both requests and responses are plaintext JSON.
    Itemv1v2
    API path/{api}, e.g. /cardDetail/v2/{api}, e.g. /v2/cardDetail
    IP whitelistRequiredNot required
    Merchant public/private keysMust be generated, and the merchant public key configured in the consoleNot required
    Request formatBusiness parameters encrypted with the VM public key and placed in {"content": "ciphertext"}Plaintext JSON submitted directly
    Response dataEncrypted string, decrypted with the merchant private keyPlaintext JSON object
    Sandbox environmentSupportedSupported (also with the /v2 prefix)
    accessTokenRequiredRequired
    API fieldsSameSame
    Webhook push and signature verificationSameSame
    X-Client-Request-Id de-duplicationSameSame

    v2 Integration#

    v2 integration takes only three steps:
    1.
    Create an API account in Personal Center -> Developer to obtain app_id and app_secret (no IP whitelist and no merchant public key required).
    2.
    Call GET /v2/getAccessToken?app_id=xxx&app_secret=xxx to obtain the accessToken.
    3.
    When calling business APIs, put the accessToken in the Authorization request header and submit plaintext JSON in the request body.

    Base Request URL#

    https://sandbox-api.vmcardio.com/ (see Environment Configuration for production)

    Request Example#

    POST https://sandbox-api.vmcardio.com/v2/cardDetail
    Authorization: <accessToken>
    Content-Type: application/json
    
    {
        "vm_card_id": "v4Qg*************HHSfg"
    }

    Response Example#

    {
        "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.

    v1 Integration (users who configured a merchant public key before 2026-10-30)#

    In addition to the v2 steps, v1 requires the following two items:
    1.
    Set up an IP whitelist;
    2.
    Generate merchant public/private keys and configure the merchant public key in the VM developer settings. Request parameters must be encrypted with the VM public key, and response data must be decrypted with the merchant private key.

    IP Whitelist#

    When calling the VM API (v1), 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.

    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 (v1 only)#

    1. Request Encryption Process#

    1.
    During the API request, the request parameters must be encrypted.
    2.
    First, use the RSA algorithm to encrypt the request parameters. Assume the request parameters are a dictionary like body = {'param1': 'value1', 'param2': 'value2'}.
    3.
    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.
    4.
    After encryption, you obtain the string content.
    5.
    Finally, send the dictionary {'content': content} to the corresponding API endpoint.

    2. Response Decryption Process#

    1.
    The response data from the API is {'code': 0, 'msg':'ok', 'data': 'encrypted data'}. Parameter, authentication, or decryption error responses are plaintext, and data does not need to be decrypted.
    2.
    Retrieve the encrypted data field from the response.
    3.
    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 merchant private key string. See the example below for the decrypt_data_with_private_key function (with padding using PKCS#1 v1.5).
    4.
    After decryption, you obtain the defined JSON structure.
    5.
    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:
    1.
    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, replace 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.
    Important Notes:
    1.
    Ensure the correctness and matching of public and private keys.
    2.
    Data format conversion during encryption and decryption may cause errors depending on the input data, so appropriate error handling is needed.

    v1 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-*********"}
    修改于 2026-11-04 08:31:54
    下一页
    Environment Configuration
    Built with