Rapid Development

Activate the merchant Backend Portal

When getting official merchant ID, the merchant needs to confirm that an email for activating its merchant back-end portal account has been received in the registered mailbox when being onboarding, and through that email merchant needs to activate its corresponding account in time. The link in the activation email has expired time. If the link expires, please contact the business manager to re-send the activation email.

CFCA Certificate Downloading and Exporting

Please contact the business manager to apply for the CFCA certificatein timely, which is used for message encryption and decryption for all the interfaces' interconnection between merchant end and Geoswift end. Merchant will receive two letters after the application, one is for two-code notification and another one is for instruction manual. The validity period of the CFCA two-code email is 14 days. If the email expires or the certificate cannot be downloaded and installed due to other factors, please contact our tech support.

Precautions for message encryption and decryption

For data security , Geoswift's interface adopts two encryption methods, two signature methods and one sorting method: CFCA public key certificate encryption, AES encryption, SHA1 signature, CFCA private key certificate signature and key name initial alphabet sorting.

1. Certificate Usage Rule:

When merchant uses its own merchantId, the certificate should be used as follows: The exported public key certificate(.cer) needs to be uploaded to the merchant backend portal. The public key in the program should be the public key(.cer) in the SDK demo. The private key(.pfx) and private key password in the program should be replaced with the private key(.pfx) and private keypassword exported after issuing the certificate.

2. The encryption process

  1. Sort JSON data by key name initial, in which the function sorts the JSON data from a to z by initial of key name, then joint the keyvalue(except for the null value), the corresponding key values should be separated by #. (PS:’#’ is needed at the end of the string,not the beginning.) Sample: 1#2#3#
  2. SHA1 signature
  3. Use the downloaded and exported CFCA private key(.PFX) to sign the digest in Step 2 and then set it as the HMAC value
  4. Generate a 16-bit random number as the key of the AES encryption
  5. Use the AES key in step 4 to encrypt the JSON string with HMAC value from step 3
  6. Use the CFCA public key(.Cer file) provided in the Geoswift SDK demo to encrypt the AES key from Step 4
  7. Set the ciphertext completed in step 5 into the request body
  8. Pass the value of the "merchantId," the "requestId," and the "encryptKey"(The value of the encrypted AES key from step 6) into the request header
  9. Request interface with HTTP POST method

3. Decryption Process

The return data and the request data are in the same format, and the "decryption" and the "signature verification" will be carried out in accordance with the reverse way of the encryption process.

  1. Receive the POST request, thus obtaining the encryptKey from the return header and the data from the return body
  2. Decrypt the encryptKey from step 1 using the private key (.pfx) so as to get the value of the 16-characters AES key
  3. Use the AES key to decrypt the return body
  4. Remove HMAC from the original data (JSON string) obtained in step 3, then sort the key names in A-Z order, and concatenate the corresponding keys' values with #; sample: 1#2#3# (add "#" to the end of the string; Null value not included in signature)
  5. SHA1 signature
  6. Verify the HMAC's value of the decrypted JSON string using the CFCA public key (.cer) provided in the Geoswift SDK demo in order to compare wth result from step 5 for ensuring the date has not been.

4. Attention points