概述

Vmcardio API 提供了完整的API能力，可通过API管理vmcardio VCC虚拟卡功能，完整使用发卡，卡管理，卡消费数据同步等功能。

请使用具有 API 管理权限的用户账户登录 VM 控制台，在个人中心 -> 开发者标签页进行 Webhook 配置与 API 账户创建，API 账户创建成功后，可以使用 API Key 来访问 VM API 。

如何申请API权限和集成流程：
1.
注册vmcardio.com 账户并完成必要认证，账户开通后联系客户经理或在线客服沟通业务场景和API使用需求。
2.
在个人中心-开发者菜单点击提交开通申请，提交后联系客服审批。
3.
注册sandbox账户用于集成测试（注册地址），注册后联系客服设置必要权限，设置成功后即可使用sandbox账户的API功能。如有技术问题，我们将通过群提供必要的技术支持。
4.
sandbox集成测试完成后，联系客服告知已测试完成，vmcardio将配置正式环境API权限，配置完成后即可迁移到正式环境正常使用API功能。

注意事项

API只能管理通过API创建的卡！通过用户后台手动创建的卡，无法通过API管理

认证

accessToken用于对用户进行身份验证，并允许访问API上的操作。所有API都使用accessToken作为认证客户端请求的机制。您的访问令牌应始终保密和安全。
请求时，需要先获取accessToken，并在请求头Authorization 添加上获取到的accessToken

生成公私钥

您可以使用 OpenSSL 生成 RSA 私钥（api_private.pem 为您的 API RSA 私钥）：
openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096
使用 OpenSSL 生成 RSA 私钥对应的公钥（api_public.pem 为您的 API RSA 公钥）：
openssl rsa -in api_private.pem -out api_public.pem -pubout

保存商户公钥例子 需要把头部和尾部都保存进来
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA6v8JgHmwJS1gK1IR9jpb
fHD+mEEwAteV13pmM94ribQELnhbQegvmH/aCDg7nkIZasyQ5H3mfNa1Fuv6IATY
9Of58gA9TEUkcxzV0JrT0zVpkxmCaejUVA63gi6AVqQZWn4YqRBAqzVzgq4CpOG+
dGTXy/GS62+EdDvF3jrhPcECAwEAAQ==
-----END PUBLIC KEY-----

RSA 加密和解密在接口交互中的对接文档

一、请求加密过程

在进行接口请求时，需要将接口请求参数进行加密处理。

首先，使用 RSA 算法对请求参数进行加密。假设请求参数是一个字典结构，如body = {'param1': 'value1', 'param2': 'value2'}。

调用加密函数encrypt_data_with_public_key(body, public_key_str)，其中public_key_str是已知的vm平台公钥字符串。encrypt_data_with_public_key函数见下方示例.

加密后得到字符串content。

最后，将包含加密内容的字典{'content': content}发送给对应接口。

二、响应解密过程

接口响应数据为{'code': 0, 'msg':'ok', 'data': '加密数据'}。

从响应数据中获取加密的data字段内容。

使用 RSA 解密算法对data进行解密，调用解密函数decrypt_data_with_private_key(encrypted_data, private_key_str)，其中encrypted_data是响应中的加密数据data，private_key_str是用户已知的私钥字符串。decrypt_data_with_private_key函数见下方示例。（其中填充方式使用PKCS#1 v1.5 填充）

解密后得到结构定义的结构体 JSON 串。

对解密后的 JSON 串进行 JSON 解码，得到最终可处理的数据结构。

三、加密和解密函数说明

（一）加密函数

函数名称：encrypt_data_with_public_key

功能描述：使用给定的公钥字符串对数据进行加密。

输入参数：

data：需要加密的数据，应为可序列化的对象，通常为字典等。

public_key_str：公钥字符串。

处理流程：

加载公钥：使用RSA.import_key方法加载传入的公钥字符串。

数据转换：将输入数据转换为 JSON 字符串。

加密数据：使用PKCS1_v1_5加密器对 JSON 字符串编码后的字节数据进行加密。

Base64 编码：对加密后的数据进行 Base64 编码。

十六进制编码：对 Base64 编码后的数据进行十六进制编码，并返回结果。

（二）解密函数

函数名称：decrypt_data_with_private_key

功能描述：使用给定的私钥字符串对加密数据进行解密。

输入参数：

encrypted_data：经过加密和编码后的十六进制字符串数据。

private_key_str：私钥字符串。

处理流程：

十六进制解码：对输入的十六进制字符串数据进行解码。

Base64 解码：对十六进制解码后的数据进行 Base64 解码。

加载私钥：使用RSA.import_key方法加载传入的私钥字符串。

解密数据：使用PKCS1_v1_5解密器对 Base64 解码后的数据进行解密。

数据转换：尝试将解密后的字节数据转换为 JSON 字符串，然后解析为字典并返回。如果转换或解析过程中出现错误，返回None。

注意事项

部分语言可能在解密中会出现需解密的部分过长的问题，这是时候需要将密文进行分段解密。api在加密的时候使用的是[PKCS#1 v1.5]的填充方式，在分段的时候注意分段的填充方式是否一致。

四、使用示例

以下是一个简单的使用示例，展示了接口请求加密和响应解密的过程：

在实际使用时，需要将your_public_key和your_private_key替换为实际的公钥和私钥字符串。同时，确保数据的格式符合预期，并且在加密和解密过程中没有出现错误。

注意事项：

确保公钥和私钥的正确性和匹配性。

加密和解密过程中的数据格式转换可能会因为输入数据的不同而产生错误，需要进行适当的错误处理。

IP 白名单

在调用 VM API 时，只允许从您设置的 IP 白名单地址发起请求，您需要在创建 API Key 时设置调用发起的 IP 地址，修改后会在10分钟之后生效。

请求示例

请求 base URL

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

加密前请求参数

加密前业务请求参数示例

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

加密后请求参数

使用vm公钥进行加密,并将加密后的数据放在content字段下

{
      "content": "434a7454477a7147757145315930652b4a733141724f5162797745496771514b474a6d6f554e58766b2f4b6f34467058474d4c6461445a7a386573636d39466836436d576b31756672427a6d6e62747a5470622b575a542b2b30687a735a46734a33476678425549664f31344f6d496d58485254627533676b43754a46674f41454367424d4970734a425642693535674e596b497146565a73434e7848696a6f622b56384a2f73324f6c5a514679746b674137546e363248772b2b4f4c7575724d366c7253704e33454467797537427a483135534e4b4835554d57576c775a376543663469506935414f7a524c64656d627a3674332f57775a5467653644354f482b326b4f50644756484f5135476364474477393553365550624c2f4f5363787a2f51544432346e2f426d5544643549344474346e734b2f4e33626b535a642b4c7654646757537a66654c414c6e464d6f49764b59513d3d"
}

响应数据

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

解密响应数据

1.
使用商户私钥对响应中的data数据进行解密,得到期望响应的字符串数据
2.
商户公钥需要提前配置到VM开发者配置中

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

接入指南

概述#

认证#

生成公私钥#

RSA 加密和解密在接口交互中的对接文档#

一、请求加密过程#

二、响应解密过程#

三、加密和解密函数说明#

（一）加密函数#

（二）解密函数#

四、使用示例#

IP 白名单#

请求示例#

请求 base URL#

加密前请求参数#

加密后请求参数#

响应数据#

解密响应数据#

概述

认证