API Integration
Description
- The physical card API provides access to the underlying capabilities of the bank.
- Merchants need to handle token deposits themselves.
Environment Information
Test Environment: https://test-physicalcard-api.alchemypay.org
Production Environment: https://physicalcard-api.alchemypay.org
Document Description
1. Overview
This document provides explanations for third-party integration interfaces. Target audience: technical developers.
2. Common Interface Parameters
Field Name | Variable Name | Required | Type | Base64 Encoding | Description |
---|---|---|---|---|---|
Partner ID | agentId | Y | string | N | Partner ID assigned by the institution |
Request String | reqData | Y | string | N | Request RSA encrypted data, encoded after encryption with URLEncoder |
Language | language | N | string | N | zh, en |
Signature | signature | Y | string | N | MD5 signature string |
3. Common Interface Response
Field Name | Variable Name | Required | Type | Base64 Encoding | Description |
---|---|---|---|---|---|
Response Code | respCode | Y | string | N | 00: Success, Others: Failure |
Response Description | respMsg | N | string | N | Exists in case of failure |
Request String | respData | N | string | N | Response RSA encrypted data |
4. Interface Invocation Details
Interfaces typically include three request parameters: agentId, reqData, signature.
Signature Generation Rule
Convert the body to a JSON string + md5Key, then encrypt it using MD5.
For example:
str = {"name":"xxx","age":"18"}123453333
md5(str)
repData Generation Rule
Similarly, convert the body to a JSON string, then encrypt it using an RSA public key to obtain an encrypted string, and then base64 encode it.
For example:
def encrypt(message: str, pub_key: str) -> str | None:
try:
pubkey = rsa.PublicKey.load_pkcs1_openssl_pem(pub_key.encode())
message_bytes = message.encode()
chunks = [message_bytes[i:i + CHUNK_SIZE] for i in range(0, len(message_bytes), CHUNK_SIZE)]
crypto = b"".join([rsa.encrypt(chunk, pubkey) for chunk in chunks])
return base64.b64encode(crypto).decode()
except Exception as e:
print(f"Error encrypting message: {e}")
return None
Example of Usage
Note that the format should be application/x-www-form-urlencoded instead of application/json.
curl -X POST https://test.xxx.com/api/mastercard/holderQuery.html \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "agentId=888666000100201&reqData=2%2FCgBnwbtXQRR2XVmLu9uOiBCfjnd1pwq59LtPhufF6VtjbKcArfHE9Cqff575EFbIEBanPKlXbilnJj2Gz4AnEs1BOZOUEO85UIcD7YBBXdt1BC3vX8hzWXrsnPbC1ZW4589r7B40h0lL9NAOjs%2BJaDIN3nmpdqvFHJ4hF1rb0%3D&signature=e5c3ca8eba4de85f44262f8d34ac21ee"
Response Example
Normally, all interface data needs to be decrypted using an RSA private key when receiving data from the server.
{"respCode":"00","respMsg":"","respData":"nnTq5O+k89BsneEN1+SUKxj6PlNSsBzeF29IeEkNQjWrRATjW+dtYPONKFO9YfG5dlLg1qZH5PBRbEWB44Q9wmvT5PLoJNdM5Uk1zhhLQ0sJA186BSiwxwMYty0wgWgC6lsY4QQzuNR/aAsr8DxLR7vsTxaPB3m5qAzO8i7D/Xu22OX52CxxDeNizXwg1+0iyKU6S5AOEKCkF52iJY8OucVOt2sq9q1aX2wBijG12ZWyuh6iVHMtJxrxEOTYpp1h481ixBvt809hte2J26mn0hbWPW8v14X/LsS+5Mf5/0CcHm72tZ+EELyeDGI4TeZQeTw3Yf97KZfQ83cO15Ggzg=="}
Example of Decryption:
def decrypt(encrypted_data: str, private_key: str) -> str:
private_key_bytes = private_key.encode('utf-8')
encrypted_data = base64.b64decode(encrypted_data)
# Deserialize the private key from PEM format
private_key_obj = serialization.load_pem_private_key(private_key_bytes, password=None, backend=default_backend())
# Determine the appropriate chunk size based on the private key size
key_size_bytes = private_key_obj.key_size // 8 # Convert bits to bytes
decrypted_data = b""
# Decrypt the data in chunks based on the key size
for offset in range(0, len(encrypted_data), key_size_bytes):
chunk = encrypted_data[offset:offset + key_size_bytes]
decrypted_chunk = private_key_obj.decrypt(chunk, padding.PKCS1v15())
decrypted_data += decrypted_chunk
return decrypted_data.decode('utf-8')
Updated 12 months ago